agents_control 0.1.0

data/lib/agents_control/dispatcher.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Decides what to do with an agent event: stay quiet, notify, or ask.
+  #
+  # All the policy lives here, because it's the one part of the system
+  # people actually want to tune with settings. Agent adapters only turn
+  # a payload into an Event, a channel only displays it — Dispatcher does the thinking.
+  class Dispatcher
+    # The key distinction: is a human at the keyboard.
+    #
+    # While they are, intercepting permission requests is counterproductive:
+    # they'll answer in the terminal faster than they can reach for their
+    # phone, and a blocked hook keeps the dialog from ever reaching the
+    # screen at all. So by default this only notifies, and interception
+    # is turned on explicitly — with /away before stepping out.
+    def initialize(agents:, channel:, config:, pending: nil, logger: nil)
+      @agents = agents
+      @channel = channel
+      @config = config
+      @pending = pending || Pending.new
+      @logger = logger
+    end
+
+    attr_reader :pending
+
+    # Returns the hook response body. An empty hash means "no decision" —
+    # the agent behaves as it would without us.
+    def handle(payload)
+      agent = @agents.find { |candidate| candidate.class.handles?(payload) }
+      return {} unless agent
+
+      event = agent.to_event(payload)
+      return {} unless event
+
+      reply = decide(event)
+      return {} unless reply
+
+      agent.to_response(event, reply)
+    rescue StandardError => e
+      log("failed to handle event: #{e.class}: #{e.message}")
+      {}
+    end
+
+    private
+
+    def decide(event)
+      unless event.question?
+        notify(event)
+        return nil
+      end
+
+      # AskUserQuestion's answer is never delivered through the hook
+      # response — only allow/deny is. Blocking here would just hold the
+      # hook open for the full reply_timeout and then auto-deny, with
+      # nothing gained: the actual answer has to be typed into the
+      # terminal, which Channel does directly, unconditionally.
+      if event.ask_user_question?
+        notify(event)
+        return nil
+      end
+
+      # A human is at the keyboard — don't get in their way, just notify.
+      unless away?
+        notify(event)
+        return nil
+      end
+
+      automatic(event) || ask(event)
+    end
+
+    def away? = @config.get("answers.away", false)
+
+    # What can be decided without a human.
+    def automatic(event)
+      case event.kind
+      when :needs_permission then automatic_permission(event)
+      when :needs_input then automatic_input(event)
+      end
+    end
+
+    def automatic_permission(event)
+      return nil unless @config.get("answers.auto_approve_permissions", false)
+      # The forbidden list overrides any automatic setting: these things
+      # a human confirms in person, whatever the settings say.
+      return nil if forbidden?(event)
+
+      Reply.allow
+    end
+
+    # A "continue" reply is safe — it grants the agent no new
+    # permissions, it only clears the question "should I go on?" That's
+    # why it's on by default, unlike automatic tool approval.
+    def automatic_input(event)
+      return nil unless @config.get("answers.auto_continue", true)
+      return nil unless continuation?(event.text)
+
+      Reply.text("Continue.")
+    end
+
+    CONTINUATION = /(продолж|continue|proceed|shall i|идти дальше|go ahead)/i
+
+    # Signs that a human is being offered a choice, not asked permission to go on.
+    ALTERNATIVE = /(\bили\b|\bлибо\b|\bor\b|^\s*\d[.)]\s|\bвариант)/i
+
+    # A "should I continue?" question differs from a substantive one in
+    # having no subject — it's answerable without reading any context.
+    #
+    # The word "continue" alone isn't enough for this: "Should I continue
+    # the refactor, or show the plan first?" is a choice, and answering
+    # "continue" on the human's behalf there means making the decision
+    # for them. So the presence of an alternative overrides the
+    # automation, even when the word matches.
+    def continuation?(text)
+      value = text.to_s
+      return false if value.empty? || value.length > 300
+      return false if value.match?(ALTERNATIVE)
+
+      value.match?(CONTINUATION)
+    end
+
+    def forbidden?(event)
+      haystack = [event.tool_name, event.tool_input.to_s].join(" ").downcase
+
+      Array(@config.get("answers.never_auto_approve", [])).any? do |needle|
+        haystack.include?(needle.to_s.downcase)
+      end
+    end
+
+    def ask(event)
+      timeout = @config.get("answers.reply_timeout", 600)
+      log("asking: #{event.label} — #{event.summary[0, 80]}")
+
+      reply = @channel.ask(event, pending: @pending, timeout: timeout)
+
+      # Silence is a refusal, not a permission. If nobody answered while
+      # the owner was out, the action doesn't happen.
+      log("no answer, declining: #{event.label}") if reply.none?
+      reply
+    end
+
+    def notify(event)
+      return unless notifiable?(event)
+
+      log("notifying: #{event.label} — #{event.summary.to_s[0, 80]}")
+      @channel.notify(event)
+    rescue StandardError => e
+      log("failed to notify: #{e.message}")
+    end
+
+    # Not every event can make noise: an agent calls tools dozens of
+    # times per turn. Only report what a human actually needs to know about.
+    def notifiable?(event)
+      case event.kind
+      when :error then true
+      when :needs_permission, :needs_input then @config.get("answers.notify_when_present", true)
+      else false
+      end
+    end
+
+    def log(message) = @logger&.puts("[dispatcher] #{message}")
+  end
+end

data/lib/agents_control/doctor.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # Checks that everything is in place.
+  #
+  # Main principle: check the environment the daemon will actually get,
+  # not the one the user happens to be sitting in. An interactive shell
+  # can show a different Ruby, a different PATH, different environment
+  # variables than what a separately launched daemon process will see.
+  class Doctor
+    Check = Struct.new(:name, :status, :detail, :fix, keyword_init: true) do
+      def ok? = status == :ok
+      def failed? = status == :fail
+      def icon = { ok: "✓", warn: "!", fail: "✗" }[status]
+    end
+
+    # AppleScript's error when the user hasn't granted permission to
+    # control the app.
+    NOT_AUTHORISED = "-1743"
+
+    def initialize(config: nil, secrets: nil, executor: Executor.new, api: nil)
+      @config = config || Config.load
+      @secrets = secrets || Secrets.new
+      @executor = executor
+      @api = api
+    end
+
+    CHECKS = %i[
+      ruby_check terminal_check automation_check agent_binary_check
+      token_check chats_check bot_check daemon_check hooks_check
+      anchors_check wake_check
+    ].freeze
+
+    # Checks run one at a time, each wrapped: a diagnostic tool has no
+    # business crashing. An unexpected error is just another result, not
+    # the end of the run — otherwise the first small thing would hide
+    # everything after it.
+    def run
+      CHECKS.filter_map do |name|
+        send(name)
+      rescue StandardError => e
+        Check.new(name: name.to_s.sub("_check", ""), status: :fail,
+                  detail: "check failed: #{e.class}")
+      end
+    end
+
+    private
+
+    def ok(name, detail) = Check.new(name: name, status: :ok, detail: detail)
+    def warn(name, detail, fix = nil) = Check.new(name: name, status: :warn, detail: detail, fix: fix)
+    def fail(name, detail, fix = nil) = Check.new(name: name, status: :fail, detail: detail, fix: fix)
+
+    # The plist gets RbConfig.ruby — the interpreter running this code,
+    # so it's guaranteed to work. What's checked isn't that, but what
+    # would be found by searching PATH: a version manager's broken shim
+    # can sit ahead of the real Ruby there.
+    def ruby_check
+      running = RbConfig.ruby
+      return fail("Ruby", "#{RUBY_VERSION} — needs 3.2+", "update the interpreter") if RUBY_VERSION < "3.2"
+
+      found = Which.find("ruby")
+      shadow = found && found != running && !working_ruby?(found)
+
+      return warn("Ruby", "#{RUBY_VERSION} — #{running}",
+                  "a broken #{found} sits earlier on PATH; the service uses " \
+                  "an absolute path, so this won't get in the way") if shadow
+
+      ok("Ruby", "#{RUBY_VERSION} — #{running}")
+    end
+
+    def working_ruby?(path)
+      result = @executor.run(path, "-e", "print RUBY_VERSION")
+
+      result.success? && !result.stdout.strip.empty?
+    end
+
+    def terminal_check
+      registry = Registry.new(executor: @executor)
+      names = registry.available_backends.map(&:name)
+
+      return warn("Terminal", "no backends available",
+                  "install tmux or launch iTerm2 — without them only monitoring works") if names.empty?
+
+      ok("Terminal", names.join(", "))
+    end
+
+    # Permission to control iTerm2 can't be granted programmatically: the
+    # TCC database is closed off by SIP, and that's a load-bearing part
+    # of macOS security, not an oversight. All that's possible is
+    # triggering the prompt at a clear moment, catching the refusal, and
+    # opening the right settings pane.
+    def automation_check
+      return nil unless macos?
+      return nil unless iterm_running?
+
+      result = @executor.run(Which.find("osascript"), "-e",
+                             'tell application "iTerm2" to count windows')
+
+      return ok("iTerm2 permission", "granted") if result.success?
+
+      if result.stderr.include?(NOT_AUTHORISED)
+        fail("iTerm2 permission", "not granted",
+             'open "x-apple.systempreferences:com.apple.preference.security?Privacy_Automation"')
+      else
+        warn("iTerm2 permission", result.stderr.to_s[0, 80])
+      end
+    end
+
+    def agent_binary_check
+      path = Which.find("claude")
+      return warn("Claude Code", "binary not found", "needed for rate-limit anchors") unless path
+
+      ok("Claude Code", path)
+    end
+
+    def token_check
+      source = @secrets.source_for(:telegram_token)
+      return fail("Token", "not found", "agents_control setup") unless source
+
+      insecure = source.respond_to?(:insecure?) && source.insecure?
+      return warn("Token", "#{source.name} — insecure storage") if insecure
+
+      ok("Token", source.name)
+    end
+
+    def chats_check
+      chats = Array(@config.get("telegram.allowed_chat_ids", []))
+      return fail("Allowed chats", "list is empty — the bot won't answer anyone",
+                  "agents_control setup") if chats.empty?
+
+      ok("Allowed chats", chats.join(", "))
+    end
+
+    TOKEN_SHAPE = /\A\d+:[A-Za-z0-9_-]{30,}\z/
+
+    def bot_check
+      token = @secrets.get(:telegram_token)
+      return nil unless token
+
+      # The shape is checked before touching the network: unprintable
+      # characters would land straight in the URL and fail the request
+      # with a cryptic address-parsing error.
+      return fail("Bot", "token doesn't look like one issued by BotFather", "agents_control setup") unless
+        token.match?(TOKEN_SHAPE)
+
+      me = (@api || Channels::Telegram::Api.new(token)).get_me
+      ok("Bot", "@#{me['username']}")
+    rescue Channels::Telegram::Api::Unavailable
+      warn("Bot", "network unavailable — couldn't check")
+    rescue Channels::Telegram::Api::Error => e
+      fail("Bot", e.message, "check the token: agents_control setup")
+    end
+
+    # A successful connection alone means nothing: something else could
+    # be sitting on the port, and in some environments a local connect
+    # always succeeds. So a request is sent and the response is
+    # inspected — our server refuses a request with no secret, and
+    # that's its signature.
+    def daemon_check
+      port = @config.get("hooks.port", Daemon::DEFAULT_PORT)
+
+      case daemon_response(port)
+      when :ours then ok("Daemon", "running on port #{port}")
+      when :stranger then fail("Daemon", "port #{port} is taken by something else",
+                               "change hooks.port in settings")
+      else warn("Daemon", "not running", "agents_control daemon")
+      end
+    end
+
+    def daemon_response(port)
+      socket = Socket.tcp("127.0.0.1", port, connect_timeout: 1)
+      socket.print("POST /ping HTTP/1.1\r\nHost: localhost\r\nContent-Length: 2\r\n\r\n{}")
+      status = socket.readline
+
+      status.include?("403") ? :ours : :stranger
+    rescue StandardError
+      :down
+    ensure
+      socket&.close
+    end
+
+    def hooks_check
+      agent = Agents::ClaudeCode.new
+      return ok("Hooks", "connected") if agent.installed?
+
+      # Not an error: the daemon connects them itself on start and
+      # removes them on stop, or the agent would complain about an
+      # unreachable address.
+      warn("Hooks", "not connected — expected while the daemon is off")
+    rescue StandardError => e
+      fail("Hooks", e.message)
+    end
+
+    def anchors_check
+      return warn("Rate-limit anchors", "off", "turn on in /settings") unless @config.get("anchors.enabled", false)
+
+      scheduler = Anchors::Scheduler.new(config: @config, store: Store.new)
+      at = scheduler.next_run_at
+
+      ok("Rate-limit anchors", "model #{@config.get('anchors.model')}, next at #{at&.strftime('%d.%m %H:%M')}")
+    end
+
+    # A 7am anchor won't fire if the laptop is asleep: launchd runs the
+    # task after waking, and the precise timing is lost.
+    def wake_check
+      return nil unless macos?
+      return nil unless @config.get("anchors.enabled", false)
+
+      scheduled = @executor.run(Which.find("pmset"), "-g", "sched").stdout.to_s
+
+      return ok("Wake schedule", "configured") if scheduled.match?(/wake|poweron/i)
+
+      warn("Wake schedule", "the Mac could be asleep at anchor time",
+           "sudo pmset repeat wakeorpoweron MTWRF #{earliest_anchor}:00")
+    end
+
+    def earliest_anchor
+      Array(@config.get("anchors.schedule", [])).min.to_s.sub(/\A(\d):/, "0\\1:")
+    end
+
+    def macos? = RUBY_PLATFORM.include?("darwin")
+
+    def iterm_running?
+      ProcessProbe.new(executor: @executor).refresh.running?("iTerm2")
+    end
+
+    def port_open?(port)
+      Socket.tcp("127.0.0.1", port, connect_timeout: 1, &:close)
+      true
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/agents_control/event.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  # A normalized event from an agent.
+  #
+  # The core and the notification channel operate only on this type and
+  # know nothing about Claude Code or Codex. An agent adapter's job is to
+  # bring its own payload into this shape, and that's the extent of its
+  # knowledge of the outside world.
+  #
+  # The shape wasn't picked arbitrarily: Claude Code and Codex independently
+  # converged on nearly the same set of events and the same way of
+  # returning a decision, so this describes an existing commonality rather
+  # than a speculative abstraction.
+  class Event
+    KINDS = %i[
+      needs_permission
+      needs_input
+      finished
+      error
+      started
+      ended
+      progress
+    ].freeze
+
+    attr_reader :kind, :agent, :session_id, :cwd, :text, :options,
+                :tool_name, :tool_input, :transcript_path, :raw
+
+    def initialize(kind:, agent:, session_id:, cwd: nil, text: nil, options: [],
+                   tool_name: nil, tool_input: nil, transcript_path: nil, raw: {})
+      raise ArgumentError, "unknown event kind: #{kind}" unless KINDS.include?(kind)
+
+      @kind = kind
+      @agent = agent
+      @session_id = session_id
+      @cwd = cwd
+      @text = text
+      @options = options
+      @tool_name = tool_name
+      @tool_input = tool_input
+      @transcript_path = transcript_path
+      @raw = raw
+    end
+
+    # Does a human need to weigh in. Everything else is background info.
+    def question? = %i[needs_permission needs_input].include?(kind)
+
+    # AskUserQuestion is structurally a permission request (it goes
+    # through the same PermissionRequest hook as any tool call), but
+    # answering it means picking one of its listed options — allow/deny
+    # doesn't apply, and neither does the usual reply-becomes-hook-response path.
+    def ask_user_question? = tool_name == "AskUserQuestion"
+
+    # Short name of where this is happening. The full path in a
+    # notification only gets in the way — what matters in a list is
+    # recognizing the project, not seeing /Users/...
+    def label
+      return File.basename(cwd) if cwd && !cwd.empty?
+
+      session_id.to_s[0, 8]
+    end
+
+    # Description of what the agent is about to do.
+    def summary
+      case kind
+      when :needs_permission then permission_summary
+      when :needs_input then text.to_s
+      when :error then "error: #{text}"
+      else text.to_s
+      end
+    end
+
+    private
+
+    # AskUserQuestion isn't a "permission" — it's a question with options
+    # to pick from; the tool name won't tell a human anything, the
+    # question itself is what matters.
+    def permission_summary
+      return describe_questions if ask_user_question?
+
+      "#{tool_name}: #{describe_tool}"
+    end
+
+    # Every tool has its own main field; show that, not the whole JSON.
+    def describe_tool
+      return "" unless tool_input.is_a?(Hash)
+
+      value = tool_input["command"] || tool_input["file_path"] ||
+              tool_input["pattern"] || tool_input["url"]
+
+      value.to_s
+    end
+
+    def describe_questions
+      questions = tool_input.is_a?(Hash) ? tool_input["questions"] : nil
+      return "" unless questions.is_a?(Array)
+
+      questions.map { |question| describe_question(question) }.join("\n\n")
+    end
+
+    def describe_question(question)
+      lines = ["#{question['header']}: #{question['question']}"]
+
+      Array(question["options"]).each_with_index do |option, index|
+        lines << "#{index + 1}. #{option['label']} — #{option['description']}"
+      end
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/agents_control/executor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module AgentsControl
+  # The single point through which the utility talks to the outside world.
+  #
+  # Exists for the "adapter isolation" rule: osascript can hang dead when
+  # iTerm2 shows a beachball, and without a hard timeout that takes the
+  # whole daemon down with it. No adapter calls Open3 directly.
+  #
+  # Tests swap this for FakeExecutor — no real terminal needed in CI.
+  class Executor
+    DEFAULT_TIMEOUT = 10
+
+    # status 124 — coreutils timeout(1) convention, 127 — "command not found".
+    TIMEOUT_STATUS   = 124
+    NOT_FOUND_STATUS = 127
+
+    Result = Struct.new(:stdout, :stderr, :status, keyword_init: true) do
+      def success? = status.zero?
+      def timeout? = status == TIMEOUT_STATUS
+      def not_found? = status == NOT_FOUND_STATUS
+    end
+
+    def initialize(timeout: DEFAULT_TIMEOUT)
+      @timeout = timeout
+    end
+
+    # Always returns a Result — never raises. A failing external command
+    # must not take the daemon down with it.
+    def run(*argv, stdin: nil, timeout: @timeout)
+      Open3.popen3(*argv) do |input, output, errors, wait_thread|
+        write_stdin(input, stdin)
+
+        # Read on separate threads: otherwise a process that fills the
+        # stderr buffer blocks waiting to be read, while we block waiting
+        # for it to exit. report_on_exception is off on purpose: on a
+        # timeout, the reader threads find popen3's pipe already closed
+        # and raise IOError. That's expected and handled below, but Ruby
+        # prints that trace to stderr by default, where it looks like a
+        # real crash in the utility's console.
+        out_reader = Thread.new { output.read }
+        err_reader = Thread.new { errors.read }
+        [out_reader, err_reader].each { |thread| thread.report_on_exception = false }
+
+        return kill(wait_thread, out_reader, err_reader, timeout) unless wait_thread.join(timeout)
+
+        Result.new(
+          stdout: out_reader.value.to_s,
+          stderr: err_reader.value.to_s,
+          status: wait_thread.value.exitstatus || -1
+        )
+      end
+    rescue Errno::ENOENT, Errno::EACCES => e
+      Result.new(stdout: "", stderr: e.message, status: NOT_FOUND_STATUS)
+    end
+
+    private
+
+    def write_stdin(input, data)
+      input.write(data) if data
+      input.close
+    rescue Errno::EPIPE
+      # The command exited without reading stdin — that's its right.
+    end
+
+    def kill(wait_thread, *readers, timeout)
+      begin
+        Process.kill("KILL", wait_thread.pid)
+        wait_thread.join
+      rescue Errno::ESRCH
+        # The process died on its own between join and kill.
+      end
+
+      # Readers are stopped explicitly: otherwise they stay hanging on
+      # already-closed pipes and pile up on every timeout.
+      readers.each(&:kill)
+
+      Result.new(stdout: "", stderr: "command didn't respond within #{timeout}s", status: TIMEOUT_STATUS)
+    end
+  end
+end