agents_control 0.1.0

data/lib/agents_control/console.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # The interactive console.
+  #
+  # The tool is meant to live in a tab, not run once and exit: that's
+  # its working state — it listens to Telegram and receives agent events
+  # while it's open. Separate subcommands would be misleading here: after
+  # `setup` it would look like everything's running, while in fact
+  # nothing is polling Telegram, and messages pile up unread on its side.
+  #
+  # So running with no arguments opens the console itself, and the
+  # commands inside it are the same as the bot's — with a slash.
+  class Console
+    COMMANDS = {
+      "/help" => "list of commands",
+      "/sessions" => "sessions with a live agent",
+      "/tabs" => "all terminal tabs",
+      "/status" => "what's happening right now",
+      "/away" => "intercept agent questions (before stepping out)",
+      "/settings" => "settings; /settings NAME — toggle",
+      "/token" => "set the Telegram token",
+      "/doctor" => "check that everything is in place",
+      "/hooks" => "hook status; /hooks install|uninstall",
+      "/quit" => "quit"
+    }.freeze
+
+    # Values worth suggesting as a second word.
+    ARGUMENTS = {
+      "/away" => %w[on off],
+      "/hooks" => %w[install uninstall]
+    }.freeze
+
+    def initialize(config: nil, store: nil, secrets: nil, output: $stdout)
+      @config = config || Config.load
+      @store = store || Store.new
+      @secrets = secrets || Secrets.new
+      @out = output
+      @out.sync = true if @out.respond_to?(:sync=)
+    end
+
+    def run
+      banner
+      start_daemon
+      loop_commands
+    ensure
+      say("")
+      say("Stopping…")
+      @daemon&.stop
+    end
+
+    private
+
+    def say(text = "") = @out.puts(text)
+
+    def banner
+      say("agents_control #{VERSION}")
+      say("Type / for the command list, arrows to pick, Enter to fill in.\nQuit with /quit or Ctrl-D.")
+      say("")
+    end
+
+    # The line is passed as an argument rather than read from the editor
+    # internally: this lets completions be tested without a live terminal.
+    def complete(word, line: word)
+      command, rest = line.split(/\s+/, 2)
+
+      rest.nil? ? complete_command(word) : complete_argument(command, word)
+    end
+
+    # The slash is filled in automatically: typing it every time isn't
+    # required, and the list is shown in full either way.
+    def complete_command(word)
+      needle = word.start_with?("/") ? word : "/#{word}"
+
+      COMMANDS.keys.select { |name| name.start_with?(needle) }
+    end
+
+    def complete_argument(command, word)
+      values = case command
+               when "/settings" then setting_names
+               else ARGUMENTS.fetch(command, [])
+               end
+
+      values.select { |value| value.start_with?(word) }
+    end
+
+    # A short setting name for the completion hint.
+    #
+    # Usually the key's last word, but for `anchors.enabled` that
+    # degenerates into a meaningless "enabled" — unclear what's actually
+    # on. For cases like that, the section is used instead: "anchors" speaks for itself.
+    GENERIC = %w[enabled].freeze
+
+    def setting_names
+      (Channels::Telegram::SettingsMenu::TOGGLES +
+       Channels::Telegram::SettingsMenu::CHOICES).map { |item| short_name(item[:key]) }
+    end
+
+    def short_name(key)
+      section, *rest = key.split(".")
+
+      GENERIC.include?(rest.last) ? section : rest.last
+    end
+
+    # The daemon comes up immediately: a console without it is just a
+    # window, and the point is to already be connected the moment the tab opens.
+    def start_daemon
+      @daemon = Daemon.new(config: @config, store: @store, secrets: @secrets, logger: @out)
+
+      return say("") if @daemon.start
+
+      say("")
+      say("The daemon isn't running — the commands below still work.")
+      say("")
+    end
+
+    def loop_commands
+      while (line = prompt)
+        line = line.strip
+        next if line.empty?
+
+        break if %w[/quit /exit /q].include?(line)
+
+        execute(line)
+      end
+    end
+
+    # Without a terminal — a plain gets: control sequences over a pipe
+    # would turn into garbage, and the console stays usable from scripts.
+    def prompt
+      return plain_prompt unless $stdin.tty?
+
+      editor.read(prompt_text)
+    rescue Interrupt
+      # Ctrl-C mid-line clears the line rather than quitting the program:
+      # quitting is /quit, so an accidental keypress doesn't drop the connection.
+      say("^C")
+      ""
+    end
+
+    def editor
+      @editor ||= Prompt.new(
+        output: @out,
+        completer: ->(word) { complete(word, line: word) },
+        describer: ->(name) { COMMANDS[name] }
+      )
+    end
+
+    def plain_prompt
+      @out.print(prompt_text)
+      $stdin.gets
+    end
+
+    # The prompt itself shows the state: after stepping away it's easy
+    # to forget interception is off, and end up with no notifications exactly when they're needed.
+    def prompt_text
+      @config.get("answers.away", false) ? "🚶 > " : "> "
+    end
+
+    def execute(line)
+      command, argument = line.split(/\s+/, 2)
+      command = "/#{command}" unless command.start_with?("/")
+
+      case command
+      # A bare slash means "show me what's here" — typing it and hitting
+      # enter is more natural than remembering the word help.
+      when "/", "//" then help
+      when "/help" then help
+      when "/sessions" then list(registry.refresh.agents, "Agent sessions")
+      when "/tabs" then list(registry.refresh.sessions, "All tabs")
+      when "/status" then status
+      when "/away" then away(argument)
+      when "/settings" then settings(argument)
+      when "/token" then token
+      when "/doctor" then doctor
+      when "/hooks" then hooks(argument)
+      else say("I don't know the command #{command}. Type /help.")
+      end
+    rescue StandardError => e
+      say("Error: #{e.class}: #{e.message}")
+    end
+
+    def help
+      width = COMMANDS.keys.map(&:length).max
+      COMMANDS.each { |name, text| say("  #{name.ljust(width)}  #{text}") }
+    end
+
+    def registry = @registry ||= Registry.new
+
+    def list(sessions, title)
+      return say("#{title}: empty.") if sessions.empty?
+
+      say(title)
+      sessions.each_with_index do |session, index|
+        say(format("%3d. %s %s", index + 1, marker(session), describe(session)))
+      end
+    end
+
+    def marker(session)
+      return "⏳" if session.processing?
+      return "🖥" if session.terminalless?
+      return "▸" if session.at_shell_prompt?
+
+      "·"
+    end
+
+    def describe(session)
+      agent = session.agent ? session.agent.to_s : (session.foreground_command || "—")
+      place = session.terminalless? ? "vscode" : session.tty.to_s.sub(%r{\A/dev/}, "")
+
+      "#{agent} · #{session.label} · #{place}"
+    end
+
+    def status
+      sessions = registry.refresh.sessions
+
+      say("Tabs: #{sessions.size}, with an agent: #{sessions.count(&:agent?)}")
+      say("Backends: #{registry.available_backends.map(&:name).join(', ')}")
+      say("Mode: #{@daemon&.away_label || 'daemon not running'}")
+      say("Waiting for a reply: #{@daemon ? @daemon.pending.size : 0}")
+      say("Chats: #{Array(@config.get('telegram.allowed_chat_ids', [])).join(', ')}")
+    end
+
+    def away(argument)
+      value = case argument.to_s.strip.downcase
+              when "on", "yes" then true
+              when "off", "no" then false
+              else !@config.get("answers.away", false)
+              end
+
+      @config.set("answers.away", value).save
+      say(value ? "🚶 Away. Agent questions go to Telegram and wait for a reply." :
+                  "🪑 Present. Questions stay in the terminal.")
+    end
+
+    def settings(argument)
+      return open_settings if argument.to_s.strip.empty?
+
+      key = resolve_setting(argument.strip)
+      return say("I don't know the setting #{argument}. Type /settings with no argument.") unless key
+
+      say(settings_menu.apply({ "key" => key }))
+    end
+
+    def settings_menu
+      Channels::Telegram::SettingsMenu.new(store: @store, config: @config)
+    end
+
+    # Showing human-readable names but requiring the internal name back
+    # is a trap: you see "Rate-limit anchors," type it, and get
+    # rejected. So the settings list is navigated with arrows, same as the commands.
+    def open_settings
+      return say(settings_menu.text) unless $stdin.tty?
+
+      items = Channels::Telegram::SettingsMenu::TOGGLES +
+              Channels::Telegram::SettingsMenu::CHOICES
+
+      Menu.new(output: @out).run(
+        title: "⚙️ Settings",
+        rows: -> { settings_menu.rows }
+      ) { |index| settings_menu.apply({ "key" => items[index][:key] }) }
+    end
+
+    # Accepts the short name, the full key, and the exact label a human
+    # saw on screen: rejecting the very string that was just shown is
+    # the worst thing a completion hint could do.
+    def resolve_setting(name)
+      needle = name.to_s.strip.downcase
+      items = Channels::Telegram::SettingsMenu::TOGGLES +
+              Channels::Telegram::SettingsMenu::CHOICES
+
+      item = items.find do |entry|
+        key = entry[:key]
+        [key, key.split(".").last, short_name(key), entry[:label]].compact
+          .map { |value| value.downcase } .include?(needle)
+      end
+
+      item && item[:key]
+    end
+
+    def token
+      say("The token isn't displayed and isn't kept in history.")
+      value = ask_secret("Token from @BotFather: ")
+      return say("Empty — nothing changed.") if value.empty?
+
+      @secrets.set(:telegram_token, value)
+      say("Saved to: #{@secrets.target.name}. Restart the console to apply it.")
+    end
+
+    def ask_secret(label)
+      @out.print(label)
+      $stdin.noecho(&:gets).to_s.strip
+    rescue SystemCallError, IOError
+      ""
+    ensure
+      say("")
+    end
+
+    def doctor
+      Doctor.new(config: @config, secrets: @secrets).run.each do |check|
+        say("#{check.icon} #{check.name.ljust(22)} #{check.detail}")
+        say("  └ #{check.fix}") if check.fix
+      end
+    end
+
+    def hooks(argument)
+      agent = Agents::ClaudeCode.new
+
+      case argument.to_s.strip
+      when "install" then say(agent.install!(hook_url, secret: hook_secret) ? "Connected." : "Couldn't connect.")
+      when "uninstall" then say(agent.uninstall! ? "Disconnected." : "Couldn't disconnect.")
+      else say("Hooks are #{agent.installed? ? 'connected' : 'not connected'}.")
+      end
+    end
+
+    def hook_url = "http://127.0.0.1:#{@config.get('hooks.port', Daemon::DEFAULT_PORT)}"
+
+    def hook_secret = @secrets.get(:hook_secret)
+  end
+end

data/lib/agents_control/daemon.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module AgentsControl
+  # Brings everything together: receiving hooks from agents and talking to Telegram.
+  #
+  # One process, because one Telegram token allows exactly one update
+  # reader, and a thread waiting on a question's answer has to get that
+  # answer from the same process that asked it.
+  class Daemon
+    # The port is fixed, not picked freely on every start: the address
+    # is written into an agent's own settings and has to survive a
+    # daemon restart, or every restart would leave hooks firing into nothing.
+    DEFAULT_PORT = 47_653
+
+    def initialize(config: nil, store: nil, secrets: nil, logger: $stdout)
+      @config = config || Config.load
+      @store = store || Store.new
+      @secrets = secrets || Secrets.new
+      @logger = logger
+
+      # Without this, output buffers until the process exits. Under
+      # launchd that means an empty log for a daemon that's actually
+      # running — blind exactly when the log is what you'd reach for.
+      @logger.sync = true if @logger.respond_to?(:sync=)
+    end
+
+    attr_reader :bot
+
+    # Exposed: the console needs to show how many questions are
+    # currently waiting for an answer.
+    def pending = @pending ||= Pending.new
+
+    # Bring everything up and return control immediately.
+    #
+    # Split from waiting for the sake of the interactive console: it
+    # holds its own input loop while the daemon runs alongside. The
+    # `daemon` command is this same start plus waiting.
+    def start
+      return false unless ready?
+
+      start_hooks
+      start_anchors
+      start_screen_watcher
+      start_rate_limit_watcher
+      install_agents
+      verify_hooks
+      publish_commands
+      start_bot
+
+      log("hooks listening on #{server.url}, agents connected: #{installed_agents.size}")
+      log("mode: #{away_label}")
+      true
+    rescue Hooks::Server::PortBusy => e
+      fail_with(e.message)
+    end
+
+    def wait = @bot&.wait
+
+    def stop
+      @bot&.stop
+      server&.stop
+      @scheduler&.stop
+      @screen_watcher&.stop
+      @rate_limit_watcher&.stop
+      remove_agents
+    end
+
+    def run
+      return false unless start
+
+      Signal.trap("INT") { @bot&.stop }
+      Signal.trap("TERM") { @bot&.stop }
+      wait
+    ensure
+      stop
+    end
+
+    def away_label
+      @config.get("answers.away", false) ? "away — questions go to Telegram" : "present — notifications only"
+    end
+
+    def ready?
+      return fail_with("Token not found. Enter /token or run agents_control setup") unless
+        @secrets.get(:telegram_token)
+      return fail_with("The allowed-chats list is empty. Run: agents_control setup") if chats.empty?
+
+      true
+    end
+
+    private
+
+    def chats = Array(@config.get("telegram.allowed_chat_ids", []))
+
+    def port = @config.get("hooks.port", DEFAULT_PORT)
+
+    def agents = @agents ||= [Agents::ClaudeCode.new]
+
+    def installed_agents = agents.select(&:installed?)
+
+    def server
+      @server ||= Hooks::Server.new(port: port, secret: hook_secret, logger: @logger)
+    end
+
+    # The secret doesn't protect against another user on the same
+    # machine — they can already read the settings file — it protects
+    # against outside requests to the local port, including whatever a
+    # page open in a browser might send.
+    def hook_secret
+      @hook_secret ||= @secrets.get(:hook_secret) || begin
+        generated = SecureRandom.hex(16)
+        @secrets.set(:hook_secret, generated)
+        generated
+      end
+    end
+
+    def start_hooks
+      dispatcher = Dispatcher.new(
+        agents: agents,
+        channel: channel,
+        config: @config,
+        pending: pending,
+        logger: @logger
+      )
+
+      server.start do |_path, payload|
+        # Any event means a human was just working with the agent. This
+        # is how the anchor scheduler knows whether a rate-limit window
+        # is open — no separate polling needed.
+        @store.put(Time.now.to_i, ttl: 86_400, key: Anchors::Scheduler::ACTIVITY_KEY)
+
+        dispatcher.handle(payload)
+      end
+    end
+
+    def start_anchors
+      @scheduler = Anchors::Scheduler.new(
+        config: @config, store: @store, logger: @logger
+      ).start
+
+      return unless @config.get("anchors.enabled", false)
+
+      log("anchors enabled, next one at #{@scheduler.next_run_at&.strftime('%d.%m %H:%M') || 'never'}")
+    end
+
+    def channel
+      @channel ||= Channels::Telegram::Channel.new(api: api, store: @store, config: @config,
+                                                    registry: Registry.new)
+    end
+
+    def start_screen_watcher
+      @screen_watcher = ScreenWatcher.new(
+        registry: Registry.new, config: @config, store: @store, api: api, logger: @logger
+      ).start
+    end
+
+    # Goes through the full Registry, like ScreenWatcher, but polls
+    # noticeably less often (once a minute, not every 20 seconds) — a
+    # limit doesn't hit every few seconds, and an AppleScript scan
+    # (~0.9s) at that frequency costs less this way.
+    def start_rate_limit_watcher
+      @rate_limit_watcher = RateLimitWatcher.new(
+        registry: Registry.new, config: @config, store: @store, api: api,
+        interval: @config.get("terminal.rate_limit_poll_interval", 60), logger: @logger
+      ).start
+    end
+
+    def api = @api ||= Channels::Telegram::Api.new(@secrets.get(:telegram_token))
+
+    def install_agents
+      @installed = true
+
+      agents.each do |agent|
+        # Headroom over the reply timeout: the hook has to outlive our
+        # own timeout, not get cut off a second before it.
+        agent.install!(server.url, secret: hook_secret,
+                                   timeout: @config.get("answers.reply_timeout", 600) + 60)
+      rescue StandardError => e
+        log("couldn't connect #{agent.key}: #{e.message}")
+      end
+    end
+
+    # Self-check: does an event from the agent actually reach us. The
+    # entry in settings.json and the live server can drift apart — for
+    # instance, if another agents_control is already running nearby with
+    # a different secret.
+    def verify_hooks
+      settings = JSON.parse(File.read(Agents::ClaudeCode.settings_path))
+      hook = settings.dig("hooks", "Stop", 0, "hooks", 0)
+      return log("couldn't find our own hooks in settings — events won't arrive") unless hook
+
+      code = probe_hook(hook)
+      return if code == 200
+
+      log("WARNING: the hook returned #{code}, agent events won't reach me.")
+      log("This usually means another agents_control is running nearby — stop it.")
+    rescue StandardError => e
+      log("couldn't verify hooks: #{e.message}")
+    end
+
+    def probe_hook(hook)
+      uri = URI(hook["url"])
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      hook.fetch("headers", {}).each { |key, value| request[key] = value }
+      request.body = JSON.generate({ "hook_event_name" => "Ping" })
+
+      Net::HTTP.start(uri.host, uri.port, read_timeout: 5) { |http| http.request(request) }.code.to_i
+    end
+
+    def publish_commands
+      api.set_my_commands(Channels::Telegram::Router::COMMANDS)
+    rescue Channels::Telegram::Api::Error => e
+      log("couldn't update the command menu: #{e.message}")
+    end
+
+    # Hooks are removed on stop: otherwise the agent prints ECONNREFUSED
+    # for every hook it has nowhere to reach. If the daemon crashes they
+    # stay dangling; fixed with the hooks uninstall command.
+    def remove_agents
+      return unless @installed
+
+      agents.each do |agent|
+        agent.uninstall!
+      rescue StandardError => e
+        log("couldn't disconnect #{agent.key}: #{e.message}")
+      end
+
+      log("hooks disconnected")
+    end
+
+    def start_bot
+      router = Channels::Telegram::Router.new(
+        api: api, registry: Registry.new, store: @store,
+        config: @config, pending: pending
+      )
+
+      @bot = Channels::Telegram::Bot.new(api: api, router: router, store: @store,
+                                         config: @config, logger: @logger).start
+    end
+
+    def fail_with(message)
+      log(message)
+      false
+    end
+
+    def log(message) = @logger.puts("[#{Time.now.strftime('%H:%M:%S')}] #{message}")
+  end
+end