earl-bot 0.1.0

data/lib/earl/tmux_monitor/alert_dispatcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Earl
+  class TmuxMonitor
+    # Builds and posts state-change alerts (error, completed, stalled, tombstone)
+    # to Mattermost. Interactive states (questions, permissions) are delegated
+    # to the appropriate forwarder instead.
+    module AlertDispatcher
+      private
+
+      def dispatch_state_alert(state, **context)
+        name, output, info = context.values_at(:name, :output, :info)
+        forwarder = { asking_question: @deps.question_forwarder,
+                      requesting_permission: @deps.permission_forwarder }[state]
+        if forwarder
+          forwarder.forward(name, output, info)
+        else
+          msg = passive_alert_message(state, name, output)
+          post_alert(info, msg) if msg
+        end
+      end
+
+      def passive_alert_message(state, name, output)
+        { errored: error_message(name, output),
+          completed: completed_message(name),
+          stalled: stalled_message(name) }[state]
+      end
+
+      def error_message(name, output)
+        ":x: Session `#{name}` encountered an error:\n```\n#{output.lines.last(10)&.join}\n```"
+      end
+
+      def completed_message(name)
+        ":white_check_mark: Session `#{name}` appears to have completed (shell prompt detected)."
+      end
+
+      def stalled_message(name)
+        ":hourglass: Session `#{name}` appears stalled (output unchanged for #{@poll_state.stall_threshold} polls)."
+      end
+
+      def post_alert(info, message)
+        @deps.mattermost.create_post(
+          channel_id: info.channel_id,
+          message: message,
+          root_id: info.thread_id
+        )
+      rescue StandardError => error
+        log(:error, "TmuxMonitor: failed to post alert (#{error.class}): #{error.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/earl/tmux_monitor/output_analyzer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Earl
+  class TmuxMonitor
+    # Stateless output analysis that detects tmux session state from captured text.
+    module OutputAnalyzer
+      SHELL_PROMPT_PATTERN = /[❯#%]\s*\z|\$\s+\z/
+
+      module_function
+
+      def detect(output, name, poll_state)
+        all_lines = output.lines
+        return :completed if completed?(all_lines)
+
+        state_from_patterns(all_lines) || stall_or_running(name, output, poll_state)
+      end
+
+      def completed?(all_lines)
+        (all_lines.last(3)&.join || "").match?(SHELL_PROMPT_PATTERN)
+      end
+
+      def state_from_patterns(all_lines)
+        recent = all_lines.last(15)&.join || ""
+        STATE_PATTERNS.each do |state, pattern|
+          return state if recent.match?(pattern)
+        end
+        nil
+      end
+
+      def stall_or_running(name, output, poll_state)
+        poll_state.stalled?(name, output) ? :stalled : :running
+      end
+    end
+  end
+end

data/lib/earl/tmux_monitor/permission_forwarder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Earl
+  class TmuxMonitor
+    # Handles forwarding detected permission prompts from tmux panes to Mattermost
+    # and processing user reactions (approve/deny) back as tmux keyboard input.
+    class PermissionForwarder
+      include Logging
+
+      PERMISSION_EMOJIS = { "white_check_mark" => "y", "x" => "n" }.freeze
+
+      def initialize(mattermost:, tmux:, pending_interactions:, mutex:)
+        @mattermost = mattermost
+        @tmux = tmux
+        @pending_interactions = pending_interactions
+        @mutex = mutex
+      end
+
+      def forward(name, output, info)
+        post = post_permission(name, output, info)
+        return unless post
+
+        register_interaction(post, name)
+      end
+
+      def handle_reaction(interaction, emoji_name, post_id)
+        answer = PERMISSION_EMOJIS[emoji_name]
+        return nil unless answer
+
+        send_answer(interaction, answer, post_id)
+      end
+
+      private
+
+      def send_answer(interaction, answer, post_id)
+        @tmux.send_keys(interaction[:session_name], answer)
+        @mutex.synchronize { @pending_interactions.delete(post_id) }
+        true
+      rescue Tmux::Error => error
+        log(:error, "TmuxMonitor: failed to send permission answer: #{error.message}")
+        nil
+      end
+
+      def post_permission(name, output, info)
+        context = output.lines.last(15)&.join || ""
+        message = build_permission_message(name, context)
+        @mattermost.create_post(
+          channel_id: info.channel_id,
+          message: message,
+          root_id: info.thread_id
+        )
+      rescue StandardError => error
+        log(:error, "TmuxMonitor: failed to post alert (#{error.class}): #{error.message}")
+        nil
+      end
+
+      def build_permission_message(name, context)
+        [
+          ":lock: **Tmux `#{name}`** is requesting permission:",
+          "```",
+          context,
+          "```",
+          ":white_check_mark: Approve  |  :x: Deny"
+        ].join("\n")
+      end
+
+      def register_interaction(post, name)
+        post_id = post["id"]
+        return unless post_id
+
+        @mattermost.add_reaction(post_id: post_id, emoji_name: "white_check_mark")
+        @mattermost.add_reaction(post_id: post_id, emoji_name: "x")
+
+        @mutex.synchronize do
+          @pending_interactions[post_id] = { session_name: name, type: :permission }
+        end
+      end
+    end
+  end
+end

data/lib/earl/tmux_monitor/question_forwarder.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Earl
+  class TmuxMonitor
+    # Handles forwarding detected questions from tmux panes to Mattermost
+    # and processing user reactions back as tmux keyboard input.
+    class QuestionForwarder
+      include Logging
+
+      EMOJI_NUMBERS = QuestionHandler::EMOJI_NUMBERS
+      EMOJI_MAP = QuestionHandler::EMOJI_MAP
+
+      def initialize(mattermost:, tmux:, pending_interactions:, mutex:)
+        @mattermost = mattermost
+        @tmux = tmux
+        @pending_interactions = pending_interactions
+        @mutex = mutex
+      end
+
+      def forward(name, output, info)
+        parsed = parse_question(output)
+        return unless parsed
+
+        post = post_question(name, parsed, info)
+        return unless post
+
+        register_interaction(post, name, parsed[:options])
+      end
+
+      def handle_reaction(interaction, emoji_name, post_id)
+        answer_index = EMOJI_MAP[emoji_name]
+        return nil unless answer_index
+        return nil unless valid_option?(interaction, answer_index)
+
+        send_answer(interaction, answer_index, post_id)
+      end
+
+      def parse_question(output)
+        lines = output.lines.map(&:strip).reject(&:empty?)
+        question_idx = find_question_index(lines)
+        return nil unless question_idx
+
+        build_parsed(lines, question_idx)
+      end
+
+      private
+
+      def valid_option?(interaction, answer_index)
+        answer_index < interaction[:options].size
+      end
+
+      def find_question_index(lines)
+        lines.rindex { |line| line.include?("?") }
+      end
+
+      def build_parsed(lines, question_idx)
+        options = gather_numbered_options(lines, question_idx).first(4)
+        return nil if options.empty?
+
+        { text: lines[question_idx], options: options }
+      end
+
+      def send_answer(interaction, answer_index, post_id)
+        @tmux.send_keys(interaction[:session_name], (answer_index + 1).to_s)
+        @mutex.synchronize { @pending_interactions.delete(post_id) }
+        true
+      rescue Tmux::Error => error
+        log(:error, "TmuxMonitor: failed to send question answer: #{error.message}")
+        nil
+      end
+
+      def gather_numbered_options(lines, question_idx)
+        options = []
+        ((question_idx + 1)...lines.size).each do |idx|
+          line = lines[idx]
+          options << line.sub(/\A\s*\d+[.)]\s*/, "") if line.match?(/\A\s*\d+[.)]\s/)
+        end
+        options
+      end
+
+      def post_question(name, parsed, info)
+        message = build_question_message(name, parsed)
+        @mattermost.create_post(
+          channel_id: info.channel_id,
+          message: message,
+          root_id: info.thread_id
+        )
+      rescue StandardError => error
+        log(:error, "TmuxMonitor: failed to post alert (#{error.class}): #{error.message}")
+        nil
+      end
+
+      def build_question_message(name, parsed)
+        lines = [":question: **Tmux `#{name}`** is asking:", "```", parsed[:text], "```"]
+        parsed[:options].each_with_index do |opt, idx|
+          emoji = EMOJI_NUMBERS[idx]
+          lines << ":#{emoji}: #{opt}" if emoji
+        end
+        lines.join("\n")
+      end
+
+      def register_interaction(post, name, options)
+        post_id = post["id"]
+        return unless post_id
+
+        add_emoji_reactions(post_id, options.size)
+        @mutex.synchronize do
+          @pending_interactions[post_id] = {
+            session_name: name, type: :question, options: options
+          }
+        end
+      end
+
+      def add_emoji_reactions(post_id, count)
+        [count, EMOJI_NUMBERS.size].min.times do |idx|
+          emoji = EMOJI_NUMBERS[idx]
+          @mattermost.add_reaction(post_id: post_id, emoji_name: emoji)
+        rescue StandardError => error
+          log(:warn, "TmuxMonitor: failed to add reaction :#{emoji}: (#{error.class}): #{error.message}")
+        end
+      end
+    end
+  end
+end

data/lib/earl/tmux_monitor.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "tmux_monitor/alert_dispatcher"
+require_relative "tmux_monitor/output_analyzer"
+require_relative "tmux_monitor/question_forwarder"
+require_relative "tmux_monitor/permission_forwarder"
+
+module Earl
+  # Lightweight background poller that monitors EARL-spawned tmux sessions for
+  # state changes (questions, permission prompts, errors, completion, stalls)
+  # and posts alerts to Mattermost. Also handles forwarding user reactions
+  # back to tmux sessions as keyboard input.
+  class TmuxMonitor
+    include Logging
+    include AlertDispatcher
+
+    DEFAULT_POLL_INTERVAL = 45 # seconds
+    DEFAULT_STALL_THRESHOLD = 5 # consecutive unchanged polls
+
+    # Pattern matchers for detecting session state from captured output.
+    STATE_PATTERNS = {
+      asking_question: /\?\s*\n\s*(?:1[.)]\s|❯)/m,
+      requesting_permission: /(?:Allow|Deny|approve|permission|Do you want to allow)/i,
+      errored: /(?:Error:|error:|FAILED|panic:|Traceback|fatal:)/
+    }.freeze
+
+    INTERACTIVE_STATES = { asking_question: :question, requesting_permission: :permission }.freeze
+
+    # Bundles external service dependencies and forwarder collaborators.
+    Forwarders = Struct.new(:question, :permission, keyword_init: true)
+
+    def initialize(mattermost:, tmux_store:, tmux_adapter: Tmux)
+      @poll_state = PollState.new(stall_threshold: Integer(ENV.fetch("EARL_TMUX_STALL_THRESHOLD",
+                                                                     DEFAULT_STALL_THRESHOLD)))
+      @deps = Dependencies.new(mattermost, tmux_store, tmux_adapter, @poll_state)
+      @poll_interval = Integer(ENV.fetch("EARL_TMUX_POLL_INTERVAL", DEFAULT_POLL_INTERVAL))
+      @thread_ctl = ThreadControl.new
+    end
+
+    def start
+      return if @thread_ctl.alive?
+
+      @thread_ctl.start { poll_loop }
+      log(:info, "TmuxMonitor started (interval: #{@poll_interval}s)")
+    end
+
+    def stop
+      @thread_ctl.stop
+      log(:info, "TmuxMonitor stopped")
+    end
+
+    # Called by Runner when a user reacts to a forwarded question/permission post.
+    # Returns true if the reaction was handled, nil otherwise.
+    def handle_reaction(post_id:, emoji_name:)
+      interaction = @poll_state.pending_interaction(post_id)
+      return nil unless interaction
+
+      case interaction[:type]
+      when :question
+        @deps.question_forwarder.handle_reaction(interaction, emoji_name, post_id)
+      when :permission
+        @deps.permission_forwarder.handle_reaction(interaction, emoji_name, post_id)
+      end
+    end
+
+    # Delegate parse_question to QuestionForwarder for external callers.
+    def parse_question(output)
+      @deps.question_forwarder.parse_question(output)
+    end
+
+    private
+
+    def poll_loop
+      loop do
+        sleep @poll_interval
+        break if @thread_ctl.shutdown?
+
+        poll_sessions
+      rescue StandardError => error
+        log(:error, "TmuxMonitor poll error: #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
+      end
+    end
+
+    def poll_sessions
+      sessions = @deps.tmux_store.all
+      cleanup_dead_sessions(sessions)
+
+      sessions.each do |name, info|
+        poll_single_session(name, info)
+      rescue StandardError => error
+        log(:error,
+            "TmuxMonitor: error polling session '#{name}': #{error.message}\n#{error.backtrace&.first(5)&.join("\n")}")
+      end
+    end
+
+    def poll_single_session(name, info)
+      return unless @deps.tmux.session_exists?(name)
+
+      output = safe_capture(name)
+      return unless output
+
+      state = OutputAnalyzer.detect(output, name, @poll_state)
+      return unless @poll_state.transition(name, state)
+
+      dispatch_state_alert(state, name: name, output: output, info: info)
+    end
+
+    def safe_capture(name)
+      @deps.tmux.capture_pane(name, lines: 50)
+    rescue Tmux::Error => error
+      log(:warn, "TmuxMonitor: failed to capture '#{name}': #{error.message}")
+      nil
+    end
+
+    def cleanup_dead_sessions(sessions)
+      sessions.each do |name, info|
+        next if @deps.tmux.session_exists?(name)
+
+        log(:info, "TmuxMonitor: session '#{name}' no longer exists, cleaning up")
+        post_alert(info, ":tombstone: Tmux session `#{name}` has ended.")
+        @deps.tmux_store.delete(name)
+        @poll_state.cleanup_session(name)
+      end
+    end
+
+    # Holds external service references and forwarder pair.
+    class Dependencies
+      attr_reader :mattermost, :tmux_store, :tmux
+
+      def initialize(mattermost, tmux_store, tmux_adapter, poll_state)
+        @mattermost = mattermost
+        @tmux_store = tmux_store
+        @tmux = tmux_adapter
+        shared = { mattermost: mattermost, tmux: tmux_adapter,
+                   pending_interactions: poll_state.pending_interactions, mutex: poll_state.mutex }
+        @forwarders = Forwarders.new(
+          question: QuestionForwarder.new(**shared),
+          permission: PermissionForwarder.new(**shared)
+        )
+      end
+
+      def question_forwarder = @forwarders.question
+      def permission_forwarder = @forwarders.permission
+    end
+
+    # Encapsulates mutable poll tracking state: last-seen states, output hashes
+    # for stall detection, and pending user interactions.
+    class PollState
+      # Tracks per-session poll state: last detected state, output hash for stall detection.
+      TrackingEntry = Struct.new(:last_state, :output_hash, :stall_count, keyword_init: true) do
+        def update_stall(current_hash, threshold)
+          if output_hash == current_hash
+            self.stall_count += 1
+            stall_count >= threshold
+          else
+            self.output_hash = current_hash
+            self.stall_count = 1
+            false
+          end
+        end
+      end
+
+      attr_reader :pending_interactions, :mutex, :stall_threshold
+
+      def initialize(stall_threshold: DEFAULT_STALL_THRESHOLD)
+        @tracking = {}
+        @pending_interactions = {}
+        @mutex = Mutex.new
+        @stall_threshold = stall_threshold
+      end
+
+      def pending_interaction(post_id)
+        @mutex.synchronize { @pending_interactions[post_id] }
+      end
+
+      # Returns true if state changed (and records the new state), false otherwise.
+      def transition(name, state)
+        tracking = ensure_tracking(name)
+        last_state = tracking.last_state
+        changed = last_state != state || should_retrigger?(name, state)
+        return false unless changed
+
+        tracking.last_state = state
+        true
+      end
+
+      def stalled?(name, output)
+        ensure_tracking(name).update_stall(output.hash, @stall_threshold)
+      end
+
+      def cleanup_session(name)
+        @tracking.delete(name)
+        @mutex.synchronize do
+          @pending_interactions.delete_if { |_, interaction| interaction[:session_name] == name }
+        end
+      end
+
+      private
+
+      def should_retrigger?(name, state)
+        interaction_type = INTERACTIVE_STATES[state]
+        return false unless interaction_type
+
+        pending = pending_interactions_for(name)
+        pending.none? { |interaction| interaction[:type] == interaction_type }
+      end
+
+      def pending_interactions_for(session_name)
+        @mutex.synchronize do
+          @pending_interactions.values.select { |interaction| interaction[:session_name] == session_name }
+        end
+      end
+
+      def ensure_tracking(name)
+        @tracking[name] ||= TrackingEntry.new(last_state: nil, output_hash: nil, stall_count: 0)
+      end
+    end
+
+    # Simple background thread lifecycle wrapper.
+    class ThreadControl
+      def initialize
+        @thread = nil
+        @shutdown = false
+      end
+
+      def alive?
+        @thread&.alive?
+      end
+
+      def shutdown?
+        @shutdown
+      end
+
+      def start(&)
+        @shutdown = false
+        @thread = Thread.new(&)
+      end
+
+      def stop
+        @shutdown = true
+        return unless @thread
+
+        @thread.join(5)
+        @thread.kill if @thread.alive?
+        @thread = nil
+      end
+    end
+  end
+end

data/lib/earl/tmux_session_store.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Earl
+  # Tracks EARL-spawned tmux sessions with metadata for monitoring and control.
+  # Persists to <config_root>/tmux_sessions.json with thread-safe atomic writes.
+  class TmuxSessionStore
+    include Logging
+
+    # Holds metadata for an EARL-spawned tmux session.
+    TmuxSessionInfo = Struct.new(:name, :channel_id, :thread_id, :working_dir,
+                                 :prompt, :created_at, keyword_init: true)
+
+    def self.default_path
+      @default_path ||= File.join(Earl.config_root, "tmux_sessions.json")
+    end
+
+    def initialize(path: self.class.default_path)
+      @path = path
+      @mutex = Mutex.new
+      @cache = nil
+      @dirty = false
+    end
+
+    def save(info)
+      @mutex.synchronize do
+        ensure_cache[info.name] = info
+        write_store(@cache)
+      end
+    end
+
+    def get(name)
+      @mutex.synchronize { ensure_cache[name] }
+    end
+
+    def all
+      @mutex.synchronize { ensure_cache.dup }
+    end
+
+    def delete(name)
+      @mutex.synchronize do
+        ensure_cache.delete(name)
+        write_store(@cache)
+      end
+    end
+
+    # Returns names of dead sessions without modifying the store.
+    def cleanup
+      find_dead_sessions
+    end
+
+    # Removes entries for tmux sessions that no longer exist.
+    # Shell calls happen outside the mutex to avoid blocking other operations
+    # if tmux is slow or hung.
+    def cleanup!
+      dead = find_dead_sessions
+      return dead if dead.empty?
+
+      remove_dead_sessions(dead)
+    end
+
+    private
+
+    def find_dead_sessions
+      names = @mutex.synchronize { ensure_cache.keys }
+      names.reject { |name| Tmux.session_exists?(name) }
+    end
+
+    def remove_dead_sessions(dead)
+      @mutex.synchronize do
+        dead.each { |name| @cache&.delete(name) }
+        write_store(@cache) if @cache
+        dead
+      end
+    end
+
+    def ensure_cache
+      @cache ||= read_store
+      write_store(@cache) if @dirty && @cache
+      @cache
+    end
+
+    def read_store
+      return {} unless File.exist?(@path)
+
+      raw = JSON.parse(File.read(@path))
+      deserialize_entries(raw)
+    rescue JSON::ParserError, ArgumentError, Errno::ENOENT => error
+      file_missing = error.is_a?(Errno::ENOENT)
+      backup_corrupted_store unless file_missing
+      suffix = file_missing ? "" : " (backed up corrupted file)"
+      log(:warn, "Failed to read tmux session store: #{error.message}#{suffix}")
+      {}
+    end
+
+    def deserialize_entries(raw)
+      valid_keys = TmuxSessionInfo.members.map(&:to_s)
+      raw.transform_values do |value|
+        filtered = value.slice(*valid_keys).transform_keys(&:to_sym)
+        TmuxSessionInfo.new(**filtered)
+      end
+    end
+
+    def backup_corrupted_store
+      return unless File.exist?(@path)
+
+      backup_path = "#{@path}.corrupt.#{Time.now.strftime("%Y%m%d%H%M%S")}"
+      FileUtils.cp(@path, backup_path)
+    rescue StandardError => error
+      log(:warn, "Failed to back up corrupted store: #{error.message}")
+    end
+
+    def write_store(data)
+      serialize_and_write(data)
+      @dirty = false
+    rescue StandardError => error
+      @dirty = true
+      log(:error, "Failed to write tmux session store: #{error.message} (will retry on next write)")
+    end
+
+    def serialize_and_write(data)
+      dir = File.dirname(@path)
+      FileUtils.mkdir_p(dir)
+
+      serialized = data.transform_values(&:to_h)
+      tmp_path = "#{@path}.tmp.#{Process.pid}"
+      File.write(tmp_path, JSON.pretty_generate(serialized))
+      File.rename(tmp_path, @path)
+    rescue StandardError
+      FileUtils.rm_f(tmp_path) if tmp_path
+      raise
+    end
+  end
+end