agents_control 0.1.0

data/lib/agents_control/prompt.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # A line input with arrow-key command selection.
+  #
+  # Written by hand because reline can't do this: its own list moves
+  # with Tab and Ctrl-N, arrows are already claimed by history, and
+  # there's no way to remap them just while the list is open. And
+  # picking with arrows is exactly what you'd expect from a line that starts with a slash.
+  class Prompt
+    include Keyboard
+
+    # How many list rows to show at once.
+    WINDOW = 8
+
+    def initialize(input: $stdin, output: $stdout, completer: nil, describer: nil)
+      @in = input
+      @out = output
+      @completer = completer || ->(_word) { [] }
+      @describer = describer || ->(_item) { nil }
+      @history = []
+    end
+
+    # Returns the entered line, or nil if input closed (Ctrl-D).
+    def read(prompt_text)
+      @prompt = prompt_text
+      @buffer = +""
+      @cursor = 0
+      @selected = 0
+      @dismissed = false
+      @drawn = 0
+      @history_at = @history.size
+      @result = nil
+
+      render
+      @in.raw { loop { break if handle(read_key) == :done } }
+
+      @result
+    ensure
+      finish
+    end
+
+    private
+
+    # ── the loop ──────────────────────────────────────────────────────────
+
+    # Returns a string once input is done, and nil to keep going.
+    def handle(key)
+      # Input was closed: that's the end, not an empty line.
+      return finish_line(nil) if key.nil?
+
+      case key
+      when CTRL_C then raise Interrupt
+      when CTRL_D then @buffer.empty? ? finish_line(nil) : nil
+      when *ENTER then accept
+      when UP then move(-1)
+      when DOWN then move(+1)
+      when LEFT then step(-1)
+      when RIGHT then step(+1)
+      when TAB then take_selection
+      when ESC then dismiss
+      when *BACKSPACE then erase
+      when CTRL_A then jump(0)
+      when CTRL_E then jump(@buffer.length)
+      when CTRL_U then clear_line
+      else insert(key)
+      end
+    end
+
+    def accept
+      return take_selection if menu?
+
+      @history.push(@buffer) unless @buffer.strip.empty? || @history.last == @buffer
+      finish_line(@buffer)
+    end
+
+    # Enter on a selected item fills in the command but doesn't run it:
+    # half the commands take an argument, and running without one would be a surprise.
+    def take_selection
+      return render unless menu?
+
+      @buffer = +"#{candidates[@selected]} "
+      @cursor = @buffer.length
+      @dismissed = true
+      render
+      nil
+    end
+
+    def finish_line(value = @buffer)
+      @result = value
+      :done
+    end
+
+    # ── editing the line ─────────────────────────────────────────────────────
+
+    # Unrecognized control sequences are silently dropped: inserted into
+    # the line, they'd turn into garbage.
+    def insert(key)
+      return nil if key.length > 1 || key.ord < 0x20
+
+      @buffer.insert(@cursor, key)
+      @cursor += key.length
+      @dismissed = false
+      @selected = 0
+      render
+      nil
+    end
+
+    def erase
+      return render if @cursor.zero?
+
+      @buffer.slice!(@cursor - 1)
+      @cursor -= 1
+      @selected = 0
+      render
+      nil
+    end
+
+    def clear_line
+      @buffer = +""
+      @cursor = 0
+      render
+      nil
+    end
+
+    def step(delta)
+      @cursor = (@cursor + delta).clamp(0, @buffer.length)
+      render
+      nil
+    end
+
+    def jump(position)
+      @cursor = position
+      render
+      nil
+    end
+
+    # ── list and history ──────────────────────────────────────────────────
+
+    def move(delta)
+      return history(delta) unless menu?
+
+      @selected = (@selected + delta) % candidates.size
+      render
+      nil
+    end
+
+    def history(delta)
+      @history_at = (@history_at + delta).clamp(0, @history.size)
+      @buffer = +(@history[@history_at] || "")
+      @cursor = @buffer.length
+      render
+      nil
+    end
+
+    def dismiss
+      @dismissed = true
+      render
+      nil
+    end
+
+    # The list only shows for a line starting with a slash and no space
+    # yet: after that come arguments, and a hint there would just get in the way.
+    def menu?
+      return false if @dismissed || !@buffer.start_with?("/") || @buffer.include?(" ")
+
+      !candidates.empty?
+    end
+
+    # A copy, not the buffer itself: the line is edited in place, and a
+    # reference to it would always equal itself — the cache would never invalidate.
+    def candidates
+      if @candidates_source != @buffer
+        @candidates_source = @buffer.dup
+        @candidates_for = Array(@completer.call(@buffer))
+      end
+
+      @candidates_for
+    end
+
+    # ── drawing ─────────────────────────────────────────────────────────────
+
+    def render
+      erase_drawn
+      @out.print("\r#{@prompt}#{@buffer}")
+
+      rows = menu? ? draw_menu : 0
+      @out.print("\e[#{rows}A") if rows.positive?
+      @out.print("\r\e[#{visible_width(@prompt) + @cursor}C") if visible_width(@prompt) + @cursor > 0
+
+      @drawn = rows
+      nil
+    end
+
+    def erase_drawn
+      @out.print("\r\e[J")
+    end
+
+    def draw_menu
+      window.each_with_index do |item, index|
+        line = " #{item.ljust(12)} #{@describer.call(item)}".rstrip
+        @out.print("\r\n")
+        @out.print(item == candidates[@selected] ? "\e[7m#{line}\e[0m" : line)
+      end
+
+      window.size
+    end
+
+    # The scroll window: the selected item is always visible, even if
+    # there are more commands than fit.
+    def window
+      return candidates if candidates.size <= WINDOW
+
+      top = (@selected - WINDOW / 2).clamp(0, candidates.size - WINDOW)
+      candidates[top, WINDOW]
+    end
+
+    def visible_width(text) = text.gsub(/\e\[[0-9;]*[A-Za-z]/, "").length
+
+    def finish
+      erase_drawn
+      @out.print("\r#{@prompt}#{@buffer}\r\n")
+      @out.flush
+    end
+
+  end
+end

data/lib/agents_control/rate_limit_watcher.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "time"
+
+module AgentsControl
+  # Notices a rate-limit message on an agent's screen and types
+  # "continue" itself at the exact moment the limit resets.
+  #
+  # Three message formats:
+  #
+  #   5-hour limit reached - resets 3pm (UTC)
+  #   You've hit your session limit · resets 2am (Europe/Zurich)
+  #   You've hit your weekly limit · resets Oct 9, 10am
+  #
+  # Goes through the full Registry, not just tmux (unlike ScreenWatcher)
+  # — a limit doesn't hit every few seconds, so polling once a minute
+  # keeps the cost of scanning iTerm2 via AppleScript low.
+  class RateLimitWatcher
+    # "limit ... resets [at] <everything to the end of the line>".
+    PATTERN = /\blimit\b.{0,60}?\bresets?\b\s*(?:at\s+)?(.+?)\s*$/i
+
+    # A timezone in parentheses at the end of the line, if present — for
+    # display to the human. Not accounted for programmatically: Time.parse
+    # treats the time as local to the machine the daemon runs on.
+    ZONE = /\(([\w\/]+)\)\s*\z/
+
+    # A month name in the rest of the line distinguishes a bare time of
+    # day ("3pm", today or tomorrow) from a weekly-limit date ("Oct 9").
+    HAS_DATE = /[A-Za-z]{3,}\s+\d{1,2}/
+
+    GRACE = 60
+    LINES = 20
+
+    def initialize(registry:, config:, store:, api:, interval: 60, clock: -> { Time.now }, logger: nil)
+      @registry = registry
+      @config = config
+      @store = store
+      @api = api
+      @interval = interval
+      @clock = clock
+      @logger = logger
+      @running = false
+    end
+
+    def start
+      return self unless enabled?
+
+      @running = true
+      @thread = Thread.new { tick while @running }
+      self
+    end
+
+    def stop
+      @running = false
+      @thread&.kill
+    end
+
+    def tick
+      candidates.each { |session| check(session) } if enabled?
+    rescue StandardError => e
+      log("failure: #{e.class}: #{e.message}")
+    ensure
+      sleep(@interval) if @running
+    end
+
+    private
+
+    def now = @clock.call
+
+    def enabled? = @config.get("answers.auto_resume_after_limit", true)
+
+    def candidates
+      @registry.refresh.agents.reject(&:terminalless?)
+    rescue StandardError
+      []
+    end
+
+    # A limit, once detected, isn't dropped just because the screen
+    # currently shows something else — only once it's actually fired. By
+    # reset time, the original message has almost certainly scrolled off
+    # the screen already, and reset_at has to survive exactly that.
+    def check(session)
+      spec = detect(@registry.backend_for(session).capture(session.id, lines: LINES))
+      key = resume_key(session)
+      saved = @store.get(key)
+
+      return remember(session, key, spec) if spec && (saved.nil? || saved["spec"] != spec)
+      return unless saved
+      return if saved["fired"]
+
+      fire(session, key, saved) if now >= Time.parse(saved["reset_at"]) + GRACE
+    end
+
+    def resume_key(session) = "resume:#{session.id}"
+
+    # The last textual match — the one closest to the screen's current
+    # state, not a random mention of a limit somewhere in the scrollback.
+    def detect(text)
+      text.to_s.each_line.map(&:chomp).filter_map { |line| line[PATTERN, 1] }.last
+    end
+
+    def remember(session, key, spec)
+      reset_at = parse_reset_time(spec)
+      return notify_unparseable(session, spec) unless reset_at
+
+      @store.put({ "spec" => spec, "reset_at" => reset_at.iso8601, "fired" => false },
+                 ttl: 86_400, key: key)
+      notify_detected(session, spec, reset_at)
+    end
+
+    def parse_reset_time(spec)
+      zone = spec[ZONE, 1]
+      clean = spec.sub(ZONE, "").strip
+      return nil if clean.empty?
+
+      time = Time.parse(clean, now)
+
+      # A bare time of day in the past means "tomorrow"; a weekly-limit
+      # date in the past means "a year has rolled over," not "the reset
+      # was yesterday."
+      if time < now
+        time += clean.match?(HAS_DATE) ? 365 * 86_400 : 86_400
+      end
+
+      time
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # The session could have closed between detecting the limit and the
+    # reset moment — checked right before typing, not trusted from the
+    # state at detection time.
+    def fire(session, key, saved)
+      fresh = @registry.refresh.find(session.id)
+
+      unless fresh&.agent?
+        @store.delete(key)
+        return
+      end
+
+      ok = type_resume(fresh)
+      @store.put(saved.merge("fired" => true), ttl: 3600, key: key)
+
+      broadcast("✅ #{fresh.label}: the limit reset, sent \"#{resume_message}\".", session: fresh) if ok
+    end
+
+    def type_resume(session)
+      backend = @registry.backend_for(session)
+      backend.send_text(session.id, resume_message, newline: false) &&
+        sleep(0.4).then { backend.send_text(session.id, "", newline: true) }
+    end
+
+    def resume_message
+      @config.get("answers.resume_message",
+                  "Continue where you left off — the previous attempt was rate limited.")
+    end
+
+    def notify_detected(session, spec, reset_at)
+      broadcast("⏳ #{session.label} hit a limit: \"#{spec}\".\n" \
+                "Resets at #{reset_at.strftime('%H:%M %d.%m')} — I'll send \"#{resume_message}\" myself.",
+                session: session)
+    end
+
+    # Don't spam the same unparseable message on every tick.
+    def notify_unparseable(session, spec)
+      key = "#{resume_key(session)}:unparsed"
+      return if @store.get(key) == spec
+
+      @store.put(spec, ttl: 3600, key: key)
+      broadcast("⚠️ #{session.label} looks like it hit a limit, but I couldn't parse the reset time: \"#{spec}\".\n" \
+                "Answer manually whenever you see fit.", session: session)
+    end
+
+    def broadcast(text, session: nil)
+      chats.each do |chat_id|
+        sent = @api.send_message(chat_id: chat_id, text: text)
+        remember_reply(chat_id, sent, session) if session
+      rescue StandardError
+        next
+      end
+    end
+
+    def remember_reply(chat_id, sent, session)
+      id = sent.is_a?(Hash) ? sent["message_id"] : nil
+      return unless id
+
+      @store.put({ "session_id" => session.id, "cwd" => session.cwd, "label" => session.label },
+                 ttl: 30 * 86_400, key: "reply:#{chat_id}:#{id}")
+    end
+
+    def chats = Array(@config.get("telegram.allowed_chat_ids", []))
+
+    # log() catches any write failure itself: an exception raised inside
+    # a rescue isn't caught by that same rescue, and would kill the
+    # thread for good.
+    def log(message)
+      @logger&.puts("[rate-limit-watcher] #{message}")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/agents_control/registry.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # A unified session list assembled from disparate sources.
+  #
+  # There are three sources, and they complement each other:
+  #
+  #   1. terminal backends — iTerm2 tabs and tmux panes;
+  #   2. the process tree — who's actually alive in those tabs;
+  #   3. terminalless agent processes — VS Code sessions, which have no tab.
+  #
+  # Source (1) without (2) lies: a tab's title stays up after the agent
+  # exits. Source (3) without special handling just gets lost — VS Code
+  # sessions aren't a rare edge case, they're often the majority of active
+  # sessions.
+  class Registry
+    def initialize(backends: nil, probe: nil, executor: Executor.new)
+      @executor = executor
+      @backends = backends || default_backends
+      @probe = probe || ProcessProbe.new(executor: executor)
+    end
+
+    # Every session: terminal tabs plus terminalless agents.
+    def sessions
+      @sessions ||= begin
+        probe.refresh
+        enrich(terminal_sessions) + terminalless_sessions
+      end
+    end
+
+    # Only sessions with a confirmed live agent.
+    # This is the list that goes to Telegram by default.
+    def agents = sessions.select(&:agent?)
+
+    def find(id) = sessions.find { |session| session.id == id }
+
+    # The backend that can control this session.
+    def backend_for(session)
+      backends.find { |backend| backend.name == session.backend } || null_backend
+    end
+
+    # Drop the cache — the registry is rebuilt on demand, not held in memory.
+    def refresh
+      @sessions = nil
+      self
+    end
+
+    def available_backends = backends.select(&:available?)
+
+    private
+
+    attr_reader :backends, :probe, :executor
+
+    # The probe is shared: the process tree is read once per registry pass,
+    # not separately by each backend.
+    def default_backends
+      [
+        Terminals::ITerm2.new(executor: executor, probe: probe),
+        Terminals::Tmux.new(executor: executor, probe: probe)
+      ]
+    end
+
+    def null_backend
+      @null_backend ||= Terminals::Null.new(executor: executor)
+    end
+
+    def terminal_sessions
+      available_backends.flat_map do |backend|
+        backend.sessions
+      rescue StandardError
+        # One backend failing must not take down the whole list: without
+        # iTerm2 we can still show tmux panes.
+        []
+      end
+    end
+
+    # The tab title is already available at this point, but it can't be
+    # trusted — only the process tree confirms an agent.
+    def enrich(list)
+      list.map do |session|
+        agent = probe.agent_in(session.tty)
+        foreground = probe.foreground(session.tty)
+
+        session.with(
+          agent: agent&.agent,
+          agent_pid: agent&.pid,
+          foreground_command: foreground&.name
+        )
+      end
+    end
+
+    # A tabless session has neither a title nor a cwd from the terminal,
+    # so the directory comes from the process itself — otherwise the list
+    # would show three nameless rows.
+    def terminalless_sessions
+      found = probe.terminalless_agents
+      return [] if found.empty?
+
+      paths = probe.cwds(found.map(&:pid))
+
+      found.map do |process|
+        Session.new(
+          id: "pid:#{process.pid}",
+          backend: nil,
+          tty: nil,
+          title: nil,
+          cwd: paths[process.pid],
+          agent: process.agent,
+          agent_pid: process.pid,
+          foreground_command: process.name
+        )
+      end
+    end
+  end
+end

data/lib/agents_control/reply.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # A human's answer to an event.
+  #
+  # Also agent-neutral: turning it into the right JSON shape is the
+  # adapter's job. Telegram only ever knows these four kinds.
+  class Reply
+    KINDS = %i[allow deny text none].freeze
+
+    attr_reader :kind, :text, :remember
+
+    def self.allow(remember: false) = new(kind: :allow, remember: remember)
+    def self.deny(text = nil) = new(kind: :deny, text: text)
+    def self.text(value) = new(kind: :text, text: value)
+
+    # Nobody answered. A distinct kind rather than nil: silence is itself
+    # a decision, and it's treated as a refusal — but it's still worth
+    # distinguishing from an explicit "no" in the message shown to the user.
+    def self.none = new(kind: :none)
+
+    def initialize(kind:, text: nil, remember: false)
+      raise ArgumentError, "unknown reply kind: #{kind}" unless KINDS.include?(kind)
+
+      @kind = kind
+      @text = text
+      @remember = remember
+    end
+
+    def allow? = kind == :allow
+    def deny? = kind == :deny
+    def text? = kind == :text
+    def none? = kind == :none
+
+    # Whether to allow the tool. Silence is not permission: if nobody
+    # answered while the owner was out, the action doesn't happen.
+    def permits? = allow?
+
+    def to_h = { kind: kind, text: text, remember: remember }
+  end
+end