agents_control 0.1.0

data/lib/agents_control/screen_watcher.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module AgentsControl
+  # Notices Claude Code's local menus on a session's screen.
+  #
+  # Dialogs the CLI shows itself in response to a local human command —
+  # switching models via /model, folder trust on first launch — never
+  # produce a hook event at all. The only way to see this state is to
+  # read the screen itself.
+  #
+  # Goes through the full Registry — sees bare iTerm2 tabs too, not just
+  # tmux panes, same as RateLimitWatcher.
+  #
+  # The heuristic is narrow: consecutive lines "❯ 1. …" and "  2. …" —
+  # this is how Claude Code draws any choice (folder trust, model switch,
+  # a tool permission if it ever made it to the screen), and almost
+  # nothing else draws like this.
+  class ScreenWatcher
+    # "1." next to the cursor marks the first option — the start of a menu.
+    CURSOR_OPTION = /^\s*❯\s*1\.\s+(.+?)\s*$/
+
+    # Later options come without the cursor, just numbered.
+    OPTION = /^\s*(\d+)\.\s+(.+?)\s*$/
+
+    # A 30-line screen comfortably covers any CLI dialog worth catching —
+    # Claude Code doesn't draw menus that long.
+    LINES = 30
+
+    def initialize(registry:, config:, store:, api:, logger: nil)
+      @registry = registry
+      @config = config
+      @store = store
+      @api = api
+      @logger = logger
+      @running = false
+    end
+
+    def start
+      return self unless enabled?
+
+      @running = true
+      @thread = Thread.new do
+        tick while @running
+      ensure
+        nil
+      end
+
+      self
+    end
+
+    def stop
+      @running = false
+      @thread&.kill
+    end
+
+    # One pass over all agent sessions. Public method — tests call it
+    # directly, without spinning up a real background thread.
+    def tick
+      candidates.each { |session| check(session) }
+    rescue StandardError => e
+      log("failure: #{e.class}: #{e.message}")
+    ensure
+      sleep(interval) if @running
+    end
+
+    private
+
+    def enabled? = @config.get("terminal.watch_menus", true)
+
+    def interval = @config.get("terminal.menu_poll_interval", 20)
+
+    def candidates
+      @registry.refresh.agents.reject(&:terminalless?)
+    rescue StandardError
+      []
+    end
+
+    def check(session)
+      options = parse_menu(@registry.backend_for(session).capture(session.id, lines: LINES))
+      key = menu_key(session)
+
+      return @store.delete(key) if options.empty?
+
+      digest = Digest::SHA1.hexdigest(options.join("\n"))
+      return if @store.get(key) == digest # the same dialog — already notified
+
+      @store.put(digest, ttl: 3600, key: key)
+      notify(session, options)
+    end
+
+    def menu_key(session) = "menu:#{session.id}"
+
+    # Looks for the last textual occurrence of "❯ 1. …" — the one
+    # closest to the screen's current state, not a random numbered list
+    # left over somewhere higher in the scrollback.
+    def parse_menu(text)
+      lines = text.to_s.each_line.map(&:chomp)
+      start = lines.rindex { |line| line.match?(CURSOR_OPTION) }
+      return [] unless start
+
+      options = [lines[start][CURSOR_OPTION, 1]]
+      index = start + 1
+
+      while index < lines.size && (m = lines[index].match(OPTION)) && m[1].to_i == options.size + 1
+        options << m[2]
+        index += 1
+      end
+
+      options.size >= 2 ? options : []
+    end
+
+    def notify(session, options)
+      text = "🖥 #{session.label} is waiting for a choice in the terminal:\n\n" +
+             options.each_with_index.map { |option, i| "#{i + 1}. #{option}" }.join("\n")
+
+      chats.each do |chat_id|
+        sent = @api.send_message(chat_id: chat_id, text: text, reply_markup: buttons(session, options))
+        remember_reply(chat_id, sent, session)
+      rescue StandardError
+        # One unreachable chat must not affect the rest.
+        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 buttons(session, options)
+      rows = options.each_with_index.map do |option, i|
+        [{
+          text: "#{i + 1}. #{option}"[0, 60],
+          callback_data: @store.put({ "action" => "menu_choice", "session_id" => session.id,
+                                      "choice" => i + 1 }, ttl: 3600)
+        }]
+      end
+
+      { inline_keyboard: rows }
+    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("[screen-watcher] #{message}")
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/agents_control/secrets.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module AgentsControl
+  # Storing tokens outside the repo and outside the config.
+  #
+  # Providers are tried in order; the first available one that answers
+  # wins. Implemented by shelling out to system binaries rather than gems:
+  # gems like keyring pull in C extensions and break installation for
+  # some users, while `security` and `secret-tool` are always present on
+  # their respective platforms.
+  #
+  # The rule that shaped the implementation: **the secret must never land
+  # in argv**. Anything passed as an argument is visible in `ps` to any
+  # process the user owns, and it lands in shell history. That's why
+  # writing to the Keychain goes through `security -i` with the command
+  # on stdin, and the CLI never accepts the token as a flag.
+  class Secrets
+    SERVICE = "agents_control"
+
+    def initialize(executor: Executor.new, providers: nil)
+      @executor = executor
+      @providers = providers || default_providers
+    end
+
+    def get(key)
+      readable.each do |provider|
+        value = provider.get(key.to_s)
+        return value if value && !value.empty?
+      end
+
+      nil
+    end
+
+    def set(key, value)
+      provider = writable.first
+      raise Error, "no secret storage available" unless provider
+
+      provider.set(key.to_s, value)
+      provider
+    end
+
+    def delete(key)
+      writable.each { |provider| provider.delete(key.to_s) }
+    end
+
+    # Where a secret lives, and where it will be written — for doctor.
+    def source_for(key)
+      readable.find { |provider| provider.get(key.to_s) }
+    end
+
+    def target = writable.first
+
+    private
+
+    def readable = @providers.select(&:available?)
+
+    def writable = readable.select(&:writable?)
+
+    def default_providers
+      [
+        Providers::Env.new,
+        Providers::Keychain.new(executor: @executor),
+        Providers::SecretTool.new(executor: @executor),
+        Providers::File.new
+      ]
+    end
+
+    module Providers
+      # Environment variables. Read-only — writing into someone else's
+      # process isn't possible. Needed for CI, containers, and headless
+      # machines with no keyring daemon.
+      class Env
+        def name = "environment variable"
+        def available? = true
+        def writable? = false
+
+        def get(key) = ENV.fetch(variable_for(key), nil)
+
+        def set(_key, _value) = raise(Error, "cannot write an environment variable")
+
+        def delete(_key) = nil
+
+        def variable_for(key) = "AGENTS_CONTROL_#{key.upcase}"
+      end
+
+      # macOS Keychain.
+      class Keychain
+        def initialize(executor: Executor.new)
+          @executor = executor
+        end
+
+        def name = "Keychain (macOS)"
+
+        def available? = !binary.nil?
+
+        def writable? = true
+
+        def get(key)
+          result = @executor.run(binary, "find-generic-password", "-s", SERVICE, "-a", key, "-w")
+          return nil unless result.success?
+
+          decode(result.stdout.strip)
+        end
+
+        # The command goes over stdin in interactive mode, not argv:
+        # `security add-generic-password -w SECRET` would expose the
+        # token in `ps`, and the man page calls passing a password as an
+        # argument insecure outright.
+        #
+        # The cost of this is that interactive mode splits the line on
+        # whitespace, so a value containing a space or newline would be
+        # silently mangled. Better to refuse loudly than to save a
+        # truncated token and chase a confusing auth error later.
+        def set(key, value)
+          unless value.to_s.match?(/\A[\x21-\x7E]+\z/)
+            raise Error, "Keychain only accepts printable ASCII with no whitespace"
+          end
+
+          command = "add-generic-password -s #{SERVICE} -a #{key} -w #{value} -U\n"
+
+          @executor.run(binary, "-i", stdin: command).success?
+        end
+
+        def delete(key)
+          @executor.run(binary, "delete-generic-password", "-s", SERVICE, "-a", key).success?
+        end
+
+        private
+
+        # `security -w` prints the value as-is while it's ASCII, but
+        # switches to hex the moment other bytes show up inside it.
+        # Telegram tokens are always ASCII, but the store is shared —
+        # decode that case too, carefully: only when the result actually
+        # looks like packed text, not like a secret made of pure hex digits.
+        def decode(value)
+          return value unless value.match?(/\A(?:\h\h)+\z/) && value.length.even?
+
+          bytes = [value].pack("H*").force_encoding(Encoding::UTF_8)
+          bytes.valid_encoding? && !bytes.ascii_only? ? bytes : value
+        end
+
+        def binary
+          @binary = Which.find("security") || false if @binary.nil?
+          @binary || nil
+        end
+      end
+
+      # Linux: libsecret on top of gnome-keyring or KWallet.
+      class SecretTool
+        def initialize(executor: Executor.new)
+          @executor = executor
+        end
+
+        def name = "libsecret (Linux)"
+
+        def available? = !binary.nil?
+
+        def writable? = true
+
+        def get(key)
+          result = @executor.run(binary, "lookup", "service", SERVICE, "account", key)
+          result.success? ? result.stdout.chomp : nil
+        end
+
+        # secret-tool reads the secret from stdin on its own — argv stays clean.
+        def set(key, value)
+          result = @executor.run(
+            binary, "store", "--label=#{SERVICE} #{key}",
+            "service", SERVICE, "account", key,
+            stdin: value
+          )
+          result.success?
+        end
+
+        def delete(key)
+          @executor.run(binary, "clear", "service", SERVICE, "account", key).success?
+        end
+
+        private
+
+        def binary
+          @binary = Which.find("secret-tool") || false if @binary.nil?
+          @binary || nil
+        end
+      end
+
+      # Last resort: a file with 0600 permissions.
+      #
+      # Needed where there's no keyring daemon at all — a headless server
+      # or a container. Worse than the other options, so we warn about it.
+      class File
+        def self.path
+          base = ENV["XDG_STATE_HOME"] || ::File.expand_path("~/.local/state")
+          ::File.join(base, "agents_control", "credentials.json")
+        end
+
+        def initialize(path: self.class.path)
+          @path = path
+        end
+
+        def name = "file #{@path} (0600)"
+
+        def available? = true
+
+        def writable? = true
+
+        def insecure? = true
+
+        def get(key) = read[key]
+
+        def set(key, value)
+          data = read.merge(key => value)
+          FileUtils.mkdir_p(::File.dirname(@path))
+
+          # Permissions are set before writing: otherwise there's a window
+          # between file creation and chmod where the secret is
+          # world-readable.
+          ::File.open(@path, ::File::WRONLY | ::File::CREAT | ::File::TRUNC, 0o600) do |file|
+            file.write(JSON.generate(data))
+          end
+
+          true
+        end
+
+        def delete(key)
+          data = read
+          return false unless data.key?(key)
+
+          set_all(data.except(key))
+        end
+
+        private
+
+        def read
+          return {} unless ::File.exist?(@path)
+
+          parsed = JSON.parse(::File.read(@path))
+          parsed.is_a?(Hash) ? parsed : {}
+        rescue JSON::ParserError
+          {}
+        end
+
+        def set_all(data)
+          ::File.open(@path, ::File::WRONLY | ::File::CREAT | ::File::TRUNC, 0o600) do |file|
+            file.write(JSON.generate(data))
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/agents_control/service.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rbconfig"
+
+module AgentsControl
+  # Autostarting the daemon: launchd on macOS, systemd on Linux.
+  #
+  # Everything here is built around one rule: **absolute paths**. The
+  # service starts not from an interactive shell but from a system
+  # manager, where PATH is completely different and can't be relied on.
+  class Service
+    LABEL = "com.agents-control.daemon"
+
+    def self.for_platform(**args)
+      RUBY_PLATFORM.include?("darwin") ? Launchd.new(**args) : Systemd.new(**args)
+    end
+
+    # The interpreter isn't looked up on PATH, it's the one running this
+    # code right now: a PATH search could find a version manager's
+    # broken shim ahead of the working Ruby. RbConfig.ruby by definition
+    # points at the live interpreter.
+    def initialize(ruby: nil, script: nil, logger: $stdout)
+      @ruby = ruby || RbConfig.ruby
+      @script = script || default_script
+      @logger = logger
+    end
+
+    attr_reader :ruby, :script
+
+    def log_path = File.expand_path("~/Library/Logs/agents_control.log")
+
+    private
+
+    # Path to the tool's own executable. The gem might not be installed
+    # globally — in that case this is the file straight from the repo.
+    def default_script
+      File.expand_path("../../exe/agents_control", __dir__)
+    end
+
+    def write(path, contents)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, contents)
+      path
+    end
+
+    def log(message) = @logger.puts(message)
+
+    # macOS.
+    class Launchd < Service
+      def path = File.expand_path("~/Library/LaunchAgents/#{LABEL}.plist")
+
+      def install
+        write(path, plist)
+        reload
+        path
+      end
+
+      def uninstall
+        system("launchctl", "unload", path, out: File::NULL, err: File::NULL) if File.exist?(path)
+        FileUtils.rm_f(path)
+      end
+
+      def installed? = File.exist?(path)
+
+      private
+
+      def reload
+        system("launchctl", "unload", path, out: File::NULL, err: File::NULL)
+        system("launchctl", "load", path, out: File::NULL, err: File::NULL)
+      end
+
+      def plist
+        <<~XML
+          <?xml version="1.0" encoding="UTF-8"?>
+          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+          <plist version="1.0">
+          <dict>
+            <key>Label</key>
+            <string>#{LABEL}</string>
+
+            <!-- Absolute paths are mandatory: launchd's PATH isn't yours. -->
+            <key>ProgramArguments</key>
+            <array>
+              <string>#{ruby}</string>
+              <string>#{script}</string>
+              <string>daemon</string>
+            </array>
+
+            <key>RunAtLoad</key>
+            <true/>
+
+            <!-- The daemon crashes, launchd brings it back up. Pending
+                 questions are lost in the process, but nobody's left
+                 waiting on them anyway: the connection to the agent
+                 dropped along with the process, and the agent moved on by itself. -->
+            <key>KeepAlive</key>
+            <true/>
+
+            <key>StandardOutPath</key>
+            <string>#{log_path}</string>
+            <key>StandardErrorPath</key>
+            <string>#{log_path}</string>
+
+            <key>EnvironmentVariables</key>
+            <dict>
+              <key>PATH</key>
+              <string>#{safe_path}</string>
+            </dict>
+          </dict>
+          </plist>
+        XML
+      end
+
+      # The same order as in binary lookup: version managers and ARM
+      # brew ahead of the system directories.
+      def safe_path
+        ["#{Dir.home}/.asdf/shims", "/opt/homebrew/bin", "/opt/homebrew/sbin",
+         "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(":")
+      end
+    end
+
+    # Linux.
+    class Systemd < Service
+      def path = File.expand_path("~/.config/systemd/user/agents-control.service")
+
+      def log_path = "journal"
+
+      def install
+        write(path, unit)
+        system("systemctl", "--user", "daemon-reload", out: File::NULL, err: File::NULL)
+        system("systemctl", "--user", "enable", "--now", "agents-control",
+               out: File::NULL, err: File::NULL)
+        path
+      end
+
+      def uninstall
+        system("systemctl", "--user", "disable", "--now", "agents-control",
+               out: File::NULL, err: File::NULL)
+        FileUtils.rm_f(path)
+      end
+
+      def installed? = File.exist?(path)
+
+      private
+
+      def unit
+        <<~UNIT
+          [Unit]
+          Description=agents_control — control AI agents from Telegram
+          After=network-online.target
+
+          [Service]
+          Type=simple
+          ExecStart=#{ruby} #{script} daemon
+          Restart=always
+          RestartSec=5
+
+          [Install]
+          WantedBy=default.target
+        UNIT
+      end
+    end
+  end
+end

data/lib/agents_control/session.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # One session — a terminal tab, or an agent with no terminal at all.
+  #
+  # Deliberately knows nothing about Claude or iTerm2: this is the common
+  # denominator the core and Telegram operate on. Anything backend-specific
+  # lives in the adapters.
+  class Session
+    attr_reader :id, :backend, :tty, :title, :cwd, :agent, :agent_pid, :foreground_command
+
+    def initialize(id:, backend: nil, tty: nil, title: nil, cwd: nil,
+                   processing: nil, at_shell_prompt: nil,
+                   agent: nil, agent_pid: nil, foreground_command: nil)
+      @id = id
+      @backend = backend
+      @tty = tty
+      @title = title
+      @cwd = cwd
+      @processing = processing
+      @at_shell_prompt = at_shell_prompt
+      @agent = agent
+      @agent_pid = agent_pid
+      @foreground_command = foreground_command
+    end
+
+    # Terminal is busy working. iTerm2 has `is processing`; tmux has no
+    # direct equivalent, so the value can be nil — "unknown", not "no".
+    def processing? = @processing == true
+
+    def at_shell_prompt? = @at_shell_prompt == true
+
+    # Agent presence is confirmed by the process tree, not the tab title.
+    def agent? = !@agent.nil?
+
+    # A session without a tab: launched from VS Code or another GUI
+    # client. Can't be controlled through a terminal, only reached via hooks.
+    def terminalless? = @backend.nil? || @tty.nil?
+
+    # Short name for the Telegram list: the directory name is more
+    # informative than a full path or a title that may be stale.
+    def label
+      return File.basename(cwd) if cwd && !cwd.empty?
+      return title if title && !title.empty?
+
+      id.to_s
+    end
+
+    def with(**attrs)
+      Session.new(**to_h.merge(attrs))
+    end
+
+    def to_h
+      {
+        id: id, backend: backend, tty: tty, title: title, cwd: cwd,
+        processing: @processing, at_shell_prompt: @at_shell_prompt,
+        agent: agent, agent_pid: agent_pid, foreground_command: foreground_command
+      }
+    end
+
+    def ==(other) = other.is_a?(Session) && other.to_h == to_h
+    alias eql? ==
+
+    def hash = to_h.hash
+  end
+end