agents_control 0.1.0

data/lib/agents_control/agents/claude_code.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module AgentsControl
+  module Agents
+    # Claude Code.
+    #
+    # `{"decision":"block","reason":"..."}` returned to a Stop hook comes
+    # back to the agent as user input, and the agent continues working
+    # with that text — this is what the whole idea of answering from
+    # Telegram rests on.
+    class ClaudeCode < Base
+      # Claude Code's config directory honors CLAUDE_CONFIG_DIR — just
+      # like the agent itself. This matters both for anyone keeping
+      # settings outside the home directory, and for tests: without this
+      # override a test run would edit the user's real file.
+      def self.settings_path
+        base = ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude")
+
+        File.join(base, "settings.json")
+      end
+
+      # The events we care about. Others arrive too but are ignored:
+      # subscribing to everything is extra overhead on every agent call.
+      EVENTS = %w[SessionStart SessionEnd PermissionRequest Stop Notification StopFailure].freeze
+
+      class << self
+        def key = :claude_code
+
+        def binaries = %w[claude]
+
+        def handles?(payload)
+          payload.is_a?(Hash) && payload.key?("hook_event_name")
+        end
+      end
+
+      def initialize(settings_path: self.class.settings_path)
+        @settings_path = settings_path
+      end
+
+      def capabilities = %i[push blocking_reply]
+
+      def to_event(payload)
+        case payload["hook_event_name"]
+        when "SessionStart" then build(payload, :started)
+        when "SessionEnd" then build(payload, :ended)
+        when "PermissionRequest" then permission_event(payload)
+        when "Stop" then stop_event(payload)
+        when "Notification" then notification_event(payload)
+        when "StopFailure" then build(payload, :error, text: payload["error"])
+        end
+      end
+
+      # Reply → the hook response body. The shape depends on the event:
+      # granting permission and continuing a dialog are structured
+      # differently in the API.
+      def to_response(event, reply)
+        case event.raw["hook_event_name"]
+        when "PermissionRequest" then permission_response(event, reply)
+        when "Stop" then stop_response(reply)
+        else {}
+        end
+      end
+
+      # ── installation ──────────────────────────────────────────────────
+
+      # Merge, not overwrite: settings.json holds other settings we don't
+      # own, and they must not be clobbered. The timeout is set
+      # explicitly: Claude Code waits longer than the documented 600
+      # seconds, and how long to wait is our call.
+      def install!(url, secret: nil, timeout: 660)
+        settings = read_settings
+        settings["hooks"] ||= {}
+
+        EVENTS.each do |name|
+          settings["hooks"][name] = merge_hook(settings["hooks"][name],
+                                               hook_entry(url, name, secret, timeout))
+        end
+
+        write_settings(settings)
+      end
+
+      def uninstall!
+        settings = read_settings
+        hooks = settings["hooks"] || {}
+
+        EVENTS.each do |name|
+          next unless hooks[name]
+
+          hooks[name] = hooks[name].filter_map { |group| without_ours(group) }
+          hooks.delete(name) if hooks[name].empty?
+        end
+
+        # If the key wasn't there before us, it shouldn't be there after
+        # us either: cleaning up after ourselves means not leaving an
+        # empty shell behind.
+        settings.delete("hooks") if hooks.empty?
+
+        write_settings(settings)
+      end
+
+      def installed?
+        hooks = read_settings["hooks"] || {}
+
+        EVENTS.all? { |name| Array(hooks[name]).any? { |group| ours?(group) } }
+      end
+
+      private
+
+      def build(payload, kind, text: nil, **extra)
+        Event.new(
+          kind: kind,
+          agent: key,
+          session_id: payload["session_id"],
+          cwd: payload["cwd"],
+          transcript_path: payload["transcript_path"],
+          text: text,
+          raw: payload,
+          **extra
+        )
+      end
+
+      def permission_event(payload)
+        build(payload, :needs_permission,
+              tool_name: payload["tool_name"],
+              tool_input: payload["tool_input"])
+      end
+
+      # Stop fires at the end of every turn, not only when the agent is
+      # actually asking something. The payload alone can't tell them
+      # apart — whether to bother the human is a decision the Dispatcher
+      # makes based on settings.
+      #
+      # stop_hook_active means we're already holding this turn blocked.
+      # Answering with another block would produce an infinite loop.
+      def stop_event(payload)
+        return nil if payload["stop_hook_active"]
+
+        build(payload, :needs_input, text: payload["last_assistant_message"])
+      end
+
+      def notification_event(payload)
+        kind = payload["notificationType"] == "agent_completed" ? :finished : :progress
+
+        build(payload, kind, text: payload["message"])
+      end
+
+      def permission_response(event, reply)
+        behavior = reply.permits? ? "allow" : "deny"
+        decision = { "behavior" => behavior }
+
+        # "Allow and don't ask again" — the rule is remembered by the
+        # agent itself, we don't need to store it afterward.
+        decision["storeRule"] = { "matcher" => event.tool_name } if reply.allow? && reply.remember
+
+        {
+          "hookSpecificOutput" => {
+            "hookEventName" => "PermissionRequest",
+            "decision" => decision
+          }
+        }
+      end
+
+      # An empty reply means "let the agent stop". A block with text
+      # feeds that text back to the agent as input.
+      def stop_response(reply)
+        return {} unless reply.text? && !reply.text.to_s.empty?
+
+        { "decision" => "block", "reason" => reply.text }
+      end
+
+      # ── settings.json handling ─────────────────────────────────────────
+
+      # The secret is written as a literal value, not via $VAR:
+      # environment substitution pulls variables from the agent's own
+      # process, which the user launches by hand — our environment isn't
+      # there.
+      #
+      # The settings file is already readable only by its owner, and the
+      # secret protects against another process on the local port, not
+      # against another user on the same account.
+      def hook_entry(url, name, secret, timeout)
+        hook = {
+          "type" => "http",
+          "url" => "#{url}/#{name}",
+          "timeout" => timeout,
+          "statusMessage" => "agents_control: waiting for a reply in Telegram",
+          # This marker is how our own entries are found on uninstall,
+          # without touching anyone else's.
+          "_agents_control" => true
+        }
+        hook["headers"] = { "Authorization" => "Bearer #{secret}" } if secret
+
+        { "hooks" => [hook] }
+      end
+
+      def merge_hook(existing, entry)
+        groups = Array(existing).reject { |group| ours?(group) }
+
+        groups + [entry]
+      end
+
+      def ours?(group)
+        Array(group["hooks"]).any? { |hook| hook["_agents_control"] }
+      end
+
+      def without_ours(group)
+        remaining = Array(group["hooks"]).reject { |hook| hook["_agents_control"] }
+
+        remaining.empty? ? nil : group.merge("hooks" => remaining)
+      end
+
+      def read_settings
+        return {} unless File.exist?(@settings_path)
+
+        parsed = JSON.parse(File.read(@settings_path))
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        # A broken file that isn't ours to fix, but we definitely have
+        # no right to overwrite its contents either.
+        raise Error, "could not parse #{@settings_path}: file is corrupted"
+      end
+
+      # Via a temporary file: an interrupted write must not leave the
+      # user with no Claude Code settings at all. Chmod'd before the
+      # rename: this file carries our hook secret in plaintext once
+      # install! runs, and it must never sit world-readable, even briefly.
+      def write_settings(settings)
+        FileUtils.mkdir_p(File.dirname(@settings_path))
+        temporary = "#{@settings_path}.agents_control.tmp"
+
+        File.write(temporary, JSON.pretty_generate(settings))
+        File.chmod(0o600, temporary)
+        File.rename(temporary, @settings_path)
+        true
+      ensure
+        FileUtils.rm_f(temporary) if temporary && File.exist?(temporary)
+      end
+    end
+  end
+end

data/lib/agents_control/anchors/scheduler.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "date"
+
+module AgentsControl
+  module Anchors
+    # Placing rate-limit windows on a schedule.
+    #
+    # A five-hour window starts at the minute of the first message and
+    # expires exactly three hundred minutes later. This tool doesn't add
+    # a single extra token — it moves window boundaries to where they're
+    # convenient. The difference is between "the window reset at 2:37pm,
+    # mid-work" and "windows at exactly 7am, noon, 5pm."
+    #
+    # Pinging has to use a cheap model. The five-hour window is shared
+    # across the account, but weekly limits are tracked per model family:
+    # an anchor on opus would spend the scarcest bucket for an effect
+    # haiku gives for free.
+    class Scheduler
+      DAYS = %w[sun mon tue wed thu fri sat].freeze
+
+      # How late it's still worth catching up on a missed slot. If the
+      # laptop slept and woke an hour later, an anchor is already
+      # pointless — the window will start somewhere other than planned regardless.
+      GRACE = 300
+
+      # How often to wake up and check the clock.
+      TICK = 30
+
+      def initialize(config:, store:, executor: Executor.new, clock: -> { Time.now }, logger: nil)
+        @config = config
+        @store = store
+        @executor = executor
+        @clock = clock
+        @logger = logger
+        @running = false
+      end
+
+      # The thread always starts; whether it's enabled is checked on
+      # every tick — so a setting changed from the menu takes effect
+      # without restarting the daemon.
+      def start
+        @running = true
+        @thread = Thread.new do
+          tick while @running
+        end
+
+        self
+      end
+
+      def stop
+        @running = false
+        @thread&.kill
+      end
+
+      # One pass: fire if the time has come.
+      def tick(now = @clock.call)
+        due_slot(now)&.then { |slot| fire(slot, now) } if enabled?
+      rescue StandardError => e
+        log("failure: #{e.class}: #{e.message}")
+      ensure
+        sleep(TICK) if @running
+      end
+
+      # The next firing time — for doctor and /status.
+      def next_run_at(from = @clock.call)
+        (0..7).each do |offset|
+          date = from.to_date + offset
+          next unless enabled_day?(date)
+
+          slot = slots_on(date).find { |time| time > from }
+          return slot if slot
+        end
+
+        nil
+      end
+
+      # Whether a window is currently active. Known because the daemon
+      # sees every agent event: any of them means a human was just working.
+      def window_active?(now = @clock.call)
+        last = @store.get(ACTIVITY_KEY)
+        return false unless last
+
+        now.to_i - last.to_i < WINDOW
+      end
+
+      ACTIVITY_KEY = "agent:last_activity"
+      WINDOW = 5 * 3600
+
+      private
+
+      def enabled? = @config.get("anchors.enabled", false)
+
+      def schedule = Array(@config.get("anchors.schedule", []))
+
+      def enabled_day?(date)
+        days = Array(@config.get("anchors.days", DAYS)).map(&:to_s)
+
+        days.include?(DAYS[date.wday])
+      end
+
+      def slots_on(date)
+        schedule.filter_map do |entry|
+          hour, minute = entry.to_s.split(":").map(&:to_i)
+          next if hour.nil?
+
+          Time.new(date.year, date.month, date.day, hour, minute, 0)
+        end.sort
+      end
+
+      def due_slot(now)
+        return nil unless enabled_day?(now.to_date)
+
+        slots_on(now.to_date).find do |slot|
+          now >= slot && now - slot < GRACE && !fired?(slot)
+        end
+      end
+
+      def fired?(slot) = !@store.get(slot_key(slot)).nil?
+
+      def slot_key(slot) = "anchor:#{slot.strftime('%Y-%m-%d %H:%M')}"
+
+      def fire(slot, now)
+        # The marker is set before the call, not after: if the ping
+        # hangs or the process crashes, retrying it half a minute later
+        # is pointless.
+        @store.put(now.to_i, ttl: 86_400 * 2, key: slot_key(slot))
+
+        if @config.get("anchors.skip_if_window_active", true) && window_active?(now)
+          return log("skipping #{slot.strftime('%H:%M')}: window is already open")
+        end
+
+        ping(slot)
+      end
+
+      def ping(slot)
+        binary = Which.find("claude")
+        return log("couldn't find claude — anchor skipped") unless binary
+
+        model = @config.get("anchors.model", "haiku")
+        result = @executor.run(binary, "-p", "ok", "--model", model,
+                               "--max-turns", "1", timeout: 120)
+
+        if result.success?
+          log("anchor #{slot.strftime('%H:%M')} on #{model}: window opened")
+        else
+          log("anchor #{slot.strftime('%H:%M')} failed: #{result.stderr.to_s[0, 120]}")
+        end
+      end
+
+      # 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("[anchors] #{message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/agents_control/channels/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    # The notification channel contract.
+    #
+    # There's only one implementation right now — Telegram. The interface
+    # is still broken out because the core must not know about buttons
+    # and chats: it operates on an event and a reply, and how that's
+    # shown to a human is the channel's concern.
+    #
+    # A second implementation (ntfy, Slack, whatever) is deliberately not
+    # invented ahead of time: the seam is marked out, but guessing its
+    # shape before a real need shows up is exactly the kind of
+    # complication this project avoids.
+    class Base
+      # Notify, expecting nothing back.
+      def notify(_event) = raise(NotImplementedError)
+
+      # Ask a question and return a Reply, or nil once the timeout expires.
+      def ask(_event, timeout:) = raise(NotImplementedError)
+
+      # Whether the channel is ready to work: has a token, has someone to talk to.
+      def ready? = raise(NotImplementedError)
+    end
+  end
+end

data/lib/agents_control/channels/telegram/api.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "timeout"
+require "json"
+require "uri"
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # A thin Bot API client built on the stdlib.
+      #
+      # Deliberately gem-free: `net/http` covers everything needed, and
+      # an extra dependency in a tool installed with a single command
+      # costs more than the lines it would save.
+      #
+      # The token is part of the URL, so any trace of a request —
+      # exception message, log, debug output — must go through redact.
+      # Otherwise the secret leaks somewhere nobody meant to put it.
+      class Api
+        HOST = "api.telegram.org"
+
+        # Telegram requires answering a button press within 10 seconds,
+        # or it stays stuck in the interface. Regular calls are kept
+        # noticeably shorter than that.
+        CALL_TIMEOUT = 8
+
+        Error = Class.new(AgentsControl::Error)
+
+        # Another process is already reading updates with this same
+        # token. This doesn't resolve itself: one instance per token is required.
+        Conflict = Class.new(Error)
+
+        # Too many requests. The response carries retry_after — how long to wait.
+        class TooManyRequests < Error
+          attr_reader :retry_after
+
+          def initialize(message, retry_after)
+            super(message)
+            @retry_after = retry_after
+          end
+        end
+
+        # The network dropped. Unlike other errors, this is an expected
+        # state for a laptop that got closed and carried off; it's fixed
+        # by retrying, not by stopping.
+        Unavailable = Class.new(Error)
+
+        def initialize(token, http: nil)
+          @token = token
+          @http = http || Http.new
+        end
+
+        def get_me = call("getMe")
+
+        # timeout here means long polling: the connection stays open
+        # until an update shows up. The network timeout has to be
+        # noticeably longer, or the client would drop the connection
+        # right as the server was about to answer.
+        def get_updates(offset: nil, timeout: 30)
+          call(
+            "getUpdates",
+            { offset: offset, timeout: timeout, allowed_updates: %w[message callback_query] },
+            read_timeout: timeout + 15
+          )
+        end
+
+        def send_message(chat_id:, text:, reply_markup: nil, parse_mode: nil)
+          call("sendMessage", {
+                 chat_id: chat_id, text: text, parse_mode: parse_mode,
+                 reply_markup: reply_markup && JSON.generate(reply_markup)
+               })
+        end
+
+        def edit_message_text(chat_id:, message_id:, text:, reply_markup: nil)
+          call("editMessageText", {
+                 chat_id: chat_id, message_id: message_id, text: text,
+                 reply_markup: reply_markup && JSON.generate(reply_markup)
+               })
+        end
+
+        # The command menu in the Telegram UI: a button next to the
+        # input field instead of hunting through the chat for a list.
+        def set_my_commands(commands)
+          payload = commands.map { |name, description| { command: name, description: description } }
+
+          call("setMyCommands", { commands: JSON.generate(payload) })
+        end
+
+        def answer_callback_query(id, text: nil, show_alert: false)
+          call("answerCallbackQuery", { callback_query_id: id, text: text, show_alert: show_alert })
+        end
+
+        # Strip the token out of arbitrary text before logging it.
+        #
+        # Matches both the literal value and its `inspect`-escaped form
+        # (control characters like a tab become the two characters
+        # `\t`): `URI::InvalidURIError`'s message is built with
+        # `inspect`, so a plain literal match alone would miss the token
+        # whenever it contains anything `inspect` escapes, and let it
+        # straight through into a log.
+        #
+        # An empty token is guarded separately: `gsub` against an empty
+        # pattern matches between every character, turning any message
+        # into unreadable noise instead of leaving it untouched.
+        def redact(text)
+          return text.to_s if @token.to_s.empty?
+
+          text.to_s.gsub(Regexp.union(@token.to_s, escaped_token), "<token>")
+        end
+
+        private
+
+        def escaped_token = @token.to_s.inspect[1..-2]
+
+        def call(method, params = {}, read_timeout: CALL_TIMEOUT)
+          response = @http.post(url_for(method), compact(params), read_timeout: read_timeout)
+          parse(response, method)
+        rescue Http::NetworkError => e
+          raise Unavailable, redact(e.message)
+        rescue URI::InvalidURIError
+          # Don't even try to redact this one: the token sits inside a
+          # URI, escaped, and a redaction pass that turned out wrong
+          # would be worse than a message with none of the URI in it at all.
+          raise Error, "#{method}: token is not valid for a URL (unexpected characters)"
+        end
+
+        def url_for(method) = URI("https://#{HOST}/bot#{@token}/#{method}")
+
+        # Drop nil fields: Telegram treats them as values that were actually passed.
+        def compact(params) = params.compact
+
+        def parse(response, method)
+          body = JSON.parse(response.body)
+          return body["result"] if body["ok"]
+
+          raise_api_error(body, method)
+        rescue JSON::ParserError
+          raise Error, "#{method}: unrecognized response (HTTP #{response.code})"
+        end
+
+        def raise_api_error(body, method)
+          description = redact(body["description"].to_s)
+          retry_after = body.dig("parameters", "retry_after")
+
+          case body["error_code"]
+          when 409 then raise Conflict, "#{method}: another process is already reading updates"
+          when 429 then raise TooManyRequests.new("#{method}: too many requests", retry_after.to_i)
+          else raise Error, "#{method}: #{description}"
+          end
+        end
+      end
+
+      # Transport is split out separately so tests never hit the network.
+      class Http
+        NetworkError = Class.new(StandardError)
+
+        def post(uri, params, read_timeout:)
+          request = Net::HTTP::Post.new(uri)
+          request.set_form_data(params)
+
+          Net::HTTP.start(uri.host, uri.port,
+                          use_ssl: true, open_timeout: 10, read_timeout: read_timeout) do |http|
+            http.request(request)
+          end
+        rescue *NETWORK_ERRORS => e
+          raise NetworkError, e.message
+        end
+
+        NETWORK_ERRORS = [
+          Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+          Errno::ENETUNREACH, Errno::ETIMEDOUT, Errno::EPIPE,
+          SocketError, Timeout::Error, OpenSSL::SSL::SSLError, IOError
+        ].freeze
+      end
+    end
+  end
+end