agents_control 0.1.0

data/lib/agents_control/hooks/server.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+require "securerandom"
+require "open3"
+
+module AgentsControl
+  module Hooks
+    # Receiver for events from agents.
+    #
+    # HTTP over bare sockets, not webrick: it left the stdlib in Ruby 3,
+    # and pulling in a gem just to accept local POSTs isn't worth it. The
+    # subset of the protocol needed — one request line, headers, a body
+    # — fits in about fifty lines.
+    #
+    # Listens strictly on 127.0.0.1. The port must never be exposed
+    # externally under any circumstances: anyone who could reach it
+    # could grant the agent permission to run commands.
+    #
+    # The handler holds the connection open until a human answers — this
+    # is exactly how a hook blocks the agent. So every connection gets
+    # its own thread, and there can be as many as there are sessions
+    # waiting at once.
+    class Server
+      HOST = "127.0.0.1"
+
+      attr_reader :port, :secret
+
+      def initialize(port: 0, secret: nil, logger: nil)
+        @requested_port = port
+        @secret = secret || SecureRandom.hex(16)
+        @logger = logger
+        @running = false
+      end
+
+      # The port is taken almost always for one reason: another
+      # agents_control is already running. Same situation as a 409 from
+      # Telegram — it won't resolve itself, and a raw backtrace explains nothing here.
+      class PortBusy < AgentsControl::Error; end
+
+      def start(&handler)
+        @server = TCPServer.new(HOST, @requested_port)
+        @port = @server.addr[1]
+        @running = true
+
+        @thread = Thread.new do
+          accept_loop(&handler)
+        end
+
+        self
+      rescue Errno::EADDRINUSE
+        raise PortBusy, "port #{@requested_port} is taken#{occupant_hint}"
+      end
+
+      # "Something's already running somewhere" with no indication of
+      # where is a useless message: finding the process becomes a manual
+      # hunt. Name it right away.
+      def occupant_hint
+        # argv array, not a shell string: the port ultimately comes from
+        # the user's own config, but there's no reason to trust a shell
+        # to parse it correctly either.
+        out, = Open3.capture3("lsof", "-nP", "-iTCP:#{@requested_port.to_i}", "-sTCP:LISTEN", "-t")
+        pids = out.split.map(&:strip)
+        return "" if pids.empty?
+
+        " by process #{pids.join(', ')}. Stop it: agents_control stop"
+      rescue StandardError
+        ""
+      end
+
+      def url = "http://#{HOST}:#{port}"
+
+      def stop
+        @running = false
+        @server&.close
+        @thread&.kill
+      end
+
+      def wait = @thread&.join
+
+      private
+
+      def accept_loop(&handler)
+        while @running
+          begin
+            socket = @server.accept
+          rescue IOError, Errno::EBADF
+            break # the socket was closed by stop
+          end
+
+          Thread.new(socket) { |connection| serve(connection, &handler) }
+        end
+      end
+
+      def serve(socket, &handler)
+        request = read_request(socket)
+        return respond(socket, 400, {}) unless request
+
+        return respond(socket, 403, {}) if from_browser?(request) || !authorized?(request)
+
+        result = handler.call(request[:path], request[:body])
+        respond(socket, 200, result || {})
+      rescue StandardError => e
+        log("handling failed: #{e.class}: #{e.message}")
+        # An empty response means "no decision" — the agent continues as usual.
+        # A failure on our end must not stop it.
+        respond(socket, 200, {})
+      ensure
+        socket.close unless socket.closed?
+      end
+
+      def read_request(socket)
+        request_line = socket.gets
+        return nil if request_line.nil?
+
+        path = request_line.split[1].to_s
+        headers = read_headers(socket)
+        length = headers["content-length"].to_i
+        body = length.positive? ? socket.read(length).to_s : ""
+
+        { path: path, headers: headers, body: parse(body) }
+      end
+
+      def read_headers(socket)
+        headers = {}
+
+        while (line = socket.gets) && line != "\r\n"
+          key, value = line.split(":", 2)
+          headers[key.to_s.strip.downcase] = value.to_s.strip
+        end
+
+        headers
+      end
+
+      def parse(body)
+        body.empty? ? {} : JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # The only thing that could reach the local port from outside the
+      # machine is a page open in a browser: nothing stops it from
+      # sending requests to 127.0.0.1. It doesn't know the secret, but a
+      # cheap extra line of defense is still worth having.
+      #
+      # The browser sets the Origin header itself and a page can't forge
+      # it. No agent ever sends it, so its presence is a reliable sign of
+      # an outsider. Host is checked separately: this rules out DNS
+      # spoofing, where a page addresses a name that resolves to loopback.
+      def from_browser?(request)
+        headers = request[:headers]
+        return true if headers.key?("origin")
+
+        host = headers["host"].to_s.split(":").first
+
+        !["127.0.0.1", "localhost", "", nil].include?(host)
+      end
+
+      # A shared secret filters out stray requests from other local
+      # programs. It's not protection against someone already logged in
+      # as the same user — the only thing defending against that is the
+      # port being local at all.
+      def authorized?(request)
+        return true if @secret.nil?
+
+        provided = request[:headers]["authorization"].to_s.sub(/\ABearer\s+/i, "")
+
+        # Constant-time comparison: the secret's length is already
+        # known, but there's no reason to leak anything through an early
+        # byte mismatch either.
+        secure_compare(provided, @secret)
+      end
+
+      def secure_compare(given, expected)
+        return false unless given.bytesize == expected.bytesize
+
+        given.bytes.zip(expected.bytes).reduce(0) { |diff, (a, b)| diff | (a ^ b) }.zero?
+      end
+
+      def respond(socket, status, payload)
+        body = JSON.generate(payload)
+
+        socket.print(
+          "HTTP/1.1 #{status} #{status == 200 ? 'OK' : 'Error'}\r\n" \
+          "Content-Type: application/json\r\n" \
+          "Content-Length: #{body.bytesize}\r\n" \
+          "Connection: close\r\n\r\n#{body}"
+        )
+      rescue Errno::EPIPE, Errno::ECONNRESET
+        # The agent gave up without waiting. Happens — not our concern.
+      end
+
+      def log(message) = @logger&.puts("[hooks] #{message}")
+    end
+  end
+end

data/lib/agents_control/keyboard.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module AgentsControl
+  # Reading keystrokes from the terminal in raw mode.
+  #
+  # Split out on its own because two things need the keyboard: the input
+  # line with its command palette, and the settings menu. Parsing escape
+  # sequences and multi-byte characters is a place it's easy to get wrong twice.
+  module Keyboard
+    UP = "\e[A"
+    DOWN = "\e[B"
+    RIGHT = "\e[C"
+    LEFT = "\e[D"
+
+    ENTER = ["\r", "\n"].freeze
+    BACKSPACE = ["\x7F", "\b"].freeze
+    CTRL_C = "\x03"
+    CTRL_D = "\x04"
+    CTRL_A = "\x01"
+    CTRL_E = "\x05"
+    CTRL_U = "\x15"
+    TAB = "\t"
+    ESC = "\e"
+
+    private
+
+    # Returns a key as a string: a printable character, a control byte,
+    # or a whole escape sequence. nil means end of input.
+    def read_key
+      byte = @in.getbyte
+      return nil if byte.nil?
+
+      return read_escape if byte == 0x1B
+
+      read_utf8(byte)
+    end
+
+    # A lone Esc and an arrow key start the same way. Told apart by
+    # waiting: a sequence's continuation arrives immediately, a lone Esc arrives alone.
+    #
+    # The end of a sequence is determined by its structure, not by a
+    # pause. Otherwise on fast input — and in tests, where there are no
+    # pauses at all — an arrow key would swallow the next keystrokes, and they'd be lost.
+    def read_escape
+      return ESC unless pending?(0.05)
+
+      second = @in.getbyte
+      return ESC if second.nil?
+
+      sequence = +"#{ESC}#{second.chr}"
+      return sequence unless ["[", "O"].include?(second.chr)
+
+      # A CSI sequence ends on a byte in the 0x40..0x7E range — that's the stop condition.
+      while sequence.length < 12
+        byte = @in.getbyte
+        break if byte.nil?
+
+        sequence << byte.chr
+        break if (0x40..0x7E).cover?(byte)
+      end
+
+      sequence
+    end
+
+    def pending?(timeout)
+      return !@in.wait_readable(timeout).nil? if @in.respond_to?(:wait_readable)
+
+      !IO.select([@in], nil, nil, timeout).nil?
+    rescue TypeError, IOError
+      true
+    end
+
+    # Non-ASCII characters arrive as several bytes — assembled into a
+    # whole character, or the string would come apart into fragments.
+    def read_utf8(first)
+      length = case first
+               when 0x00..0x7F then 1
+               when 0xC0..0xDF then 2
+               when 0xE0..0xEF then 3
+               else 4
+               end
+
+      bytes = [first]
+      (length - 1).times { bytes << @in.getbyte.to_i }
+      bytes.pack("C*").force_encoding(Encoding::UTF_8).scrub
+    end
+  end
+end

data/lib/agents_control/menu.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # A list navigated with arrow keys.
+  #
+  # Needed wherever picking is more natural than typing: settings are
+  # shown with human-readable names, and requiring the internal name
+  # instead would be a trap. See a row, hit Enter, it changes in place.
+  class Menu
+    include Keyboard
+
+    HINT = "↑↓ — select · Enter — toggle · Esc — exit"
+
+    def initialize(input: $stdin, output: $stdout)
+      @in = input
+      @out = output
+    end
+
+    # rows — something callable: the row list is re-read after every
+    # change, or the screen would keep showing the old value.
+    #
+    # The block receives the index of the selected row.
+    def run(title:, rows:)
+      @rows = rows
+      @items = nil
+      @selected = 0
+      @drawn = 0
+
+      @in.raw do
+        loop do
+          draw(title)
+          break unless step(read_key) { |index| yield(index) }
+        end
+      end
+
+      nil
+    ensure
+      finish
+    end
+
+    private
+
+    # Returns false when it's time to close the menu.
+    def step(key)
+      case key
+      # "й" is the same physical key as "q" on a ЙЦУКЕН layout — quits
+      # without forcing a layout switch just to press q.
+      when nil, ESC, CTRL_C, CTRL_D, "q", "й" then return false
+      when UP then move(-1)
+      when DOWN then move(+1)
+      when *ENTER then activate { |index| yield(index) }
+      end
+
+      true
+    end
+
+    def move(delta)
+      return if items.empty?
+
+      @selected = (@selected + delta) % items.size
+    end
+
+    def activate
+      return if items.empty?
+
+      yield(@selected)
+      # Values changed — re-read the list, or the screen would keep showing the old one.
+      @items = nil
+    end
+
+    def items
+      @items ||= Array(@rows.call)
+    end
+
+    def draw(title)
+      rewind
+      lines = [title, ""] + rendered_items + ["", HINT]
+      @out.print(lines.join("\r\n"))
+      @drawn = lines.size - 1
+    end
+
+    def rendered_items
+      items.each_with_index.map do |line, index|
+        index == @selected ? "\e[7m #{line} \e[0m" : " #{line} "
+      end
+    end
+
+    # Rewind to the start of what was drawn and clear it: redrawn in
+    # full, so there's no need to track each line's length separately.
+    def rewind
+      @out.print("\e[#{@drawn}A") if @drawn.positive?
+      @out.print("\r\e[J")
+    end
+
+    def finish
+      rewind
+      @out.flush
+    end
+  end
+end

data/lib/agents_control/pending.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Questions currently waiting for an answer.
+  #
+  # The thread serving the hook parks here until a human presses a
+  # button in Telegram, or time runs out. This wait is exactly what
+  # holds the agent blocked — that's the whole point of it.
+  #
+  # Held only in memory, and that's deliberate. If the daemon crashes,
+  # the HTTP connection to the agent drops too: the agent gets a network
+  # error, treats it as "no decision," and continues on its own. There's
+  # nothing to restore after a restart — nobody's left waiting.
+  class Pending
+    Question = Struct.new(:id, :event, :queue, :asked_at, keyword_init: true)
+
+    def initialize
+      @questions = {}
+      @mutex = Mutex.new
+    end
+
+    # Register a question and wait for an answer.
+    # Returns Reply.none if nobody answered in time.
+    #
+    # The block runs between registration and waiting: the message has
+    # to be sent once the question's identifier is already known, but
+    # before the thread goes to sleep. Otherwise the answer could arrive
+    # before we start waiting for it.
+    def ask(event, timeout:)
+      question = register(event)
+
+      begin
+        yield(question.id) if block_given?
+        question.queue.pop(timeout: timeout) || Reply.none
+      ensure
+        forget(question.id)
+      end
+    end
+
+    def answer(id, reply)
+      question = @mutex.synchronize { @questions[id] }
+      return false unless question
+
+      question.queue.push(reply)
+      true
+    end
+
+    def find(id) = @mutex.synchronize { @questions[id] }
+
+    def all = @mutex.synchronize { @questions.values.dup }
+
+    def size = @mutex.synchronize { @questions.size }
+
+    private
+
+    def register(event)
+      question = Question.new(
+        id: SecureRandom.alphanumeric(8).downcase,
+        event: event,
+        queue: Thread::Queue.new,
+        asked_at: Time.now
+      )
+
+      @mutex.synchronize { @questions[question.id] = question }
+      question
+    end
+
+    def forget(id) = @mutex.synchronize { @questions.delete(id) }
+  end
+end

data/lib/agents_control/process_probe.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Who's actually running in each tab.
+  #
+  # A tab's title can't be trusted: Claude Code sets it via an OSC
+  # sequence, and the title stays up after the process exits.
+  #
+  # One `ps -A` call for the whole process tree instead of a separate
+  # `ps -t` per tab.
+  class ProcessProbe
+    # Processes with no controlling terminal. This is what an agent
+    # session launched from the VS Code extension looks like: it has no
+    # tab at all.
+    NO_TTY = "??"
+
+    # An agent is identified by the basename of its executable: in a
+    # terminal that's `claude`; in VS Code it's a long path into the
+    # extension's directory.
+    AGENT_BINARIES = {
+      "claude" => :claude_code,
+      "codex" => :codex
+    }.freeze
+
+    Process = Struct.new(:tty, :pid, :stat, :command, keyword_init: true) do
+      # `+` in the stat column marks a process in the foreground group —
+      # i.e. what the user is currently interacting with.
+      def foreground? = stat.to_s.include?("+")
+      def name = File.basename(command.to_s)
+      def agent = AGENT_BINARIES[name]
+      def agent? = !agent.nil?
+      def terminal? = tty != NO_TTY
+    end
+
+    def initialize(executor: Executor.new)
+      @executor = executor
+    end
+
+    # Re-reads the process tree. The result is cached on the object — one
+    # probe per registry pass.
+    def refresh
+      result = @executor.run(Which.find!("ps"), "-A", "-o", "tty=,pid=,stat=,comm=")
+      @processes = result.success? ? parse(result.stdout) : []
+      self
+    end
+
+    def processes
+      @processes || refresh.processes
+    end
+
+    # A tab's processes, in launch order.
+    def for_tty(tty)
+      by_tty.fetch(normalize(tty), [])
+    end
+
+    # What's currently in the foreground of a tab. This is what the user sees.
+    def foreground(tty)
+      candidates = for_tty(tty)
+      candidates.reverse.find(&:foreground?) || candidates.last
+    end
+
+    # The live agent in a tab — or nil, whatever the title claims.
+    def agent_in(tty)
+      for_tty(tty).find(&:agent?)
+    end
+
+    # Whether an app with this name is running.
+    #
+    # Deliberately not via pgrep: on macOS `pgrep -x` matches against the
+    # full path rather than the name, and in a restricted environment
+    # pgrep can miss processes that ps sees fine. We already have the
+    # list — this is a filter over existing data, not another call.
+    def running?(name)
+      processes.any? { |process| process.name == name }
+    end
+
+    # Agents with no tab: VS Code sessions and anything else terminalless.
+    def terminalless_agents
+      processes.select { |process| process.agent? && !process.terminal? }
+    end
+
+    # Working directories of processes: { pid => path }.
+    #
+    # For a tabless session this is the only way to give it a human name —
+    # there's no title and no cwd from a terminal. One lsof call for all
+    # pids at once (0.027s), not one call per pid.
+    def cwds(pids)
+      pids = Array(pids).compact.uniq
+      return {} if pids.empty?
+
+      lsof = Which.find("lsof")
+      return {} unless lsof
+
+      result = @executor.run(lsof, "-a", "-d", "cwd", "-p", pids.join(","), "-Fn")
+      # We may lack permission for someone else's processes — that's fine, return what we have.
+      result.success? ? parse_lsof(result.stdout) : {}
+    end
+
+    private
+
+    # -F format: lines with a single-letter prefix. `p` is pid, `n` is
+    # filename. An `n` value belongs to the most recently seen `p`.
+    def parse_lsof(output)
+      current = nil
+
+      output.each_line.with_object({}) do |line, found|
+        line = line.chomp
+        case line[0]
+        when "p" then current = line[1..].to_i
+        when "n" then found[current] = line[1..] if current && !found.key?(current)
+        end
+      end
+    end
+
+    def by_tty
+      @by_tty ||= processes.group_by(&:tty)
+    end
+
+    # macOS prints `ttys017`, but elsewhere the same tty is called
+    # `/dev/ttys017` or `s017` — normalize to one form.
+    def normalize(tty)
+      return NO_TTY if tty.nil? || tty.empty?
+
+      tty.sub(%r{\A/dev/}, "")
+    end
+
+    def parse(output)
+      output.each_line.filter_map do |line|
+        tty, pid, stat, command = line.strip.split(/\s+/, 4)
+        next if command.nil?
+
+        Process.new(tty: normalize(tty), pid: pid.to_i, stat: stat, command: command)
+      end
+    end
+  end
+end