agents_control 0.1.0

data/lib/agents_control/store.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+
+module AgentsControl
+  # State that survives a daemon restart.
+  #
+  # Needed for two reasons at once:
+  #
+  #   1. Telegram limits button `callback_data` to 64 bytes. A session
+  #      identifier won't fit there, let alone an action's text — a button
+  #      carries only a short key, and the action itself lives here.
+  #   2. While the owner is out, the daemon can crash and come back up.
+  #      Pending questions have to survive that, or the agent is left
+  #      waiting forever.
+  #
+  # There are dozens of records here, not millions, and only one process
+  # writes them — so an atomically-replaced file and a mutex, not a database.
+  class Store
+    DEFAULT_TTL = 3600
+
+    def self.path
+      base = ENV["XDG_STATE_HOME"] || File.expand_path("~/.local/state")
+      File.join(base, "agents_control", "store.json")
+    end
+
+    attr_reader :path
+
+    def initialize(path: self.class.path, clock: -> { Time.now.to_i })
+      @path = path
+      @clock = clock
+      @mutex = Mutex.new
+    end
+
+    # Short random key for a button. Eight base36 characters is ~41 bits,
+    # which is plenty: keys live minutes and are checked one at a time.
+    def put(value, ttl: DEFAULT_TTL, key: nil)
+      key ||= SecureRandom.alphanumeric(8).downcase
+
+      write do |data|
+        data[key] = { "value" => value, "expires_at" => now + ttl }
+      end
+
+      key
+    end
+
+    def get(key)
+      entry = read[key]
+      return nil if entry.nil? || expired?(entry)
+
+      entry["value"]
+    end
+
+    # Take the value and delete it in the same step.
+    #
+    # This is exactly how a button press is handled: Telegram redelivers
+    # the callback if the connection drops, and a finger can tap twice.
+    # The first call gets the value, every call after gets nil, and the
+    # action never runs a second time. The check and the delete happen
+    # under one mutex, or two simultaneous presses could both see the value.
+    # The value has to come back as the block's result, not via `return`:
+    # an early return would unwind past the file write, the delete would
+    # never reach disk, and the button would fire again after a restart.
+    def take(key)
+      write do |data|
+        entry = data.delete(key)
+
+        entry.nil? || expired?(entry) ? nil : entry["value"]
+      end
+    end
+
+    def delete(key)
+      write { |data| data.delete(key) }
+    end
+
+    # All live records — for recovering state after a restart.
+    def all
+      read.reject { |_key, entry| expired?(entry) }
+           .transform_values { |entry| entry["value"] }
+    end
+
+    def prune
+      write { |data| data.reject! { |_key, entry| expired?(entry) } }
+    end
+
+    private
+
+    def now = @clock.call
+
+    def expired?(entry) = entry["expires_at"].to_i <= now
+
+    def read
+      @mutex.owned? ? load_file : @mutex.synchronize { load_file }
+    end
+
+    def write
+      @mutex.synchronize do
+        data = load_file
+        result = yield(data)
+        save_file(data)
+        result
+      end
+    end
+
+    def load_file
+      return {} unless File.exist?(path)
+
+      parsed = JSON.parse(File.read(path))
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError, Errno::ENOENT
+      # A corrupt file must not keep the daemon from starting. Losing
+      # pending questions is unfortunate, but failing to start at all is
+      # worse — the agent would be left blocked with no way to answer.
+      {}
+    end
+
+    # Replace via rename: a process reading the file at that moment sees
+    # either the whole old version or the whole new one, never half of either.
+    def save_file(data)
+      FileUtils.mkdir_p(File.dirname(path))
+      temporary = "#{path}.#{Process.pid}.tmp"
+
+      File.write(temporary, JSON.generate(data))
+      File.chmod(0o600, temporary)
+      File.rename(temporary, path)
+    ensure
+      FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
+    end
+  end
+end

data/lib/agents_control/terminals/base.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Terminals
+    # An operation this backend doesn't have. For example, a tabless
+    # session has nothing to create or read from the screen.
+    class Unsupported < StandardError; end
+
+    # The terminal backend contract.
+    #
+    # There are three implementations right now (iTerm2, tmux, null), and
+    # they're chosen not globally but per session: the same machine can
+    # hold bare iTerm2 tabs, tmux panes, and VS Code sessions with no
+    # terminal at all, all at once.
+    #
+    # Every method must be safe when the backend is unavailable: return an
+    # empty result or false, never raise out to the caller or hang it.
+    class Base
+      def initialize(executor: Executor.new, probe: nil)
+        @executor = executor
+        @probe = probe
+      end
+
+      # The backend's symbolic name — ends up in Session#backend.
+      def name = raise(NotImplementedError)
+
+      # Whether the backend can answer right now.
+      # Must have no side effects: in particular, must not launch an app
+      # the user hasn't already opened.
+      def available? = raise(NotImplementedError)
+
+      # [Session] — all of this backend's tabs/panes.
+      def sessions = raise(NotImplementedError)
+
+      def create_tab(cwd: nil, command: nil) = raise(Unsupported, "#{name}: creating a tab is not supported")
+
+      def send_text(_id, _text, newline: true) = raise(Unsupported, "#{name}: sending input is not supported")
+
+      def capture(_id, lines: 200) = raise(Unsupported, "#{name}: reading the screen is not supported")
+
+      def focus(_id) = raise(Unsupported, "#{name}: focusing is not supported")
+
+      def close(_id) = raise(Unsupported, "#{name}: closing is not supported")
+
+      private
+
+      attr_reader :executor
+
+      # The registry hands over its own probe, so the process tree is
+      # read once per pass instead of separately by each backend.
+      def probe
+        @probe ||= ProcessProbe.new(executor: executor)
+      end
+
+      # Field and record separators.
+      #
+      # Plain `|` or a tab won't do: a tab title holds arbitrary text
+      # that the user or the agent writes however they like — anything
+      # can show up there, including newlines. The US and RS control
+      # characters never appear in that text.
+      FIELD = "\x1F"
+      RECORD = "\x1E"
+
+      def parse_records(output, fields)
+        output.split(RECORD).filter_map do |record|
+          next if record.strip.empty?
+
+          values = record.split(FIELD, -1)
+          next if values.size < fields.size
+
+          fields.zip(values).to_h
+        end
+      end
+    end
+  end
+end

data/lib/agents_control/terminals/iterm2.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Terminals
+    # iTerm2 via AppleScript.
+    #
+    # Scripts are passed to osascript over stdin, and parameters via
+    # `on run argv`. Values are never interpolated into the script text:
+    # identifiers, and especially arbitrary user commands, would
+    # otherwise turn into an AppleScript injection.
+    #
+    # A full scan of sessions via AppleScript is expensive, so the list
+    # is built on demand rather than polled on a timer. Agent state
+    # comes from hooks, not from here.
+    class ITerm2 < Base
+      # The session identifier matches the ITERM_SESSION_ID variable that
+      # iTerm2 puts in a tab's environment. A hook uses it to tie an
+      # agent session to a specific tab.
+      LIST = <<~APPLESCRIPT
+        on run argv
+          set fs to (character id 31)
+          set rs to (character id 30)
+          set out to ""
+          tell application "iTerm2"
+            repeat with w in windows
+              repeat with t in tabs of w
+                repeat with s in sessions of t
+                  set out to out & (id of s) & fs & (tty of s) & fs ¬
+                    & ((is processing of s) as text) & fs ¬
+                    & ((is at shell prompt of s) as text) & fs ¬
+                    & (variable s named "path") & fs ¬
+                    & (name of s) & rs
+                end repeat
+              end repeat
+            end repeat
+          end tell
+          return out
+        end run
+      APPLESCRIPT
+
+      # Shared wrapper: find a session by id and do something with it.
+      # %s is substituted right here in the code, never from user input.
+      FIND_AND = <<~APPLESCRIPT
+        on run argv
+          set target_id to item 1 of argv
+          tell application "iTerm2"
+            repeat with w in windows
+              repeat with t in tabs of w
+                repeat with s in sessions of t
+                  if (id of s) is target_id then
+                    %s
+                    return "ok"
+                  end if
+                end repeat
+              end repeat
+            end repeat
+          end tell
+          return "missing"
+        end run
+      APPLESCRIPT
+
+      CREATE_TAB = <<~APPLESCRIPT
+        on run argv
+          set target_dir to item 1 of argv
+          set target_cmd to item 2 of argv
+          tell application "iTerm2"
+            if (count of windows) is 0 then
+              set w to (create window with default profile)
+            else
+              set w to current window
+              tell w to create tab with default profile
+            end if
+            set s to current session of current tab of w
+            if target_dir is not "" then
+              tell s to write text ("cd " & quoted form of target_dir)
+            end if
+            if target_cmd is not "" then
+              tell s to write text target_cmd
+            end if
+            return (id of s)
+          end tell
+        end run
+      APPLESCRIPT
+
+      FIELDS = %i[id tty processing at_shell_prompt cwd title].freeze
+
+      def name = :iterm2
+
+      # Checked against the process tree, not via AppleScript: talking to
+      # the app over AppleScript launches it if it's closed, and an
+      # availability check has no business opening a terminal on the user.
+      #
+      # pgrep won't do here: on macOS `-x` matches against the full path,
+      # and in a restricted environment it misses processes that ps sees fine.
+      def available? = probe.running?("iTerm2")
+
+      def sessions
+        result = osascript(LIST)
+        return [] unless result.success?
+
+        parse_records(result.stdout, FIELDS).map do |record|
+          Session.new(
+            id: record[:id],
+            backend: name,
+            tty: record[:tty],
+            title: record[:title].to_s.strip,
+            cwd: record[:cwd].to_s.strip,
+            processing: record[:processing] == "true",
+            at_shell_prompt: record[:at_shell_prompt] == "true"
+          )
+        end
+      end
+
+      def create_tab(cwd: nil, command: nil)
+        result = osascript(CREATE_TAB, cwd.to_s, command.to_s)
+        result.success? ? result.stdout.strip : nil
+      end
+
+      def send_text(id, text, newline: true)
+        # The text goes in as argv's second argument, not into the script body.
+        script = format(FIND_AND, %(tell s to write text (item 2 of argv) newline #{newline}))
+        act(script, id, text)
+      end
+
+      def capture(id, lines: 200)
+        script = format(FIND_AND, "return contents of s")
+        result = osascript(script, id)
+        return "" unless result.success?
+
+        # AppleScript only hands back the visible area — there's no
+        # scrollback here; for history, go to tmux or the agent's transcript.
+        #
+        # `contents of s` is the whole visible screen, including blank
+        # filler lines below the text when it doesn't reach the bottom of
+        # the pane. rstrip removes that tail before the .last(lines) cut —
+        # otherwise, on a pane taller than its content, the cut would
+        # grab only blank lines.
+        text = result.stdout.rstrip
+        text.empty? ? "" : text.lines.last(lines).join.rstrip
+      end
+
+      def focus(id)
+        act(format(FIND_AND, "tell t to select\n                    tell w to select"), id)
+      end
+
+      def close(id)
+        act(format(FIND_AND, "tell s to close"), id)
+      end
+
+      private
+
+      def act(script, *args)
+        result = osascript(script, *args)
+        result.success? && !result.stdout.include?("missing")
+      end
+
+      def osascript(script, *args)
+        binary = Which.find("osascript")
+        return Executor::Result.new(stdout: "", stderr: "osascript not found", status: 127) unless binary
+
+        # Scanning fifteen sessions takes ~0.9s; give it headroom for a
+        # slow AppleEvent, but not forever — iTerm2 itself can hang.
+        executor.run(binary, "-", *args, stdin: script, timeout: 20)
+      end
+    end
+  end
+end

data/lib/agents_control/terminals/null.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Terminals
+    # Backend for sessions that have no terminal at all.
+    #
+    # This isn't a stub for an exotic edge case: an agent launched from
+    # the VS Code extension sits on tty `??` — it has neither a tab nor a
+    # pty, and such sessions are often the majority of active ones, not a
+    # rare exception.
+    #
+    # A session like this shows up in the list and can be worked with
+    # through hooks — answering questions, reading the transcript. What's
+    # off-limits is anything that needs a terminal: sending text, reading
+    # the screen, creating a tab.
+    class Null < Base
+      def name = :none
+
+      def available? = true
+
+      # This backend doesn't enumerate its own sessions: they're
+      # supplied by ProcessProbe (terminalless agent processes) and the
+      # hook registry.
+      def sessions = []
+    end
+  end
+end

data/lib/agents_control/terminals/tmux.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Terminals
+    # tmux.
+    #
+    # The only backend that works on both macOS and Linux, and also the
+    # fastest one: a full pane list comes back in 0.008s versus 0.9s for
+    # iTerm2 — a hundred-plus-fold difference. It's also the only one with
+    # scrollback and the only one that survives an ssh disconnect.
+    #
+    # Inside iTerm2 it runs as `tmux -CC`: tmux windows become native
+    # tabs, and both backends operate on the same machine at once.
+    class Tmux < Base
+      # %w doesn't interpolate — the literal tmux substitutions stay intact inside.
+      FORMAT_FIELDS = %w[
+        #{pane_id}
+        #{pane_tty}
+        #{pane_current_command}
+        #{pane_current_path}
+        #{session_name}
+        #{window_name}
+      ].freeze
+
+      FIELDS = %i[id tty command cwd session window].freeze
+
+      # Shells under which a pane counts as "at a prompt" rather than busy.
+      SHELLS = %w[zsh bash sh fish dash ksh tcsh].freeze
+
+      def name = :tmux
+
+      # Just having the binary is enough: the server might not be
+      # running yet, but we can still create a window in it.
+      def available? = !binary.nil?
+
+      def sessions
+        return [] unless available?
+
+        result = run("list-panes", "-a", "-F", format_string)
+        # No server isn't an error, it just means there are no panes yet.
+        return [] unless result.success?
+
+        parse_records(result.stdout, FIELDS).map do |record|
+          Session.new(
+            id: record[:id],
+            backend: name,
+            tty: record[:tty],
+            title: [record[:session], record[:window]].compact.join(":"),
+            cwd: record[:cwd],
+            # tmux has no equivalent of `is processing`, so this is nil —
+            # "unknown", not "no". ProcessProbe determines busy-ness.
+            processing: nil,
+            at_shell_prompt: SHELLS.include?(record[:command].to_s),
+            # tmux already knows what's running in the pane — this same
+            # list-panes call hands back the process name for free, with
+            # no trip through ProcessProbe needed.
+            foreground_command: record[:command]
+          )
+        end
+      end
+
+      def create_tab(cwd: nil, command: nil)
+        args = ["new-window", "-P", "-F", "#{'#'}{pane_id}"]
+        args += ["-c", cwd] if cwd && !cwd.empty?
+        args << command if command && !command.empty?
+
+        result = run(*args)
+        result.success? ? result.stdout.strip : nil
+      end
+
+      def send_text(id, text, newline: true)
+        args = ["send-keys", "-t", id, "--", text]
+        args << "Enter" if newline
+        run(*args).success?
+      end
+
+      # This is exactly what tmux is for: history, not just the visible screen.
+      def capture(id, lines: 200)
+        result = run("capture-pane", "-p", "-t", id, "-S", "-#{lines}")
+        result.success? ? result.stdout.rstrip : ""
+      end
+
+      def focus(id)
+        run("select-window", "-t", id).success? && run("select-pane", "-t", id).success?
+      end
+
+      def close(id) = run("kill-pane", "-t", id).success?
+
+      private
+
+      def format_string = FORMAT_FIELDS.join(FIELD) + RECORD
+
+      def run(*args)
+        return Executor::Result.new(stdout: "", stderr: "tmux not found", status: 127) unless binary
+
+        executor.run(binary, *args)
+      end
+
+      def binary
+        # false means "looked and didn't find it", so we don't search again on every call.
+        @binary = Which.find("tmux") || false if @binary.nil?
+        @binary || nil
+      end
+    end
+  end
+end

data/lib/agents_control/transcript.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentsControl
+  # The tail of a conversation with an agent.
+  #
+  # Read from the JSONL file whose path the agent sends with every hook.
+  # This beats scraping text off the screen for three reasons: it works
+  # the same for a terminal tab and for a VS Code session, which has no
+  # screen at all; it gives structure instead of ANSI noise; and it isn't
+  # limited to what fit in the visible area.
+  class Transcript
+    # The file grows without bound, and only the end matters. Read from
+    # the end in blocks, so a multi-megabyte history never has to be
+    # pulled fully into memory.
+    TAIL_BYTES = 256 * 1024
+
+    PROJECTS = File.expand_path("~/.claude/projects")
+
+    class << self
+      # The transcript of a tab the hooks never sent anything about.
+      #
+      # Claude Code lays out histories in directories named after the
+      # working path, with `/` and `_` replaced by `-`. If that scheme
+      # ever changes, this method just returns an empty transcript
+      # instead of breaking its caller.
+      def for_cwd(cwd, root: PROJECTS)
+        return new(nil) if cwd.to_s.empty?
+
+        directory = File.join(root, slug(cwd))
+        new(newest_in(directory))
+      end
+
+      def slug(cwd) = cwd.to_s.tr("/_", "--")
+
+      private
+
+      # One directory maps to many sessions — take the most recently modified.
+      def newest_in(directory)
+        Dir.glob(File.join(directory, "*.jsonl")).max_by { |path| File.mtime(path) }
+      end
+    end
+
+    def initialize(path)
+      @path = path
+    end
+
+    def exists? = @path && File.exist?(@path)
+
+    # The last N messages as [{role:, text:}].
+    def last(count = 6)
+      return [] unless exists?
+
+      messages = parse(tail)
+      messages.last(count)
+    end
+
+    # Ready-to-send text, in full — splitting across multiple Telegram
+    # messages, if needed, is the caller's job (Router#say_chunked).
+    def render(count = 6)
+      entries = last(count)
+      return "The conversation is empty." if entries.empty?
+
+      entries.map { |entry| "#{prefix(entry[:role])} #{entry[:text]}" }.join("\n\n")
+    end
+
+    private
+
+    def tail
+      size = File.size(@path)
+      offset = [size - TAIL_BYTES, 0].max
+
+      File.open(@path, "rb") do |file|
+        file.seek(offset)
+        # The first line after the offset is almost certainly cut off — discard it.
+        file.gets if offset.positive?
+        file.read.to_s
+      end
+    end
+
+    def parse(raw)
+      raw.each_line.filter_map do |line|
+        entry = JSON.parse(line)
+        text = extract(entry)
+        next if text.nil? || text.empty?
+
+        { role: entry["type"] || entry.dig("message", "role"), text: text }
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Content is either a string or an array of blocks; tool calls are
+    # shown by name, not as the full argument JSON — a notification needs
+    # to convey what's happening, not reproduce the call.
+    def extract(entry)
+      content = entry.dig("message", "content")
+
+      case content
+      when String then content
+      when Array then extract_blocks(content)
+      end
+    end
+
+    def extract_blocks(blocks)
+      blocks.filter_map do |block|
+        case block["type"]
+        when "text" then block["text"]
+        when "tool_use" then "→ #{block['name']}"
+        end
+      end.join("\n").strip
+    end
+
+    def prefix(role)
+      case role.to_s
+      when "user" then "🙋"
+      when "assistant" then "🤖"
+      else "·"
+      end
+    end
+  end
+end

data/lib/agents_control/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  VERSION = "0.1.0"
+end

data/lib/agents_control/which.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Finds executables by absolute path rather than via PATH.
+  #
+  # The daemon is launched by launchd, not an interactive shell, and PATH
+  # is different there: Ruby version-manager shims may be missing, and an
+  # Intel Homebrew install on Apple Silicon without Rosetta doesn't run at
+  # all. So PATH is checked last, not first.
+  module Which
+    # Directories in order of trust: version managers and ARM Homebrew
+    # first, then system paths, and only then whatever PATH turns up.
+    SEARCH_DIRS = [
+      "~/.asdf/shims",
+      "~/.rbenv/shims",
+      "/opt/homebrew/bin",
+      "/opt/homebrew/sbin",
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+      "/usr/sbin",
+      "/sbin"
+    ].freeze
+
+    module_function
+
+    # Absolute path to the binary, or nil.
+    def find(name, extra_dirs: [])
+      dirs = extra_dirs + SEARCH_DIRS
+      from_dirs(name, dirs) || from_path(name)
+    end
+
+    # Like find, but with a clear error instead of nil — for places where
+    # a missing binary means there's no point continuing.
+    def find!(name, extra_dirs: [])
+      find(name, extra_dirs: extra_dirs) ||
+        raise(NotFoundError, "executable not found: #{name.inspect}")
+    end
+
+    def from_dirs(name, dirs)
+      dirs.lazy
+          .map { |dir| File.join(File.expand_path(dir), name) }
+          .find { |path| executable?(path) }
+    end
+
+    def from_path(name)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).lazy
+         .reject(&:empty?)
+         .map { |dir| File.join(dir, name) }
+         .find { |path| executable?(path) }
+    end
+
+    def executable?(path)
+      File.file?(path) && File.executable?(path)
+    end
+
+    class NotFoundError < StandardError; end
+  end
+end