agents_control 0.1.0

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

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # The long-polling loop.
+      #
+      # Webhooks are deliberately not used: they need a public address
+      # and a certificate. Long polling works behind NAT, from a coffee
+      # shop, and with the laptop lid closed — everywhere this tool
+      # actually lives.
+      class Bot
+        OFFSET_KEY = "telegram:offset"
+
+        # Pause after a network failure: grows toward a ceiling so a
+        # closed laptop doesn't hammer reconnects all night.
+        BACKOFF = [1, 2, 5, 10, 30, 60].freeze
+
+        def initialize(api:, router:, store:, config:, logger: $stdout)
+          @api = api
+          @router = router
+          @store = store
+          @config = config
+          @logger = logger
+          @running = false
+        end
+
+        # Polling runs on its own thread while the main one waits for a
+        # stop signal: otherwise Ctrl-C has no effect while a long poll
+        # is hanging, and launchd gets to send SIGKILL first. Kept
+        # separate from wait so an interactive console can hold its own
+        # input loop while the bot runs alongside.
+        def start
+          @running = true
+          @stopped = Thread::Queue.new
+          @poller = Thread.new { poll_loop }
+
+          self
+        end
+
+        # Wait for a stop. Returns false if the reason was a second
+        # instance on the same token.
+        def wait
+          reason = @stopped.pop
+
+          @running = false
+          @poller&.kill
+          log(reason) if reason.is_a?(String)
+
+          reason != :conflict
+        end
+
+        def run
+          start
+          trap_signals
+          log("bot started, listening for updates")
+          wait
+        end
+
+        def stop = @stopped&.push(nil)
+
+        def running? = @running
+
+        private
+
+        def poll_loop
+          failures = 0
+
+          while @running
+            begin
+              poll_once
+              failures = 0
+            rescue Api::Conflict => e
+              # Another process is reading updates — looping further is
+              # pointless, exit with a clear explanation.
+              log("stopping: #{e.message}. Is another agents_control running?")
+              @stopped.push(:conflict)
+              return
+            rescue Api::TooManyRequests => e
+              pause(e.retry_after.positive? ? e.retry_after : 5)
+            rescue Api::Unavailable => e
+              failures += 1
+              log("network unavailable (#{e.message}), retrying in #{backoff(failures)}s")
+              pause(backoff(failures))
+            rescue Api::Error => e
+              failures += 1
+              log("API error: #{e.message}")
+              pause(backoff(failures))
+            end
+          end
+        end
+
+        def poll_once
+          updates = @api.get_updates(offset: offset, timeout: @config.get("telegram.poll_timeout", 30))
+
+          updates.each do |update|
+            handle(update)
+            self.offset = update["update_id"] + 1
+          end
+        end
+
+        # The offset advances even after a failed handling attempt: not
+        # advancing it would mean replaying the same message forever.
+        # Network errors don't reach here — they bubble up out of
+        # get_updates before the loop.
+        def handle(update)
+          @router.handle(update)
+        rescue Api::Unavailable
+          raise
+        rescue StandardError => e
+          log("failed to handle update #{update['update_id']}: #{e.class}: #{e.message}")
+        end
+
+        def offset = @store.get(OFFSET_KEY)
+
+        # The offset outlives buttons: it has to survive both a restart
+        # and an overnight idle period, or the bot would replay old commands.
+        def offset=(value)
+          @store.put(value, ttl: 86_400 * 30, key: OFFSET_KEY)
+        end
+
+        def backoff(failures) = BACKOFF[[failures - 1, BACKOFF.size - 1].min]
+
+        # Sleep in short slices so Ctrl-C doesn't have to wait out the full pause.
+        # Not named wait — that's the name of the public stop-waiting method.
+        def pause(seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+
+          while @running && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+            sleep(0.2)
+          end
+        end
+
+        # A signal handler can safely do almost nothing — Queue#push is
+        # one of the few things that's actually safe there.
+        def trap_signals
+          %w[INT TERM].each do |signal|
+            Signal.trap(signal) { @stopped.push("received signal #{signal}, stopping") }
+          end
+        end
+
+        def log(message) = @logger.puts("[#{Time.now.strftime('%H:%M:%S')}] #{message}")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # Telegram as a notification and reply channel.
+      #
+      # Deliberately split from Router: Router parses incoming traffic,
+      # Channel produces outgoing traffic. Both share the same Store,
+      # because a button physically can't carry more than 64 bytes, and
+      # the whole content of an action lives on our side anyway.
+      class Channel < Channels::Base
+        def initialize(api:, store:, config:, registry: nil)
+          @api = api
+          @store = store
+          @config = config
+          @registry = registry
+        end
+
+        def ready? = !chats.empty?
+
+        # Notify, expecting nothing back.
+        def notify(event)
+          return notify_ask_user_question(event) if event.ask_user_question?
+
+          broadcast(headline(event), event: event)
+        end
+
+        # Ask and wait. Blocks the calling thread — and through it, the
+        # agent itself, which is holding the hook's HTTP request open.
+        #
+        # Never called with an AskUserQuestion event: Dispatcher routes
+        # those through notify instead, since their answer never flows
+        # through a hook response in the first place.
+        def ask(event, pending:, timeout:)
+          pending.ask(event, timeout: timeout) do |question_id|
+            broadcast(question_text(event), markup: buttons_for(event, question_id),
+                                            event: event, question_id: question_id)
+          end
+        end
+
+        private
+
+        def registry = @registry ||= Registry.new
+
+        def chats = Array(@config.get("telegram.allowed_chat_ids", []))
+
+        # Headroom for the continuation marker ("↪️ 2/3\n\n"), which is
+        # appended to a chunk after Chunker has already measured its length.
+        MARKER_HEADROOM = 20
+
+        # Buttons and the "message → session" link are attached to every
+        # chunk: a reply can target any of them, not just the last one.
+        def broadcast(text, markup: nil, event: nil, question_id: nil)
+          chunks = Chunker.split(text, limit: Chunker::MAX_MESSAGE - MARKER_HEADROOM)
+          chunks = [""] if chunks.empty?
+
+          chats.each do |chat_id|
+            chunks.each_with_index do |chunk, i|
+              body = "#{continuation_marker(i, chunks.size)}#{chunk}"
+              sent = send_formatted(chat_id, body, i == chunks.size - 1 ? markup : nil)
+              remember(chat_id, sent, event, question_id) if event
+            end
+          rescue Api::Error
+            # One unreachable chat must not affect the rest, and
+            # definitely must not take down the thread holding the agent.
+            next
+          end
+        end
+
+        def continuation_marker(index, total) = index.zero? ? "" : "↪️ #{index + 1}/#{total}\n\n"
+
+        # MarkdownV2 is strict: one incorrectly escaped period and
+        # Telegram rejects the whole send, so there's a fallback to plain
+        # text. Losing a message to a formatting error isn't an option:
+        # on the other end is a thread holding the hook's HTTP request open.
+        def send_formatted(chat_id, text, markup)
+          @api.send_message(chat_id: chat_id, text: Markdown.convert(text),
+                            reply_markup: markup, parse_mode: "MarkdownV2")
+        rescue Api::Error => e
+          raise unless e.message.include?("can't parse entities")
+
+          @api.send_message(chat_id: chat_id, text: text, reply_markup: markup)
+        end
+
+        # The link between a chat message and the session it's about.
+        #
+        # Needed so an agent's message can just be replied to, without
+        # figuring out tab numbers. It outlives the question itself:
+        # replying to an old message still makes sense even after the
+        # agent has stopped waiting.
+        #
+        # TTL is 30 days, not a day: the whole point is answering not
+        # right away but whenever convenient, and an old message has to stay addressable.
+        REPLY_TARGET_TTL = 30 * 86_400
+
+        def remember(chat_id, sent, event, question_id)
+          id = sent.is_a?(Hash) ? sent["message_id"] : nil
+          return unless id
+
+          @store.put({ "session_id" => event.session_id, "question_id" => question_id,
+                       "cwd" => event.cwd, "label" => event.label },
+                     ttl: REPLY_TARGET_TTL, key: "reply:#{chat_id}:#{id}")
+        end
+
+        # A short session tag in the header. Needed so that in a chat
+        # with several agents it's clear which one a message belongs to
+        # — especially when they work in the same directory and the
+        # label is identical.
+        def tag(event) = "##{event.session_id.to_s.delete('-')[0, 4]}"
+
+        def headline(event)
+          case event.kind
+          when :error then "🔴 #{event.label} #{tag(event)}\n#{event.text}"
+          when :finished then "✅ #{event.label} #{tag(event)} — done"
+          else "🔔 #{event.label} #{tag(event)}\n#{event.summary}"
+          end
+        end
+
+        # The reply hint lives right in the message: nobody's going to
+        # look it up in the help text.
+        def question_text(event)
+          head = case event.kind
+                 when :needs_permission
+                   "🔐 #{event.label} #{tag(event)} needs permission\n\n`#{event.summary}`"
+                 else
+                   "❓ #{event.label} #{tag(event)} is waiting for a reply\n\n#{event.text.to_s}"
+                 end
+
+          "#{head}\n\n↩️ reply to this message to write to the agent"
+        end
+
+        def buttons_for(event, question_id)
+          rows = action_rows(event, question_id)
+          rows << [context_button(event, question_id)]
+
+          { inline_keyboard: rows }
+        end
+
+        def action_rows(event, question_id)
+          event.kind == :needs_permission ? permission_rows(question_id) : input_rows(question_id)
+        end
+
+        def permission_rows(question_id)
+          [
+            [answer_button("✅ Allow", question_id, kind: :allow),
+             answer_button("❌ Deny", question_id, kind: :deny)],
+            [answer_button("✅ Allow and don't ask again", question_id,
+                           kind: :allow, remember: true)]
+          ]
+        end
+
+        def input_rows(question_id)
+          [
+            [answer_button("▶️ Continue", question_id, kind: :text, text: "Continue."),
+             answer_button("⏹ Stop", question_id, kind: :text, text: "Stop and wait for me.")],
+            [{ text: "✍️ Answer in my own words",
+               callback_data: @store.put({ "action" => "compose", "question_id" => question_id },
+                                         ttl: ttl) }]
+          ]
+        end
+
+        # Show the tail of the conversation — for when a single line
+        # doesn't make it clear what's going on. Context shouldn't be
+        # dumped by default: it's a tool for when in doubt, not a
+        # mandatory part of every notification.
+        def context_button(event, _question_id)
+          {
+            text: "📄 context",
+            callback_data: @store.put({ "action" => "transcript",
+                                        "path" => event.transcript_path,
+                                        "label" => event.label }, ttl: ttl)
+          }
+        end
+
+        def answer_button(text, question_id, kind:, remember: false, text_value: nil, **extra)
+          payload = {
+            "action" => "answer",
+            "question_id" => question_id,
+            "reply" => { "kind" => kind.to_s, "remember" => remember,
+                         "text" => extra[:text] || text_value }
+          }
+
+          { text: text, callback_data: @store.put(payload, ttl: ttl) }
+        end
+
+        def ttl = @config.get("answers.reply_timeout", 600) + 300
+
+        # ── AskUserQuestion ────────────────────────────────────────────
+
+        # This never blocks the hook and never carries a question_id:
+        # the answer doesn't come back as a hook decision, it gets typed
+        # straight into the terminal — by a button tap (ask_question_choice,
+        # handled in Router) or by replying with free text (already
+        # routed there by Router#type_into_session, since there's no
+        # pending question tied to this message for it to be mistaken for).
+        def notify_ask_user_question(event)
+          text = "❓ #{event.label} #{tag(event)}\n\n```\n#{event.summary}\n```\n\n" \
+                 "↩️ reply to this message to answer in your own words"
+
+          rows = option_rows(event)
+          rows << [context_button(event, nil)]
+
+          broadcast(text, markup: { inline_keyboard: rows }, event: event)
+        end
+
+        # Only offered when there's exactly one question and exactly one
+        # matching terminal session for its cwd. With more than one
+        # question we don't know whether the terminal expects them
+        # answered one at a time or needs a final submit; with an
+        # ambiguous cwd we don't know which pane to type into. Both
+        # cases fall back to no option buttons — replying still works either way.
+        def option_rows(event)
+          questions = Array(event.tool_input.is_a?(Hash) ? event.tool_input["questions"] : nil)
+          return [] unless questions.size == 1
+
+          session = resolve_session(event)
+          return [] unless session
+
+          option_buttons(session, questions.first)
+        end
+
+        def resolve_session(event)
+          matches = registry.refresh.agents.select { |s| s.cwd == event.cwd && !s.terminalless? }
+          matches.size == 1 ? matches.first : nil
+        end
+
+        # Options that read as an open-ended "type your own answer"
+        # invitation rather than a concrete choice get skipped here —
+        # tapping a button for one would be meaningless, since there's
+        # nothing to type into the terminal on the user's behalf.
+        # Replying with free text already covers this case regardless.
+        OPEN_ENDED_OPTION = /\b(other|something else|none of (?:these|the above)|custom|
+                              explain|describe|my own|not (?:listed|here))\b/xi
+
+        def option_buttons(session, question)
+          Array(question["options"]).each_with_index.filter_map do |option, index|
+            next if open_ended?(option)
+
+            [{ text: "#{index + 1}. #{option['label']}"[0, 60],
+               callback_data: @store.put({ "action" => "ask_question_choice",
+                                           "session_id" => session.id, "choice" => index + 1 },
+                                         ttl: ttl) }]
+          end
+        end
+
+        def open_ended?(option) = "#{option['label']} #{option['description']}".match?(OPEN_ENDED_OPTION)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # Splits long text into multiple messages instead of clipping the
+      # tail or the head — an agent's response is never allowed to be cut short.
+      #
+      # Telegram's real limit is 4096 UTF-16 code units in the `text`
+      # field AFTER entity parsing (core.telegram.org/bots/api#sendmessage,
+      # the unit is confirmed at core.telegram.org/api/entities). That's
+      # neither UTF-8 bytes nor `String#length` (codepoint count): a
+      # non-Latin character is 2 bytes in UTF-8 but 1 unit in UTF-16, so a
+      # byte-based estimate is up to twice as conservative as necessary
+      # for any non-ASCII text.
+      module Chunker
+        MAX_MESSAGE = 4096
+
+        module_function
+
+        def utf16_length(text) = text.to_s.encode(Encoding::UTF_16LE).bytesize / 2
+
+        # The RAW text has to be cut, not text already converted to
+        # MarkdownV2: a cut inside an escaping pair or a code block would
+        # make Telegram reject the whole chunk's parsing. So the chunk
+        # boundary is chosen on the raw lines, but measured against the
+        # final, converted length — exactly what the API will see.
+        def split(text, limit: MAX_MESSAGE)
+          lines = text.to_s.each_line.flat_map { |line| fit_line(line, limit) }
+          pack(lines, limit)
+        end
+
+        # A single line longer than the limit on its own (minified JSON
+        # with no line breaks, say) leaves no line boundary to cut at, so
+        # it's cut by character with a 2x safety margin: MarkdownV2
+        # escaping adds at most one backslash per character, so it can
+        # never more than double the text's length.
+        def fit_line(line, limit)
+          return [line] if utf16_length(line) <= limit
+
+          line.chars.each_slice(limit / 2).map(&:join)
+        end
+
+        def pack(pieces, limit)
+          chunks = []
+          current = +""
+
+          pieces.each do |piece|
+            candidate = current + piece
+            if !current.empty? && utf16_length(Markdown.convert(candidate)) > limit
+              chunks << current
+              current = piece
+            else
+              current = candidate
+            end
+          end
+          chunks << current unless current.empty?
+
+          chunks
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # Building inline keyboards and rendering lists.
+      #
+      # The key Bot API constraint: a button's `callback_data` can't
+      # exceed **64 bytes**. An iTerm2 session UUID alone (36 characters,
+      # plus an action, plus separators) already cuts it close, let alone
+      # a path or a command.
+      #
+      # So a button carries only a short key from Store, and the actual
+      # action lives on the daemon's side. Side benefit: the key is
+      # one-shot, and pressing the same button twice does nothing the
+      # second time.
+      class Keyboards
+        # How long a button lives. It has to survive a quick trip out,
+        # but not hang around forever: a stale message shouldn't stay a
+        # working remote control.
+        ACTION_TTL = 3600
+
+        def initialize(store:)
+          @store = store
+        end
+
+        # Buttons under a single session's card.
+        def session_actions(session)
+          rows = [[
+            button("🎯 focus", action: "focus", session: session),
+            button("👁 screen", action: "screen", session: session)
+          ]]
+
+          # Closing a tab goes through confirmation: a mistap on a phone is too easy.
+          rows << [button("✖️ close", action: "close_confirm", session: session)] unless session.terminalless?
+
+          { inline_keyboard: rows }
+        end
+
+        def confirm(action, session, label: "Yes, close it")
+          {
+            inline_keyboard: [[
+              button("⚠️ #{label}", action: action, session: session),
+              button("cancel", action: "cancel", session: session)
+            ]]
+          }
+        end
+
+        def list_actions
+          { inline_keyboard: [[
+            { text: "🤖 agents", callback_data: put(action: "list_agents") },
+            { text: "📋 all tabs", callback_data: put(action: "list_tabs") }
+          ]] }
+        end
+
+        # Buttons under /start and /help — the full command list isn't
+        # always visible in the Telegram UI (the menu button is easy to
+        # miss among everything else), so this keeps it available at any
+        # moment right in the message.
+        def main_menu
+          { inline_keyboard: [
+            [{ text: "🤖 agents", callback_data: put(action: "list_agents") },
+             { text: "📋 all tabs", callback_data: put(action: "list_tabs") }],
+            [{ text: "📊 status", callback_data: put(action: "status") },
+             { text: "⚙️ settings", callback_data: put(action: "show_settings") }]
+          ] }
+        end
+
+        # A list with short numbers: commands like `/run 2 ls` address
+        # sessions by them later.
+        #
+        # Numbers are assigned against the full session list (universe),
+        # not the displayed subset — "All tabs" and "Agents" both number
+        # against the same universe, so a session keeps the same number
+        # in either view as long as the set of tabs hasn't changed. An
+        # /run with a remembered number must always hit the session the
+        # human actually saw, never a different one that happened to
+        # land on the same row in a shorter, filtered list.
+        def render_list(sessions, chat_id:, title:, universe: sessions)
+          numbers = numbered(universe)
+          @store.put(numbers.invert, ttl: ACTION_TTL, key: index_key(chat_id))
+
+          lines = sessions.map do |session|
+            "#{numbers[session.id].to_s.rjust(2)}. #{marker(session)} #{describe(session)}"
+          end
+
+          ([title, ""] + lines).join("\n")
+        end
+
+        def session_for(chat_id, number)
+          map = @store.get(index_key(chat_id)) || {}
+
+          map[number.to_s]
+        end
+
+        private
+
+        def index_key(chat_id) = "index:#{chat_id}"
+
+        # session.id => "1".."N", in the order of the full session list.
+        def numbered(universe)
+          universe.each_with_index.to_h { |session, position| [session.id, (position + 1).to_s] }
+        end
+
+        def button(text, action:, session:)
+          { text: text, callback_data: put(action: action, session_id: session.id) }
+        end
+
+        def put(payload) = @store.put(payload, ttl: ACTION_TTL)
+
+        def marker(session)
+          return "⏳" if session.processing?
+          return "🖥" if session.terminalless?
+          return "▸" if session.at_shell_prompt?
+
+          "·"
+        end
+
+        def describe(session)
+          parts = [session.agent ? session.agent.to_s : (session.foreground_command || "—")]
+          parts << session.label
+          parts << (session.terminalless? ? "vscode" : session.tty.to_s.sub(%r{\A/dev/}, ""))
+
+          parts.join(" · ")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module AgentsControl
+  module Channels
+    module Telegram
+      # Turns plain GFM-like text — the shape Claude Code writes — into
+      # Telegram MarkdownV2.
+      #
+      # Escaping rules:
+      #
+      #   - outside code, the 18 characters `_*[]()~`>#+-=|{}.!` must be
+      #     backslash-escaped, or sendMessage answers with a 400: Bad
+      #     Request: can't parse entities: Character '.' is reserved…
+      #   - inside `inline code` and ```blocks``` those same characters
+      #     must NOT be escaped — there they're just text;
+      #   - a ```lang tag before a block is accepted and syntax-highlighted.
+      #
+      # This is Telegram's strict mode: one incorrectly escaped period
+      # and the whole message fails to send. So the converter is written
+      # conservatively (it never touches code, and escapes prose in
+      # full), and the Api side still carries its own separate
+      # safety net — falling back to plain text if Telegram rejects it anyway.
+      module Markdown
+        # Escaped outside code. Order matters: `\` goes first, or the
+        # escaping slashes would themselves get escaped again.
+        RESERVED = %w[\\ _ * [ ] ( ) ~ ` > # + - = | { } . !].freeze
+
+        # Code is what must never be touched: even the opening triple
+        # quote can carry a language tag (```ruby) that has to be kept
+        # literal, not escaped.
+        CODE = /(```.*?```|`[^`\n]+`)/m
+
+        # One of the few GFM constructs worth preserving as actual
+        # formatting rather than turning into escaped asterisks: Claude
+        # Code often puts **important** text in headings and summaries.
+        BOLD = /\*\*(.+?)\*\*/m
+
+        module_function
+
+        def convert(text)
+          text.to_s.split(CODE).each_with_index.map do |chunk, index|
+            index.odd? ? chunk : escape_prose(chunk)
+          end.join
+        end
+
+        def escape_prose(text)
+          text.split(BOLD).each_with_index.map do |chunk, index|
+            index.odd? ? "*#{escape_literal(chunk)}*" : escape_literal(chunk)
+          end.join
+        end
+
+        def escape_literal(text)
+          pattern = Regexp.union(RESERVED)
+          text.gsub(pattern) { |char| "\\#{char}" }
+        end
+      end
+    end
+  end
+end