earl-bot 0.1.0

data/lib/earl/command_executor/session_handler.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Earl
+  class CommandExecutor
+    # Handles tmux session commands: !sessions, !session <name> show/status/
+    # input/nudge/approve/deny/kill.
+    module SessionHandler
+      PANE_STATUS_LABELS = {
+        active: "\u{1F7E2} Active", permission: "\u{1F7E0} Waiting for permission", idle: "\u{1F7E1} Idle"
+      }.freeze
+
+      private
+
+      def handle_sessions(ctx)
+        tmux = @deps.tmux
+        return reply(ctx, ":x: tmux is not installed.") unless tmux.available?
+
+        panes = tmux.list_all_panes
+        return reply(ctx, "No tmux sessions running.") if panes.empty?
+
+        claude_panes = panes.select { |pane| tmux.claude_on_tty?(pane[:tty]) }
+        return reply(ctx, "No Claude sessions found across #{panes.size} tmux panes.") if claude_panes.empty?
+
+        reply(ctx, format_sessions_table(claude_panes))
+      end
+
+      def format_sessions_table(claude_panes)
+        rows = claude_panes.map { |pane| format_claude_pane_row(pane) }
+        header = [
+          "#### :computer: Claude Sessions (#{rows.size})",
+          "| Pane | Project | Status |", "|------|---------|--------|"
+        ]
+        (header + rows).join("\n")
+      end
+
+      def format_claude_pane_row(pane)
+        target, path = pane.values_at(:target, :path)
+        project = File.basename(path)
+        status = detect_pane_status(target)
+        label = PANE_STATUS_LABELS.fetch(status, "\u{1F7E1} Idle")
+        "| `#{target}` | #{project} | #{label} |"
+      end
+
+      def detect_pane_status(target)
+        output = @deps.tmux.capture_pane(target, lines: 20)
+        return :permission if output.include?("Do you want to proceed?")
+        return :active if output.include?("esc to interrupt")
+
+        :idle
+      rescue Tmux::Error => error
+        log(:debug, "detect_pane_status failed for #{target}: #{error.message}")
+        :idle
+      end
+
+      def handle_session_show(ctx)
+        with_tmux_session(ctx) do
+          target = ctx.arg
+          output = @deps.tmux.capture_pane(target)
+          reply(ctx, "#### :computer: `#{target}` pane output\n```\n#{truncate_output(output)}\n```")
+        end
+      end
+
+      def handle_session_status(ctx)
+        with_tmux_session(ctx) do
+          target = ctx.arg
+          output = @deps.tmux.capture_pane(target, lines: 200)
+          truncated = truncate_output(output, 3000)
+          reply(ctx, "#### :mag: `#{target}` status\n```\n#{truncated}\n```\n_AI summary not yet implemented._")
+        end
+      end
+
+      def handle_session_input(ctx)
+        with_tmux_session(ctx) do
+          target = ctx.arg
+          text = ctx.args[1]
+          @deps.tmux.send_keys(target, text)
+          reply(ctx, ":keyboard: Sent to `#{target}`: `#{text}`")
+        end
+      end
+
+      def handle_session_nudge(ctx)
+        with_tmux_session(ctx) do
+          target = ctx.arg
+          @deps.tmux.send_keys(target, "Are you stuck? What's your current status?")
+          reply(ctx, ":wave: Nudged `#{target}`.")
+        end
+      end
+
+      def handle_session_approve(ctx) = send_tmux_key_action(ctx, "Enter", ":white_check_mark: Approved permission on")
+      def handle_session_deny(ctx) = send_tmux_key_action(ctx, "Escape", ":no_entry_sign: Denied permission on")
+
+      def handle_session_kill(ctx)
+        name = ctx.arg
+        store = @deps.tmux_store
+        @deps.tmux.kill_session(name)
+        store&.delete(name)
+        reply(ctx, ":skull: Tmux session `#{name}` killed.")
+      rescue Tmux::NotFound
+        store&.delete(name)
+        reply(ctx, ":x: Session `#{name}` not found (cleaned up store).")
+      rescue Tmux::Error => error
+        reply(ctx, ":x: Error killing session: #{error.message}")
+      end
+
+      def with_tmux_session(ctx)
+        yield
+      rescue Tmux::NotFound
+        reply(ctx, ":x: Session `#{ctx.arg}` not found.")
+      rescue Tmux::Error => error
+        reply(ctx, ":x: Error: #{error.message}")
+      end
+
+      def truncate_output(output, max_length = 3500)
+        output.length > max_length ? "\u2026#{output[-max_length..]}" : output
+      end
+
+      def send_tmux_key_action(ctx, key, message_prefix)
+        with_tmux_session(ctx) do
+          target = ctx.arg
+          @deps.tmux.send_keys_raw(target, key)
+          reply(ctx, "#{message_prefix} `#{target}`.")
+        end
+      end
+    end
+  end
+end

data/lib/earl/command_executor/spawn_handler.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Earl
+  class CommandExecutor
+    # Handles the !spawn command — creates a new Claude session in tmux.
+    module SpawnHandler
+      # Bundles spawn parameters extracted from the command.
+      SpawnRequest = Struct.new(:name, :prompt, :working_dir, keyword_init: true) do
+        def to_session_info(ctx)
+          TmuxSessionStore::TmuxSessionInfo.new(
+            name: name, channel_id: ctx.channel_id, thread_id: ctx.thread_id,
+            working_dir: working_dir, prompt: prompt, created_at: Time.now.iso8601
+          )
+        end
+      end
+
+      private
+
+      def handle_spawn(ctx)
+        prompt = ctx.arg
+        return reply(ctx, ':x: Usage: `!spawn "prompt" [--name N] [--dir D]`') if prompt.to_s.strip.empty?
+
+        req = build_spawn_request(prompt, ctx.args[1].to_s)
+        validate_and_spawn(ctx, req)
+      rescue Tmux::Error => error
+        reply(ctx, ":x: Failed to spawn session: #{error.message}")
+      end
+
+      def build_spawn_request(prompt, flags_str)
+        parsed = parse_spawn_flags(flags_str)
+        name = parsed[:name] || generate_session_name
+        SpawnRequest.new(name: name, prompt: prompt, working_dir: parsed[:dir])
+      end
+
+      def generate_session_name
+        "earl-#{Time.now.strftime("%Y%m%d%H%M%S")}"
+      end
+
+      def validate_and_spawn(ctx, req)
+        name = req.name
+        return if spawn_name_invalid?(ctx, name)
+        return if spawn_dir_invalid?(ctx, req.working_dir)
+        return if spawn_name_taken?(ctx, name)
+
+        spawn_tmux_session(ctx, req)
+      end
+
+      def spawn_name_invalid?(ctx, name)
+        return false unless name.match?(/[.:]/)
+
+        reply(ctx, ":x: Invalid session name `#{name}`: cannot contain `.` or `:` (tmux reserved).")
+        true
+      end
+
+      def spawn_dir_invalid?(ctx, working_dir)
+        return false unless working_dir
+        return false if Dir.exist?(working_dir)
+
+        reply(ctx, ":x: Directory not found: `#{working_dir}`")
+        true
+      end
+
+      def spawn_name_taken?(ctx, name)
+        return false unless @deps.tmux.session_exists?(name)
+
+        reply(ctx, ":x: Session `#{name}` already exists.")
+        true
+      end
+
+      def spawn_tmux_session(ctx, req)
+        name = req.name
+        command = "claude #{Shellwords.shellescape(req.prompt)}"
+        @deps.tmux.create_session(name: name, command: command, working_dir: req.working_dir)
+        persist_spawn_info(req.to_session_info(ctx))
+        reply(ctx, spawn_success_message(req))
+      end
+
+      def persist_spawn_info(info)
+        store = @deps.tmux_store
+        store&.save(info)
+      end
+
+      def spawn_success_message(req)
+        name = req.name
+        ":rocket: Spawned tmux session `#{name}`\n" \
+          "- **Prompt:** #{req.prompt}\n" \
+          "- **Dir:** #{req.working_dir || Dir.pwd}\n" \
+          "Use `!session #{name}` to check output."
+      end
+
+      def parse_spawn_flags(str)
+        {
+          dir: str[/--dir\s+(\S+)/, 1],
+          name: str[/--name\s+(\S+)/, 1]
+        }.compact
+      end
+    end
+  end
+end

data/lib/earl/command_executor/stats_formatter.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Earl
+  class CommandExecutor
+    # Formats session statistics for the !stats command.
+    module StatsFormatter
+      private
+
+      def format_stats(stats)
+        total_in = stats.total_input_tokens
+        total_out = stats.total_output_tokens
+        cost = stats.total_cost
+        header = ["#### :bar_chart: Session Stats", "| Metric | Value |", "|--------|-------|"]
+        rows = [format_token_row(total_in, total_out)]
+        append_optional_stats(rows, stats)
+        rows << format_cost_row(cost)
+        (header + rows).join("\n")
+      end
+
+      def append_optional_stats(lines, stats)
+        append_context_line(lines, stats)
+        append_model_line(lines, stats.model_id)
+        append_ttft_line(lines, stats.time_to_first_token)
+        append_speed_line(lines, stats.tokens_per_second)
+      end
+
+      def append_context_line(lines, stats)
+        pct = stats.context_percent
+        return unless pct
+
+        lines << "| **Context used** | #{format("%.1f%%", pct)} of #{format_number(stats.context_window)} |"
+      end
+
+      def append_model_line(lines, model)
+        lines << "| **Model** | `#{model}` |" if model
+      end
+
+      def append_ttft_line(lines, ttft)
+        lines << "| **Last TTFT** | #{format("%.1fs", ttft)} |" if ttft
+      end
+
+      def append_speed_line(lines, tps)
+        lines << "| **Last speed** | #{format("%.0f", tps)} tok/s |" if tps
+      end
+
+      def format_persisted_stats(persisted)
+        total_in, total_out, cost = persisted.to_h.values_at(
+          :total_input_tokens, :total_output_tokens, :total_cost
+        )
+        token_row = format_token_row(total_in || 0, total_out || 0)
+        cost_row = format_cost_row(cost)
+        ["#### :bar_chart: Session Stats (stopped)", "| Metric | Value |", "|--------|-------|",
+         token_row, cost_row].join("\n")
+      end
+
+      def format_token_row(total_in, total_out)
+        total = format_number(total_in + total_out)
+        "| **Total tokens** | #{total} (in: #{format_number(total_in)}, out: #{format_number(total_out)}) |"
+      end
+
+      def format_cost_row(cost)
+        "| **Cost** | $#{format("%.4f", cost)} |"
+      end
+    end
+  end
+end

data/lib/earl/command_executor/usage_handler.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Earl
+  class CommandExecutor
+    # Handles !usage and !context commands — fetches external data
+    # via background threads and posts formatted results.
+    module UsageHandler
+      CONTEXT_CATEGORIES = {
+        "messages" => "Messages", "system_prompt" => "System prompt",
+        "system_tools" => "System tools", "custom_agents" => "Custom agents",
+        "memory_files" => "Memory files", "skills" => "Skills",
+        "free_space" => "Free space", "autocompact_buffer" => "Autocompact buffer"
+      }.freeze
+
+      private
+
+      def handle_usage(ctx)
+        reply(ctx, ":hourglass: Fetching usage data (takes ~15s)...")
+        run_usage_fetch(ctx)
+      end
+
+      def run_usage_fetch(ctx)
+        Thread.new { usage_fetch_body(ctx) }
+      end
+
+      def usage_fetch_body(ctx)
+        data = fetch_usage_data
+        message = data ? format_usage(data) : ":x: Failed to fetch usage data."
+        reply(ctx, message)
+      rescue StandardError => error
+        msg = error.message
+        log(:error, "Usage command error: #{msg}")
+        reply(ctx, ":x: Error fetching usage: #{msg}")
+      end
+
+      def fetch_usage_data
+        output, status = Open3.capture2(USAGE_SCRIPT, "--json", err: File::NULL)
+        return nil unless status.success?
+
+        JSON.parse(output)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def format_usage(data)
+        lines = ["#### :bar_chart: Claude Usage"]
+        append_usage_section(lines, data["session"], "Session")
+        append_usage_section(lines, data["week"], "Week")
+        append_usage_section(lines, data["sonnet_week"], "Sonnet")
+        append_usage_extra(lines, data["extra"])
+        lines.join("\n")
+      end
+
+      def append_usage_section(lines, section, label)
+        return unless section&.dig("percent_used")
+
+        lines << "- **#{label}:** #{section["percent_used"]}% used \u2014 resets #{section["resets"]}"
+      end
+
+      def append_usage_extra(lines, extra)
+        return unless extra&.dig("percent_used")
+
+        pct, spent, budget, resets = extra.values_at("percent_used", "spent", "budget", "resets")
+        lines << "- **Extra:** #{pct}% used (#{spent} / #{budget}) \u2014 resets #{resets}"
+      end
+
+      def handle_context(ctx)
+        sid = @deps.session_manager.claude_session_id_for(ctx.thread_id)
+        unless sid
+          reply(ctx, "No session found for this thread.")
+          return
+        end
+
+        reply(ctx, ":hourglass: Fetching context data (takes ~20s)...")
+        run_context_fetch(ctx, sid)
+      end
+
+      def run_context_fetch(ctx, sid)
+        Thread.new { context_fetch_body(ctx, sid) }
+      end
+
+      def context_fetch_body(ctx, sid)
+        data = fetch_context_data(sid)
+        message = data ? format_context(data) : ":x: Failed to fetch context data."
+        reply(ctx, message)
+      rescue StandardError => error
+        msg = error.message
+        log(:error, "Context command error: #{msg}")
+        reply(ctx, ":x: Error fetching context: #{msg}")
+      end
+
+      def fetch_context_data(session_id)
+        output, status = Open3.capture2(CONTEXT_SCRIPT, session_id, "--json", err: File::NULL) # nosemgrep
+        return nil unless status.success?
+
+        JSON.parse(output)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def format_context(data)
+        model, used, total, pct, cats = data.values_at("model", "used_tokens", "total_tokens", "percent_used",
+                                                       "categories")
+        lines = [
+          "#### :brain: Context Window Usage",
+          "- **Model:** `#{model}`",
+          "- **Used:** #{used} / #{total} tokens (#{pct})"
+        ]
+        append_context_categories(lines, cats)
+        lines.join("\n")
+      end
+
+      def append_context_categories(lines, cats)
+        return unless cats
+
+        lines << ""
+        CONTEXT_CATEGORIES.each do |key, label|
+          append_category_line(lines, cats[key], label)
+        end
+      end
+
+      def append_category_line(lines, cat, label)
+        tokens = cat&.fetch("tokens", nil)
+        return unless tokens
+
+        pct_val = cat["percent"]
+        pct = pct_val ? " (#{pct_val})" : ""
+        lines << "- **#{label}:** #{tokens} tokens#{pct}"
+      end
+    end
+  end
+end

data/lib/earl/command_executor.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+require_relative "command_executor/constants"
+require_relative "command_executor/lifecycle_handler"
+require_relative "command_executor/session_handler"
+require_relative "command_executor/spawn_handler"
+require_relative "command_executor/stats_formatter"
+require_relative "command_executor/usage_handler"
+require_relative "command_executor/heartbeat_display"
+
+module Earl
+  # Executes `!` commands parsed by CommandParser, dispatching to the
+  # appropriate session manager or mattermost action.
+  class CommandExecutor
+    include Logging
+    include Formatting
+    include Constants
+    include LifecycleHandler
+    include SessionHandler
+    include SpawnHandler
+    include StatsFormatter
+    include UsageHandler
+    include HeartbeatDisplay
+
+    # Bundles dispatch context so thread_id + channel_id don't travel as separate args.
+    CommandContext = Data.define(:thread_id, :channel_id, :arg, :args) do
+      def post_params(message)
+        { channel_id: channel_id, message: message, root_id: thread_id }
+      end
+    end
+
+    # Groups injected dependencies to keep ivar count low.
+    Deps = Struct.new(:session_manager, :mattermost, :config, :heartbeat_scheduler,
+                      :tmux_store, :tmux, :runner, keyword_init: true)
+
+    def initialize(session_manager:, mattermost:, config:, **extras)
+      heartbeat_scheduler, tmux_store, tmux_adapter, runner = extras.values_at(:heartbeat_scheduler, :tmux_store,
+                                                                               :tmux_adapter, :runner)
+      @deps = Deps.new(
+        session_manager: session_manager, mattermost: mattermost, config: config,
+        heartbeat_scheduler: heartbeat_scheduler, tmux_store: tmux_store, tmux: tmux_adapter || Tmux, runner: runner
+      )
+      @working_dirs = {} # thread_id -> path
+    end
+
+    # Returns { passthrough: "/command" } for passthrough commands so the
+    # runner can route them through the normal message pipeline.
+    # Returns nil for all other commands (handled inline).
+    def execute(command, thread_id:, channel_id:)
+      cmd_name = command.name
+      slash = PASSTHROUGH_COMMANDS[cmd_name]
+      return { passthrough: slash } if slash
+
+      ctx = build_context(command, thread_id, channel_id)
+      dispatch_command(cmd_name, ctx)
+      nil
+    end
+
+    def working_dir_for(thread_id)
+      @working_dirs[thread_id]
+    end
+
+    private
+
+    def dispatch_command(name, ctx)
+      handler = DISPATCH[name]
+      send(handler, ctx) if handler
+    end
+
+    def build_context(command, thread_id, channel_id)
+      cmd_args = command.args
+      CommandContext.new(thread_id: thread_id, channel_id: channel_id, arg: cmd_args.first, args: cmd_args)
+    end
+
+    def handle_help(ctx)
+      reply(ctx, HELP_TABLE)
+    end
+
+    def handle_update(ctx)
+      reply(ctx, ":arrows_counterclockwise: Updating EARL...")
+      save_restart_context(ctx, "update")
+      @deps.runner&.request_update
+    end
+
+    def handle_restart(ctx)
+      reply(ctx, ":arrows_counterclockwise: Restarting EARL...")
+      save_restart_context(ctx, "restart")
+      @deps.runner&.request_restart
+    end
+
+    def save_restart_context(ctx, command)
+      config_dir = Earl.config_root
+      FileUtils.mkdir_p(config_dir)
+      path = File.join(config_dir, "restart_context.json")
+      data = ctx.deconstruct_keys(%i[channel_id thread_id]).merge(command: command)
+      File.write(path, JSON.generate(data))
+    rescue StandardError => error
+      log(:warn, "Failed to save restart context: #{error.message}")
+    end
+
+    def handle_permissions(ctx)
+      reply(ctx, "Permission mode is controlled via `EARL_SKIP_PERMISSIONS` env var.")
+    end
+
+    def handle_stats(ctx)
+      session = @deps.session_manager.get(ctx.thread_id)
+      return reply(ctx, format_stats(session.stats)) if session
+
+      reply_persisted_stats(ctx)
+    end
+
+    def reply_persisted_stats(ctx)
+      persisted = @deps.session_manager.persisted_session_for(ctx.thread_id)
+      if persisted&.total_cost
+        reply(ctx, format_persisted_stats(persisted))
+      else
+        reply(ctx, "No active session for this thread.")
+      end
+    end
+
+    def reply(ctx, message)
+      @deps.mattermost.create_post(**ctx.post_params(message))
+    end
+  end
+end

data/lib/earl/command_parser.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Earl
+  # Parses `!` prefixed commands from user messages in Mattermost.
+  # Returns a ParsedCommand struct or nil if the message is not a command.
+  class CommandParser
+    # A parsed chat command with name and arguments.
+    ParsedCommand = Struct.new(:name, :args, keyword_init: true)
+
+    COMMANDS = {
+      /\A!stop\z/i => :stop,
+      /\A!escape\z/i => :escape,
+      /\A!kill\z/i => :kill,
+      /\A!help\z/i => :help,
+      /\A!stats\z/i => :stats,
+      /\A!cost\z/i => :stats,
+      /\A!compact\z/i => :compact,
+      /\A!cd\s+(.+)\z/i => :cd,
+      /\A!permissions\z/i => :permissions,
+      /\A!heartbeats\z/i => :heartbeats,
+      /\A!usage\z/i => :usage,
+      /\A!context\z/i => :context,
+      /\A!sessions\z/i => :sessions,
+      # Specific !session subcommands must come before catch-all
+      /\A!session\s+(\S+)\s+status\z/i => :session_status,
+      /\A!session\s+(\S+)\s+kill\z/i => :session_kill,
+      /\A!session\s+(\S+)\s+nudge\z/i => :session_nudge,
+      /\A!session\s+(\S+)\s+approve\z/i => :session_approve,
+      /\A!session\s+(\S+)\s+deny\z/i => :session_deny,
+      /\A!session\s+(\S+)\s+"([^"]+)"\z/i => :session_input,
+      /\A!session\s+(\S+)\s+'([^']+)'\z/i => :session_input,
+      /\A!session\s+(\S+)\z/i => :session_show,
+      /\A!update\z/i => :update,
+      /\A!restart\z/i => :restart,
+      /\A!spawn\s+"([^"]+)"(.*)\z/i => :spawn
+    }.freeze
+
+    def self.command?(text)
+      text.strip.start_with?("!")
+    end
+
+    def self.parse(text)
+      stripped = text.strip
+      return nil unless stripped.start_with?("!")
+
+      COMMANDS.each do |pattern, name|
+        match = stripped.match(pattern)
+        next unless match
+
+        args = match.captures
+        return ParsedCommand.new(name: name, args: args)
+      end
+
+      nil
+    end
+  end
+end