earl-bot 0.1.0

data/lib/earl/session_manager.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "session_manager/persistence"
+require_relative "session_manager/session_creation"
+
+module Earl
+  # Thread-safe registry of active Claude sessions, keyed by Mattermost
+  # thread ID, with lazy creation, coordinated shutdown, and optional persistence.
+  class SessionManager
+    include Logging
+    include PermissionConfig
+
+    # Bundles session creation parameters that travel together.
+    SessionConfig = Data.define(:channel_id, :working_dir, :username)
+
+    # Bundles thread identity with session config to eliminate data clump.
+    ThreadContext = Data.define(:thread_id, :short_id, :session_config)
+
+    # Bundles persistence parameters to reduce parameter list length.
+    PersistenceContext = Data.define(:channel_id, :working_dir, :paused)
+
+    # Bundles parameters for spawning a new Claude session.
+    SpawnParams = Data.define(:session_id, :thread_id, :channel_id, :working_dir, :username)
+
+    def initialize(config: nil, session_store: nil)
+      @config = config
+      @session_store = session_store
+      @sessions = {}
+      @mutex = Mutex.new
+    end
+
+    def get_or_create(thread_id, session_config)
+      ctx = ThreadContext.new(thread_id: thread_id, short_id: thread_id[0..7],
+                              session_config: session_config)
+      @mutex.synchronize do
+        session = @sessions[thread_id]
+        return reuse_session(session, ctx.short_id) if session&.alive?
+
+        persisted = @session_store&.load&.dig(thread_id)
+        return resume_or_create(ctx, persisted) if persisted&.claude_session_id
+
+        create_session(ctx)
+      end
+    end
+
+    def get(thread_id)
+      @mutex.synchronize { @sessions[thread_id] }
+    end
+
+    def stop_session(thread_id)
+      @mutex.synchronize do
+        session = @sessions.delete(thread_id)
+        session&.kill
+        @session_store&.remove(thread_id)
+      end
+    end
+
+    def stop_all
+      @mutex.synchronize do
+        log(:info, "Stopping #{@sessions.size} session(s)...")
+        @sessions.each_value(&:kill)
+        @sessions.clear
+      end
+    end
+
+    def touch(thread_id)
+      @session_store&.touch(thread_id)
+    end
+
+    def resume_all
+      return unless @session_store
+
+      @session_store.load.each do |thread_id, persisted|
+        resume_session(thread_id, persisted) unless persisted.is_paused
+      end
+    end
+
+    def pause_all
+      @mutex.synchronize do
+        @sessions.each do |thread_id, session|
+          persist_ctx = PersistenceContext.new(channel_id: nil, working_dir: nil, paused: true)
+          @session_store&.save(thread_id, build_persisted(session, persist_ctx))
+          session.kill
+        end
+        @sessions.clear
+      end
+    end
+
+    include Persistence
+    include SessionCreation
+  end
+end

data/lib/earl/session_store.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Earl
+  # Persists session metadata to <config_root>/sessions.json for
+  # resuming sessions across EARL restarts. Uses an in-memory cache
+  # to avoid re-reading from disk on every save, preventing race
+  # conditions between concurrent save/touch calls.
+  class SessionStore
+    include Logging
+
+    # Snapshot of a Claude session's metadata for disk persistence and resume.
+    PersistedSession = Struct.new(:claude_session_id, :channel_id, :working_dir,
+                                  :started_at, :last_activity_at, :is_paused,
+                                  :message_count, :total_cost, :total_input_tokens,
+                                  :total_output_tokens, keyword_init: true)
+
+    def self.default_path
+      @default_path ||= File.join(Earl.config_root, "sessions.json")
+    end
+
+    def initialize(path: self.class.default_path)
+      @path = path
+      @mutex = Mutex.new
+      @cache = nil # Lazy-loaded from disk on first access
+    end
+
+    def load
+      @mutex.synchronize { cache.dup }
+    end
+
+    def save(thread_id, persisted_session)
+      @mutex.synchronize do
+        cache[thread_id] = persisted_session
+        write_store(@cache)
+      end
+    end
+
+    def remove(thread_id)
+      @mutex.synchronize do
+        cache.delete(thread_id)
+        write_store(@cache)
+      end
+    end
+
+    def touch(thread_id)
+      @mutex.synchronize do
+        session = cache[thread_id]
+        if session
+          session.last_activity_at = Time.now.iso8601
+          write_store(@cache)
+        end
+      end
+    end
+
+    private
+
+    def cache
+      @cache ||= read_store
+    end
+
+    def read_store
+      return {} unless File.exist?(@path)
+
+      raw = JSON.parse(File.read(@path))
+      raw.transform_values { |attrs| PersistedSession.new(**attrs.transform_keys(&:to_sym)) }
+    rescue JSON::ParserError, Errno::ENOENT => error
+      log(:warn, "Failed to read session store: #{error.message}")
+      {}
+    end
+
+    def write_store(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 Errno::ENOENT, Errno::EACCES, Errno::ENOSPC, IOError => error
+      log(:error, "Failed to write session store: #{error.message}")
+      FileUtils.rm_f(tmp_path) if tmp_path
+    end
+  end
+end

data/lib/earl/streaming_response.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Earl
+  # Manages the lifecycle of a single streamed response to Mattermost,
+  # including post creation, debounced updates, and typing indicators.
+  class StreamingResponse
+    include Logging
+    include ToolInputFormatter
+
+    DEBOUNCE_MS = 300
+    TOOL_PREFIXES = ToolInputFormatter::TOOL_ICONS.values.uniq.push("\u2699\uFE0F").freeze
+
+    # Holds the Mattermost thread and channel context for posting.
+    Context = Struct.new(:thread_id, :mattermost, :channel_id, keyword_init: true)
+    # Tracks the reply post lifecycle: ID, failure state, text, debounce timing, and typing thread.
+    PostState = Struct.new(:reply_post_id, :create_failed, :full_text, :last_update_at,
+                           :debounce_timer, :typing_thread, keyword_init: true)
+
+    def initialize(thread_id:, mattermost:, channel_id:)
+      @context = Context.new(thread_id: thread_id, mattermost: mattermost, channel_id: channel_id)
+      @post_state = PostState.new(create_failed: false, full_text: "", last_update_at: Time.now)
+      @segments = []
+      @mutex = Mutex.new
+    end
+
+    def channel_id
+      @context.channel_id
+    end
+
+    def start_typing
+      @post_state.typing_thread = Thread.new { typing_loop }
+    end
+
+    def on_text(text)
+      @mutex.synchronize { handle_text(text) }
+    rescue StandardError => error
+      log(:error, "Streaming error (thread #{short_id}): #{error.class}: #{error.message}")
+      log(:error, error.backtrace&.first(5)&.join("\n"))
+    end
+
+    def on_tool_use(tool_use)
+      @mutex.synchronize { handle_tool_use_display(tool_use) }
+    rescue StandardError => error
+      log(:error, "Tool use display error (thread #{short_id}): #{error.class}: #{error.message}")
+      log(:error, error.backtrace&.first(5)&.join("\n"))
+    end
+
+    def on_complete(**)
+      @mutex.synchronize { finalize }
+    rescue StandardError => error
+      log(:error, "Completion error (thread #{short_id}): #{error.class}: #{error.message}")
+      log(:error, error.backtrace&.first(5)&.join("\n"))
+    end
+
+    def stop_typing
+      @post_state.typing_thread&.kill
+      @post_state.typing_thread = nil
+    end
+
+    private
+
+    def typing_loop
+      loop do
+        send_typing_indicator
+        sleep 3
+      end
+    rescue StandardError => error
+      log(:warn, "Typing error (thread #{short_id}): #{error.class}: #{error.message}")
+    end
+
+    def send_typing_indicator
+      @context.mattermost.send_typing(channel_id: @context.channel_id, parent_id: @context.thread_id)
+    end
+
+    def handle_text(text)
+      @segments << text
+      @post_state.full_text = @segments.join("\n\n")
+      stop_typing
+
+      return if @post_state.create_failed
+      return create_initial_post(@post_state.full_text) unless posted?
+
+      schedule_update
+    end
+
+    def posted?
+      !!@post_state.reply_post_id
+    end
+
+    # Post creation and update lifecycle.
+    module PostUpdating
+      private
+
+      def create_initial_post(text)
+        result = @context.mattermost.create_post(channel_id: @context.channel_id, message: text,
+                                                 root_id: @context.thread_id)
+        post_id = result["id"]
+        return handle_create_failure unless post_id
+
+        @post_state.reply_post_id = post_id
+        @post_state.last_update_at = Time.now
+      end
+
+      def handle_create_failure
+        @post_state.create_failed = true
+        log(:error, "Failed to create post for thread #{short_id} \u2014 subsequent text will be dropped")
+      end
+
+      def schedule_update
+        elapsed_ms = (Time.now - @post_state.last_update_at) * 1000
+
+        if elapsed_ms >= DEBOUNCE_MS
+          update_post
+        else
+          start_debounce_timer
+        end
+      end
+
+      def start_debounce_timer
+        return if @post_state.debounce_timer
+
+        @post_state.debounce_timer = Thread.new do
+          sleep DEBOUNCE_MS / 1000.0
+          @mutex.synchronize { update_post }
+        end
+      end
+
+      def update_post
+        @post_state.debounce_timer = nil
+        @context.mattermost.update_post(post_id: @post_state.reply_post_id, message: @post_state.full_text)
+        @post_state.last_update_at = Time.now
+      end
+    end
+
+    # Finalization: completes the response and handles multi-segment posts.
+    module Finalization
+      private
+
+      def finalize
+        ps = @post_state
+        ps.debounce_timer&.join(1)
+        stop_typing
+        return if finalize_empty?(ps)
+
+        final_text = build_final_text
+        apply_final_text(ps, final_text)
+      end
+
+      def finalize_empty?(post_state)
+        post_state.full_text.empty? && !post_state.reply_post_id
+      end
+
+      def apply_final_text(post_state, final_text)
+        if only_text_segments?
+          post_state.full_text = final_text
+          update_post if post_state.reply_post_id
+        else
+          remove_last_text_from_streamed_post
+          create_notification_post(final_text)
+        end
+      end
+
+      def only_text_segments?
+        @segments.none? { |segment| tool_segment?(segment) }
+      end
+
+      def build_final_text
+        last_text = @segments.reverse.find { |segment| !tool_segment?(segment) }
+        last_text || @post_state.full_text
+      end
+
+      def remove_last_text_from_streamed_post
+        return unless posted?
+
+        last_text_index = @segments.rindex { |segment| !tool_segment?(segment) }
+        return unless last_text_index
+
+        @segments.delete_at(last_text_index)
+        @post_state.full_text = @segments.join("\n\n")
+        update_post unless @post_state.full_text.empty?
+      end
+
+      def create_notification_post(text)
+        @context.mattermost.create_post(
+          channel_id: @context.channel_id, message: text, root_id: @context.thread_id
+        )
+      end
+    end
+
+    include PostUpdating
+    include Finalization
+
+    def handle_tool_use_display(tool_use)
+      return if tool_use[:name] == "AskUserQuestion"
+
+      @segments << format_tool_use(tool_use)
+      @post_state.full_text = @segments.join("\n\n")
+      stop_typing
+
+      return if @post_state.create_failed
+      return create_initial_post(@post_state.full_text) unless posted?
+
+      schedule_update
+    end
+
+    def format_tool_use(tool_use)
+      name, input = tool_use.values_at(:name, :input)
+      format_tool_display(name, input)
+    end
+
+    def tool_segment?(segment)
+      TOOL_PREFIXES.any? { |prefix| segment.start_with?(prefix) }
+    end
+
+    def short_id
+      @context.thread_id[0..7]
+    end
+  end
+end

data/lib/earl/tmux/parsing.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Earl
+  module Tmux
+    # Private parsing helpers for tmux output formats.
+    # Extracted to keep the main Tmux module under the line limit.
+    module Parsing
+      private
+
+      def build_format(fields)
+        fields.map { |field| "\#{#{field}}" }.join(FIELD_SEP)
+      end
+
+      def parse_session_line(line)
+        parts = line.strip.split(FIELD_SEP, 3)
+        return if parts.size < 3
+
+        { name: parts[0], attached: parts[1] != "0",
+          created_at: Time.at(parts[2].to_i).strftime("%c") }
+      end
+
+      def no_server_or_sessions?(error)
+        msg = error.message
+        msg.include?("no server running") || msg.include?("no sessions")
+      end
+
+      def parse_pane_lines(output, field_count)
+        output.each_line.filter_map do |line|
+          parts = line.strip.split(FIELD_SEP, field_count)
+          next if parts.size < field_count
+
+          { index: parts[0].to_i, command: parts[1], path: parts[2], pid: parts[3].to_i }
+        end
+      end
+
+      def parse_all_pane_line(line, field_count)
+        parts = line.strip.split(FIELD_SEP, field_count)
+        return if parts.size < field_count
+
+        build_all_pane_hash(parts)
+      end
+
+      def build_all_pane_hash(parts)
+        session, window, pane_idx, command, path, pid, tty = parts
+        { target: "#{session}:#{window}.#{pane_idx}", session: session,
+          window: window.to_i, pane_index: pane_idx.to_i,
+          command: command, path: path, pid: pid.to_i, tty: tty }
+      end
+
+      def build_create_window_args(options)
+        session = options.fetch(:session)
+        name = options[:name]
+        working_dir = options[:working_dir]
+        command = options[:command]
+        args = ["tmux", "new-window", "-t", session]
+        args.push("-n", name) if name
+        args.push("-c", working_dir) if working_dir
+        args.push(command) if command
+        args
+      end
+
+      def fetch_parent_command(pid_str)
+        output, _status = Open3.capture2e("ps", "-o", "comm=", "-p", pid_str)
+        output.strip
+      end
+
+      def fetch_child_commands
+        output, = Open3.capture2e("ps", "-eo", "pid=,ppid=,comm=")
+        parse_process_entries(output)
+      end
+
+      def parse_process_entries(output)
+        output.each_line.filter_map do |line|
+          parts = line.strip.split(/\s+/, 3)
+          { ppid: parts[1], comm: parts[2] } if parts.size >= 3
+        end
+      end
+    end
+  end
+end

data/lib/earl/tmux/processes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Earl
+  module Tmux
+    # Process inspection: check for Claude on TTY, list child processes.
+    module Processes
+      def claude_on_tty?(tty)
+        check_tty_for_claude(tty)
+      end
+
+      def pane_child_commands(pid)
+        pid_str = pid.to_s
+        parent_comm = fetch_parent_command(pid_str)
+        all_entries = fetch_child_commands
+        child_comms = all_entries.filter_map { |entry| entry[:comm] if entry[:ppid] == pid_str }
+        ([parent_comm] + child_comms).reject(&:empty?)
+      rescue StandardError => error
+        Earl.logger.debug("Tmux.pane_child_commands failed for PID #{pid}: #{error.message}")
+        []
+      end
+
+      private
+
+      def check_tty_for_claude(tty)
+        tty_name = tty.sub(%r{\A/dev/}, "")
+        output, = Open3.capture2e("ps", "-t", tty_name, "-o", "command=") # nosemgrep
+        output.each_line.any? { |line| line.match?(%r{/claude\b|^claude\b}i) }
+      rescue StandardError => error
+        Earl.logger.debug("Tmux.claude_on_tty? failed for #{tty}: #{error.message}")
+        false
+      end
+    end
+  end
+end

data/lib/earl/tmux/sessions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Earl
+  module Tmux
+    # Session lifecycle: create, kill, check existence.
+    module Sessions
+      def create_session(name:, command: nil, working_dir: nil)
+        cmd = build_session_args(name, command, working_dir)
+        execute(*cmd)
+      end
+
+      def create_window(**options)
+        build_create_window_args(options).then { |args| execute(*args) }
+      end
+
+      def kill_session(name)
+        execute("tmux", "kill-session", "-t", name)
+      rescue Error => error
+        raise NotFound, "Session '#{name}' not found" if error.message.include?("can't find")
+
+        raise
+      end
+
+      def session_exists?(name)
+        execute("tmux", "has-session", "-t", name)
+        true
+      rescue Error
+        false
+      end
+
+      private
+
+      def build_session_args(name, command, working_dir)
+        args = ["tmux", "new-session", "-d", "-s", name]
+        args.push("-c", working_dir) if working_dir
+        args.push(command) if command
+        args
+      end
+    end
+  end
+end

data/lib/earl/tmux.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "tmux/parsing"
+require_relative "tmux/sessions"
+require_relative "tmux/processes"
+
+module Earl
+  # Shell wrapper module for interacting with tmux. Provides methods for
+  # listing sessions/panes, capturing output, sending keys, and managing
+  # sessions. All commands use Open3.capture2e for safe shell execution.
+  module Tmux
+    # Raised when a tmux command fails with a non-zero exit status.
+    class Error < StandardError; end
+
+    # Raised when a tmux session or pane cannot be found.
+    class NotFound < Error; end
+
+    SEND_KEYS_DELAY = 0.1
+    FIELD_SEP = "|||"
+    # Configuration for wait_for_text polling behavior.
+    WaitConfig = Data.define(:timeout, :interval, :lines)
+    WAIT_DEFAULTS = { timeout: 15, interval: 0.5, lines: 200 }.freeze
+    # Specification for creating a new tmux window.
+    WindowSpec = Data.define(:session, :name, :command, :working_dir)
+
+    PANE_FIELDS = %w[pane_index pane_current_command pane_current_path pane_pid].freeze
+    ALL_PANE_FIELDS = %w[session_name window_index pane_index pane_current_command
+                         pane_current_path pane_pid pane_tty].freeze
+
+    module_function
+
+    def available?
+      _, status = Open3.capture2e("which", "tmux")
+      status.success?
+    end
+
+    def list_sessions
+      fmt = build_format(%w[session_name session_attached session_created])
+      output = execute("tmux", "list-sessions", "-F", fmt)
+      output.each_line.filter_map { |line| parse_session_line(line) }
+    rescue Error => error
+      return [] if no_server_or_sessions?(error)
+
+      raise
+    end
+
+    def list_panes(session)
+      fmt = build_format(PANE_FIELDS)
+      output = execute("tmux", "list-panes", "-t", session, "-F", fmt)
+      parse_pane_lines(output, PANE_FIELDS.size)
+    rescue Error => error
+      raise NotFound, "Session '#{session}' not found" if error.message.include?("can't find")
+
+      raise
+    end
+
+    def list_all_panes
+      field_count = ALL_PANE_FIELDS.size
+      fmt = build_format(ALL_PANE_FIELDS)
+      output = execute("tmux", "list-panes", "-a", "-F", fmt)
+      output.each_line.filter_map { |line| parse_all_pane_line(line, field_count) }
+    rescue Error => error
+      return [] if no_server_or_sessions?(error)
+
+      raise
+    end
+
+    def capture_pane(target, lines: 100)
+      execute("tmux", "capture-pane", "-t", target, "-p", "-J", "-S", "-#{lines}")
+    rescue Error => error
+      raise NotFound, "Target '#{target}' not found" if error.message.include?("can't find")
+
+      raise
+    end
+
+    def send_keys(target, text)
+      execute("tmux", "send-keys", "-t", target, "-l", "--", text)
+      sleep SEND_KEYS_DELAY
+      execute("tmux", "send-keys", "-t", target, "Enter")
+    end
+
+    def send_keys_raw(target, key)
+      execute("tmux", "send-keys", "-t", target, key)
+    end
+
+    def wait_for_text(target, pattern, **)
+      config = WaitConfig.new(**WAIT_DEFAULTS, **)
+      regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
+      poll_until_match(target, regex, config)
+    end
+
+    class << self
+      include Parsing
+      include Sessions
+      include Processes
+
+      private
+
+      def execute(*cmd)
+        output, status = Open3.capture2e(*cmd)
+        raise Error, "tmux command failed: #{cmd.join(" ")}: #{output.strip}" unless status.success?
+
+        output
+      end
+
+      def poll_until_match(target, regex, config)
+        remaining = config.timeout
+        poll_interval = config.interval
+
+        loop do
+          output = capture_pane(target, lines: config.lines)
+          return output if output.match?(regex)
+          return nil if remaining <= 0
+
+          sleep poll_interval
+          remaining -= poll_interval
+        end
+      end
+    end
+  end
+end