earl-bot 0.1.0

data/lib/earl/memory/store.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Earl
+  module Memory
+    # Pure Ruby file I/O for reading, writing, and searching memory files.
+    # Manages markdown-based persistent memory in <config_root>/memory/
+    # with SOUL.md (personality), USER.md (user notes), and YYYY-MM-DD.md (daily episodic).
+    class Store
+      def self.default_dir
+        @default_dir ||= File.join(Earl.config_root, "memory")
+      end
+
+      def initialize(dir: self.class.default_dir)
+        @dir = dir
+      end
+
+      def soul
+        read_file("SOUL.md")
+      end
+
+      def users
+        read_file("USER.md")
+      end
+
+      def recent_memories(days: 7, limit: 50)
+        entries = collect_entries(days)
+        entries.last(limit).join("\n")
+      rescue Errno::ENOENT
+        ""
+      end
+
+      def save(username:, text:)
+        FileUtils.mkdir_p(@dir)
+        now = Time.now.utc
+        today = now.strftime("%Y-%m-%d")
+        path = File.join(@dir, "#{today}.md")
+        entry = "- **#{now.strftime("%H:%M UTC")}** | `@#{username}` | #{text}"
+
+        write_with_header(path, today, entry)
+        { file: path, entry: entry }
+      end
+
+      def search(query:, limit: 20)
+        pattern = Regexp.new(Regexp.escape(query), Regexp::IGNORECASE)
+        grep_files(pattern, limit)
+      end
+
+      private
+
+      def collect_entries(days)
+        paths = date_files_descending(days)
+        paths.flat_map { |path| entries_from_file(path) }
+      end
+
+      def entries_from_file(path)
+        File.readlines(path).filter_map do |line|
+          stripped = line.strip
+          stripped unless stripped.empty? || stripped.start_with?("#")
+        end
+      end
+
+      def grep_files(pattern, limit)
+        search_files.each_with_object([]) do |path, matches|
+          file_matches = matches_in_file(path, pattern)
+          matches.concat(file_matches)
+          break matches if matches.size >= limit
+        rescue Errno::ENOENT
+          next
+        end.first(limit)
+      end
+
+      def matches_in_file(path, pattern)
+        basename = File.basename(path)
+        File.readlines(path).filter_map do |line|
+          { file: basename, line: line.strip } if pattern.match?(line)
+        end
+      end
+
+      def read_file(name)
+        path = file_at(name)
+        return "" unless path
+
+        File.read(path)
+      rescue Errno::ENOENT
+        ""
+      end
+
+      def file_at(name)
+        path = File.join(@dir, name)
+        path if File.exist?(path)
+      end
+
+      def date_files_descending(days)
+        today = Date.today
+        (0...days).filter_map do |offset|
+          file_at((today - offset).strftime("%Y-%m-%d.md"))
+        end
+      end
+
+      def search_files
+        priority = %w[SOUL.md USER.md].filter_map { |name| file_at(name) }
+        date_files = Dir.glob(File.join(@dir, "????-??-??.md")).reverse
+        priority + date_files
+      end
+
+      def write_with_header(path, today, entry)
+        content = build_entry_content(path, today, entry)
+        append_locked(path, content)
+      end
+
+      def build_entry_content(path, today, entry)
+        needs_header = !File.exist?(path) || File.empty?(path)
+        header = needs_header ? "# Memories for #{today}\n\n" : ""
+        "#{header}#{entry}\n"
+      end
+
+      def append_locked(path, content)
+        File.open(path, "a") do |file|
+          file.flock(File::LOCK_EX)
+          file.write(content)
+        end
+      end
+    end
+  end
+end

data/lib/earl/message_queue.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Earl
+  # Thread-safe message queue that tracks which threads are actively
+  # processing and buffers messages for busy threads.
+  class MessageQueue
+    include Logging
+
+    def initialize
+      @processing_threads = Set.new
+      @pending_messages = {}
+      @mutex = Mutex.new
+    end
+
+    def try_claim(thread_id)
+      @mutex.synchronize do
+        if @processing_threads.include?(thread_id)
+          false
+        else
+          @processing_threads << thread_id
+          true
+        end
+      end
+    end
+
+    def enqueue(thread_id, text)
+      @mutex.synchronize do
+        queue = (@pending_messages[thread_id] ||= [])
+        queue << text
+        log(:debug, "Queued message for busy thread #{thread_id[0..7]}")
+      end
+    end
+
+    def dequeue(thread_id)
+      @mutex.synchronize do
+        msgs = @pending_messages[thread_id]
+        if msgs && !msgs.empty?
+          msgs.shift
+        else
+          @processing_threads.delete(thread_id)
+          nil
+        end
+      end
+    end
+
+    # Unconditionally releases the processing claim for a thread,
+    # discarding any pending messages. Use when the session is dead
+    # and queued messages cannot be delivered.
+    def release(thread_id)
+      @mutex.synchronize do
+        @processing_threads.delete(thread_id)
+        @pending_messages.delete(thread_id)
+      end
+    end
+  end
+end

data/lib/earl/permission_config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Earl
+  # Shared permission configuration builder for MCP permission server.
+  # Used by both SessionManager (user-initiated) and HeartbeatScheduler (automated).
+  module PermissionConfig
+    private
+
+    def build_permission_env(config, channel_id:, thread_id: "")
+      return nil if config.skip_permissions?
+
+      {
+        "PLATFORM_URL" => config.mattermost_url,
+        "PLATFORM_TOKEN" => config.bot_token,
+        "PLATFORM_CHANNEL_ID" => channel_id,
+        "PLATFORM_THREAD_ID" => thread_id,
+        "PLATFORM_BOT_ID" => config.bot_id,
+        "ALLOWED_USERS" => config.allowed_users.join(",")
+      }
+    end
+  end
+end

data/lib/earl/question_handler/question_posting.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Earl
+  class QuestionHandler
+    # Handles building question messages, posting them, and managing reactions.
+    module QuestionPosting
+      private
+
+      def post_current_question(state)
+        question = state.current_question
+        message = build_question_message(question)
+
+        post_id = create_question_post(state.channel_id, state.thread_id, message)
+        register_question_post(state, post_id, (question["options"] || []).size)
+      end
+
+      def create_question_post(channel_id, thread_id, message)
+        result = @mattermost.create_post(channel_id: channel_id, message: message, root_id: thread_id)
+        result["id"]
+      end
+
+      def build_question_message(question)
+        options = question["options"] || []
+        lines = [":question: **#{question["question"]}**"]
+        options.each_with_index do |opt, index|
+          emoji = EMOJI_NUMBERS[index]
+          label = opt["label"] || opt.to_s
+          desc = opt["description"]
+          lines << ":#{emoji}: #{label}#{" — #{desc}" if desc}"
+        end
+        lines.join("\n")
+      end
+
+      def register_question_post(state, post_id, option_count)
+        if post_id
+          state.current_post_id = post_id
+          add_emoji_options(post_id, option_count)
+          @mutex.synchronize { @pending_questions[post_id] = state }
+          true
+        else
+          false
+        end
+      end
+
+      def add_emoji_options(post_id, count)
+        count.times do |index|
+          @mattermost.add_reaction(post_id: post_id, emoji_name: EMOJI_NUMBERS[index])
+        end
+      end
+
+      def delete_question_post(post_id)
+        @mattermost.delete_post(post_id: post_id)
+      rescue StandardError => error
+        log(:warn, "Failed to delete question post #{post_id}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/earl/question_handler.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "question_handler/question_posting"
+
+module Earl
+  # Handles AskUserQuestion tool_use events from Claude by posting numbered
+  # options to Mattermost and collecting answers via emoji reactions.
+  class QuestionHandler
+    include Logging
+    include QuestionPosting
+
+    EMOJI_NUMBERS = %w[one two three four].freeze
+    EMOJI_MAP = { "one" => 0, "two" => 1, "three" => 2, "four" => 3 }.freeze
+
+    # Tracks in-progress question flow: which tool_use triggered it, the list of
+    # questions, collected answers, and the Mattermost post/thread IDs.
+    QuestionState = Struct.new(:tool_use_id, :questions, :answers, :current_index,
+                               :current_post_id, :thread_id, :channel_id, keyword_init: true) do
+      def current_question
+        questions[current_index]
+      end
+
+      def all_questions_answered?
+        current_index >= questions.size
+      end
+    end
+
+    def initialize(mattermost:)
+      @mattermost = mattermost
+      @pending_questions = {} # post_id -> QuestionState
+      @mutex = Mutex.new
+    end
+
+    def handle_tool_use(thread_id:, tool_use:, channel_id: nil)
+      name, input, tool_use_id = tool_use.values_at(:name, :input, :id)
+      return nil unless name == "AskUserQuestion"
+
+      questions = input["questions"] || []
+      return nil if questions.empty?
+
+      state = QuestionState.new(
+        tool_use_id: tool_use_id, questions: questions, answers: {},
+        current_index: 0, thread_id: thread_id, channel_id: channel_id
+      )
+      start_question_flow(state, tool_use_id)
+    end
+
+    def handle_reaction(post_id:, emoji_name:)
+      state = fetch_pending(post_id)
+      return nil unless state
+
+      selected = resolve_selected_option(state, emoji_name)
+      return nil unless selected
+
+      accept_answer(state, post_id, selected)
+    end
+
+    private
+
+    def start_question_flow(state, tool_use_id)
+      unless post_current_question(state)
+        log(:error, "Failed to post question for tool_use #{tool_use_id}, returning error answer")
+        return { tool_use_id: tool_use_id, answer_text: "Failed to post question to chat" }
+      end
+
+      { tool_use_id: tool_use_id }
+    end
+
+    def fetch_pending(post_id)
+      @mutex.synchronize { @pending_questions[post_id] }
+    end
+
+    def release_pending(post_id)
+      @mutex.synchronize { @pending_questions.delete(post_id) }
+      delete_question_post(post_id)
+    end
+
+    def accept_answer(state, post_id, selected)
+      index = state.current_index
+      record_answer(state, state.questions[index], selected)
+      release_pending(post_id)
+      advance_question(state, index)
+    end
+
+    def advance_question(state, index)
+      next_index = index + 1
+      state.current_index = next_index
+      return build_answer_json(state) unless next_index < state.questions.size
+
+      post_current_question(state)
+      nil
+    end
+
+    def resolve_selected_option(state, emoji_name)
+      answer_index = EMOJI_MAP[emoji_name]
+      return nil unless answer_index
+
+      options = state.questions[state.current_index]["options"] || []
+      answer_index < options.size ? options[answer_index] : nil
+    end
+
+    def record_answer(state, question, selected_option)
+      state.answers[question["question"]] = selected_option["label"] || selected_option.to_s
+    end
+
+    def build_answer_json(state)
+      answers = state.questions.map.with_index do |question, index|
+        q_text = question["question"]
+        answer = state.answers[q_text]
+        "Question #{index + 1}: #{q_text}\nAnswer: #{answer}"
+      end.join("\n\n")
+
+      { tool_use_id: state.tool_use_id, answer_text: answers }
+    end
+  end
+end

data/lib/earl/runner/idle_management.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Earl
+  class Runner
+    # Idle session management.
+    module IdleManagement
+      private
+
+      def start_idle_checker
+        @app_state.idle_checker_thread = Thread.new do
+          loop do
+            sleep IDLE_CHECK_INTERVAL
+            check_idle_sessions
+          rescue StandardError => error
+            log(:error, "Idle checker error: #{error.message}")
+          end
+        end
+      end
+
+      def check_idle_sessions
+        @services.session_store.load.each do |thread_id, persisted|
+          stop_if_idle(thread_id, persisted)
+        end
+      end
+
+      def stop_if_idle(thread_id, persisted)
+        return if persisted.is_paused
+
+        idle_seconds = seconds_since_activity(persisted.last_activity_at)
+        return unless idle_seconds
+        return unless idle_seconds > IDLE_TIMEOUT
+
+        log(:info, "Stopping idle session for thread #{thread_id[0..7]} (idle #{(idle_seconds / 60).round}min)")
+        @services.session_manager.stop_session(thread_id)
+      end
+
+      def seconds_since_activity(last_activity_at)
+        return nil unless last_activity_at
+
+        Time.now - Time.parse(last_activity_at)
+      end
+    end
+  end
+end

data/lib/earl/runner/lifecycle.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Earl
+  class Runner
+    # Shutdown, restart, and process lifecycle management.
+    module Lifecycle
+      private
+
+      def begin_shutdown(&)
+        return if @app_state.shutting_down
+
+        @app_state.shutting_down = true
+        @app_state.shutdown_thread = Thread.new(&)
+      end
+
+      def handle_shutdown_signal
+        begin_shutdown { shutdown }
+      end
+
+      def handle_restart_signal
+        @app_state.pending_restart = true
+        begin_shutdown { restart }
+      end
+
+      def setup_close_handler
+        @services.mattermost.on_close { handle_shutdown_signal }
+      end
+
+      def shutdown
+        log(:info, "Shutting down...")
+        @app_state.idle_checker_thread&.kill
+        @services.heartbeat_scheduler.stop
+        @services.tmux_monitor.stop
+        @services.session_manager.pause_all
+        log(:info, "Goodbye!")
+      end
+
+      def restart
+        updating = @app_state.pending_update
+        log(:info, updating ? "Updating EARL..." : "Restarting EARL...")
+        pull_latest if updating || !Earl.development?
+        update_dependencies if updating
+        shutdown
+      end
+
+      def wait_and_exec_restart
+        @app_state.shutdown_thread&.join
+        cmd = [RbConfig.ruby, $PROGRAM_NAME]
+        log(:info, "Exec: #{cmd.join(" ")}")
+        Bundler.with_unbundled_env { Kernel.exec(*cmd) }
+      end
+
+      def pull_latest
+        run_in_repo("git pull --ff-only", "git", "pull", "--ff-only")
+      end
+
+      def update_dependencies
+        run_in_repo("bundle install", { "RUBYOPT" => "-W0" }, "bundle", "install", "--quiet")
+      end
+
+      def run_in_repo(label, *cmd)
+        Dir.chdir(File.dirname($PROGRAM_NAME)) do
+          result = system(*cmd) ? "succeeded" : "failed (continuing)"
+          log(result.start_with?("s") ? :info : :warn, "#{label} #{result}")
+        end
+      rescue StandardError => error
+        log(:warn, "#{label} failed: #{error.message}")
+      end
+    end
+  end
+end

data/lib/earl/runner/message_handling.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Earl
+  class Runner
+    # Message routing: receives user messages, dispatches commands or enqueues for Claude.
+    module MessageHandling
+      private
+
+      def setup_message_handler
+        @services.mattermost.on_message do |sender_name:, thread_id:, text:, channel_id:, **_extra|
+          if allowed_user?(sender_name)
+            msg = UserMessage.new(thread_id: thread_id, text: text, channel_id: channel_id,
+                                  sender_name: sender_name)
+            handle_incoming_message(msg)
+          end
+        end
+      end
+
+      def handle_incoming_message(msg)
+        if CommandParser.command?(msg.text)
+          dispatch_command(msg)
+        else
+          enqueue_message(msg)
+        end
+      end
+
+      def dispatch_command(msg)
+        command = CommandParser.parse(msg.text)
+        return unless command
+
+        thread_id = msg.thread_id
+        result = @services.command_executor.execute(command, thread_id: thread_id, channel_id: msg.channel_id)
+        enqueue_passthrough(result, msg) if result&.dig(:passthrough)
+        stop_active_response(thread_id) if %i[stop kill].include?(command.name)
+      end
+
+      def enqueue_passthrough(result, msg)
+        msg_thread_id, _text, msg_channel_id, msg_sender = msg.deconstruct
+        passthrough_msg = UserMessage.new(
+          thread_id: msg_thread_id, text: result[:passthrough],
+          channel_id: msg_channel_id, sender_name: msg_sender
+        )
+        enqueue_message(passthrough_msg)
+      end
+
+      def enqueue_message(msg)
+        thread_id = msg.thread_id
+        queue = @app_state.message_queue
+        if queue.try_claim(thread_id)
+          process_message(msg)
+        else
+          queue.enqueue(thread_id, msg.text)
+        end
+      end
+
+      def process_message(msg)
+        sent = false
+        thread_id = msg.thread_id
+        sent = process_message_send(msg, thread_id)
+      rescue StandardError => error
+        log_processing_error(thread_id, error)
+      ensure
+        cleanup_failed_send(thread_id) unless sent
+      end
+
+      def process_message_send(msg, thread_id)
+        text = msg.text
+        effective_channel = msg.channel_id || @services.config.channel_id
+        existing_session, session = prepare_session(thread_id, effective_channel, msg.sender_name)
+        prepare_response(session, thread_id, effective_channel)
+        message = existing_session ? text : build_contextual_message(thread_id, text)
+        send_and_touch(session, thread_id, message)
+      end
+
+      def send_and_touch(session, thread_id, message)
+        sent = session.send_message(message)
+        @services.session_manager.touch(thread_id) if sent
+        sent
+      end
+
+      def prepare_session(thread_id, channel_id, sender_name)
+        working_dir = resolve_working_dir(thread_id, channel_id)
+        manager = @services.session_manager
+        existing = manager.get(thread_id)
+        session_config = SessionManager::SessionConfig.new(
+          channel_id: channel_id, working_dir: working_dir, username: sender_name
+        )
+        session = manager.get_or_create(thread_id, session_config)
+        [existing, session]
+      end
+
+      def resolve_working_dir(thread_id, channel_id)
+        @services.command_executor.working_dir_for(thread_id) || @services.config.channels[channel_id] || Dir.pwd
+      end
+
+      def build_contextual_message(thread_id, text)
+        ThreadContextBuilder.new(mattermost: @services.mattermost).build(thread_id, text)
+      end
+
+      def process_next_queued(thread_id)
+        next_text = @app_state.message_queue.dequeue(thread_id)
+        return unless next_text
+
+        msg = UserMessage.new(thread_id: thread_id, text: next_text, channel_id: nil, sender_name: nil)
+        process_message(msg)
+      end
+
+      def allowed_user?(username)
+        allowed = @services.config.allowed_users
+        return true if allowed.empty?
+
+        unless allowed.include?(username)
+          log(:debug, "Ignoring message from non-allowed user: #{username}")
+          return false
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/earl/runner/reaction_handling.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Earl
+  class Runner
+    # Emoji reaction handling: routes reactions to question handler or tmux monitor.
+    module ReactionHandling
+      private
+
+      def setup_reaction_handler
+        @services.mattermost.on_reaction do |user_id:, post_id:, emoji_name:|
+          handle_reaction(user_id: user_id, post_id: post_id, emoji_name: emoji_name)
+        end
+      end
+
+      def handle_reaction(user_id:, post_id:, emoji_name:)
+        return unless allowed_reactor?(user_id)
+
+        result = @services.question_handler.handle_reaction(post_id: post_id, emoji_name: emoji_name)
+        if result
+          thread_id = @responses.question_threads[result[:tool_use_id]]
+          return unless thread_id
+
+          session = @services.session_manager.get(thread_id)
+          session&.send_message(result[:answer_text])
+          return
+        end
+
+        @services.tmux_monitor.handle_reaction(post_id: post_id, emoji_name: emoji_name)
+      end
+
+      def allowed_reactor?(user_id)
+        allowed = @services.config.allowed_users
+        return true if allowed.empty?
+
+        username = @services.mattermost.get_user(user_id: user_id)["username"]
+        return false unless username
+
+        allowed.include?(username)
+      end
+    end
+  end
+end