agents_control 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7396050fbeeb69af3c8fd481608facce44bce68072dc043f03fa0bc34138de5b
-  data.tar.gz: '05597674bc05d4bb1142e1295c264f737caf7be5afee724616ec4e0673db3870'
+  metadata.gz: 5ca83918e01b4dc98c7b72f17da5cd31d859d863d61614f7eee74dd01e62ecb2
+  data.tar.gz: d50f30441533aded38f243800dda29a884fd01fda135506dee034115eeb63e7a
 SHA512:
-  metadata.gz: efe615074ece6b5898eecaaa66fdc882c46d2b6a74c715b18768b347ab3af3ef180774930dc46d5648461a006b96059bd265c67f676e45ed2eadcc0017bc6ee2
-  data.tar.gz: 6137a2654888b576860d1a8463e5aff520ace959c687974e6bd20e3425ba40f98673391517c30dc7d1c54a58bbbbad070aa2253891d6553458f774354c9c6543
+  metadata.gz: 9dd870ff93dd579dd1bbbc7cffd7e9f62d7a5d25ba79d2f69adb6018ac1ae8061614b5e1d09db5bc817d65f8f6a33fc7557b8a6a035245d640e92373bcdc598d
+  data.tar.gz: 71c5a463b794b2196fa3023a0a703ab6cd02da596f2b1f003ea1365db96f9a67e8d3ab3e1ddc51bdd470d76217395907565a2d53ef65dccf6fc0b411c04dee0a

data/README.md

@@ -1,5 +1,7 @@
 # agents_control
 
+[![Gem Version](https://img.shields.io/gem/v/agents_control)](https://rubygems.org/gems/agents_control)
+
 A remote for iTerm2 and its AI agents (Claude Code, Codex) from Telegram:
 tab list, commands, screen, new sessions. For Claude Code — also the
 agent's questions and permission requests: it stops, buttons show up in
@@ -26,15 +28,15 @@ outside: the port only binds to 127.0.0.1, there are no incoming connections.
 On macOS, terminal control (sending commands, reading the screen,
 creating tabs) works through iTerm2 or tmux — Terminal.app isn't
 supported. Notifications about questions and permissions aren't tied to
-a terminal at all: their source is the agent's hooks, which work
+a terminal at all: their source is Claude Code's hooks, which work
 everywhere, including sessions with no terminal (a VS Code session, for
-instance), but for now only for Claude Code.
+instance).
 
 ## Why
 
 You need to run a command in a session, check the screen, or switch to
 a tab, and you're not at the computer — now you can do that from
-Telegram. If the session is Claude Code, there's a bonus too: the agent
+Telegram. If the session is Claude Code, there's a bonus too: it
 stops and waits for an answer — the question and its buttons arrive in
 Telegram, no need to go home just to say "continue."
 
@@ -59,6 +61,12 @@ cd agents_control
 bundle install
 ```
 
+Or as a RubyGem:
+
+```sh
+gem install agents_control
+```
+
 Or straight from Claude Code, as a plugin — the repo doubles as a marketplace:
 
 ```
@@ -69,31 +77,7 @@ Or straight from Claude Code, as a plugin — the repo doubles as a marketplace:
 The plugin doesn't replace the install above — it's just a way to find
 the tool and get install instructions without leaving Claude Code.
 
-## Usage
-
-```sh
-agents_control          # opens the console and stays in the tab
-```
-
-The tool lives in a tab: while it's open, it listens to Telegram and
-receives agent events. Commands inside start with a slash, same as the bot's:
-
-```
-> /sessions          sessions with a live agent
-> /tabs              all terminal tabs
-> /away              intercept agent questions (before stepping out)
-> /settings          settings; /settings away — toggle
-> /doctor            check that everything is in place
-> /quit              quit
-```
-
-State icons: `⏳` working · `▸` at a shell prompt · `🖥` no terminal
-(VS Code) · `·` everything else.
-
-One-off commands exist too — `agents_control sessions`, `doctor`,
-`daemon` — but the normal way to run it is an open console.
-
-### Telegram
+## Telegram
 
 Create a bot with [@BotFather](https://t.me/BotFather) and run the wizard:
 
@@ -113,13 +97,45 @@ Bot commands:
 | `/tabs` | all terminal tabs |
 | `/screen N` | show a tab's screen |
 | `/focus N` | switch to a tab |
-| `/run N command` | run a command in a tab |
+| `/run N command` | run a command in a tab and show the result |
 | `/new [directory]` | create a tab |
 | `/away` | intercept agent questions |
 | `/status` | current status |
 
 The number `N` comes from the last list shown.
 
+Against a plain tab, `/run` treats the command itself as the reference
+point: the shell echoes back whatever's typed, so it looks for that
+exact text on screen and shows from there — sharper than diffing
+screenshots, and it still works even if something else wrote to the
+same tab in between, since it doesn't need the screen from right
+before typing to relate to the screen after at all. A short reply
+("y", "n" mid `git add -p`) isn't a safe anchor on its own — too
+likely to match something unrelated — so those fall back to a
+before/after diff instead, and when even that can't cleanly tell
+what's new, to the current screen outright: seeing the result,
+possibly with a little stale context around it, beats not seeing it
+at all. How much gets captured either way is a `/settings` option
+(`terminal.run_result_lines`, 200 by default) — a command whose output
+runs longer just gets its last N lines, same as the default gets cut
+by a screen that's too tall.
+
+Against an agent, `/run` just confirms the send — an agent isn't a
+shell command that finishes in a couple of seconds, so there's no
+"result" to capture yet by the time it would look. Hooks already own
+telling Telegram when it's actually done or needs something, the same
+as replying to one of its own questions.
+
+The result stays a live target: replying to it — "y", "n", anything —
+types straight into that same pane and shows what came back, so
+something like `git add -p`'s hunk-by-hunk prompts works as an actual
+back-and-forth over Telegram, not a one-shot fire-and-forget.
+
+Both `/run` and `/screen` head their reply with the tab's label and
+tty (`valkyrie · ttys017`) — several tabs can share a label when
+they're open on the same project, and the tty is what actually tells
+them apart.
+
 This list also populates Telegram's own `/` command menu automatically
 — `setup` and every daemon start publish it via the Bot API, no manual
 BotFather step needed. If the menu still shows only `/start` after
@@ -129,15 +145,16 @@ to force it to refresh.
 
 ### Two modes
 
-While you're at the keyboard, intercepting agent questions is
-counterproductive: you'll answer in the terminal faster than you can
-reach for your phone, and a blocked hook keeps the dialog from ever
-appearing on screen. So there are two modes:
+This whole section is about Claude Code specifically — its hooks are
+what makes any of it possible. While you're at the keyboard,
+intercepting its questions is counterproductive: you'll answer in the
+terminal faster than you can reach for your phone, and a blocked hook
+keeps the dialog from ever appearing on screen. So there are two modes:
 
 - **present** (default) — questions are mirrored to Telegram but stay
   in the terminal;
 - **away** (`/away`) — a question arrives with buttons and waits for a
-  reply; the agent stands by until you answer or time runs out.
+  reply; Claude Code stands by until you answer or time runs out.
 
 A question can also be answered by replying directly to the message —
 it goes to the right session, even with several tabs open.
@@ -159,14 +176,14 @@ the wrong place.
 
 A "continue" reply is sent automatically, but tool permissions aren't.
 These are two independent settings on purpose: merged into one, they'd
-produce an agent that approves itself everything while nobody's
-watching. A question that offers a choice ("rewrite it or leave it?")
-is never answered automatically, even if it contains the word "continue."
+let it approve itself everything while nobody's watching. A question
+that offers a choice ("rewrite it or leave it?") is never answered
+automatically, even if it contains the word "continue."
 
 ### Hooks
 
 The daemon connects hooks on start and removes them on stop — otherwise
-the agent prints a warning about an unreachable address in every
+Claude Code prints a warning about an unreachable address in every
 session. If the daemon crashed and the hooks are still there:
 
 ```sh
@@ -177,6 +194,30 @@ agents_control hooks uninstall
 Entries in `~/.claude/settings.json` are tagged, and other settings
 aren't touched: installing and removing return the file to exactly its original shape.
 
+## Usage
+
+```sh
+agents_control          # opens the console and stays in the tab
+```
+
+The tool lives in a tab: while it's open, it listens to Telegram and
+receives agent events. Commands inside start with a slash, same as the bot's:
+
+```
+> /sessions          sessions with a live agent
+> /tabs              all terminal tabs
+> /away              intercept agent questions (before stepping out)
+> /settings          settings; /settings away — toggle
+> /doctor            check that everything is in place
+> /quit              quit
+```
+
+State icons: `⏳` working · `▸` at a shell prompt · `🖥` no terminal
+(VS Code) · `·` everything else.
+
+One-off commands exist too — `agents_control sessions`, `doctor`,
+`daemon` — but the normal way to run it is an open console.
+
 ## Rate-limit anchors
 
 A five-hour window starts at the minute of the first message and
@@ -199,7 +240,7 @@ catches this and suggests `pmset repeat wakeorpoweron`.
 
 ## Watchers
 
-Hooks see the agent's own decisions, but not everything: the CLI's own
+Hooks see Claude Code's own decisions, but not everything: the CLI's own
 local menus (model switch, folder trust) and text on screen (a
 rate-limit message) aren't covered by hooks at all — these events never
 produce a single hook call. Two independent watchers handle them,

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

@@ -20,6 +20,15 @@ module AgentsControl
         # working remote control.
         ACTION_TTL = 3600
 
+        # Numbers, unlike buttons, are typed by hand into later messages
+        # — /run N doesn't stay tied to the message the list came in on,
+        # so it has to survive much longer than a single quick trip out.
+        # A closed session is still handled gracefully regardless of how
+        # long the mapping lives (find just returns nil), so the only
+        # cost of a longer TTL is a number eventually pointing at a tab
+        # that's since closed — a clear, expected error either way.
+        LIST_TTL = 86_400
+
         def initialize(store:)
           @store = store
         end
@@ -78,7 +87,7 @@ module AgentsControl
         # 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))
+          @store.put(numbers.invert, ttl: LIST_TTL, key: index_key(chat_id))
 
           lines = sessions.map do |session|
             "#{numbers[session.id].to_s.rjust(2)}. #{marker(session)} #{describe(session)}"

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

@@ -35,13 +35,14 @@ module AgentsControl
         HELP = (["Commands:", ""] +
                 COMMANDS.map { |name, text, hint| "/#{name}#{hint ? " #{hint}" : ''} — #{text}" }).join("\n")
 
-        def initialize(api:, registry:, store:, config:, keyboards: nil, pending: nil)
+        def initialize(api:, registry:, store:, config:, keyboards: nil, pending: nil, logger: nil)
           @api = api
           @registry = registry
           @store = store
           @config = config
           @keyboards = keyboards || Keyboards.new(store: store)
           @pending = pending
+          @logger = logger
         end
 
         def handle(update)
@@ -95,17 +96,25 @@ module AgentsControl
         end
 
         # First, the exact session by session_id — unambiguous even when
-        # several tabs share one cwd. Matching by cwd is the fallback for
-        # when that tab has already closed.
+        # several tabs share one cwd, and works for any session type:
+        # /run and /screen remember the terminal's own session id, not
+        # an agent's hook id, so this resolves directly whether the
+        # target is an agent or a plain shell tab. Matching by cwd is
+        # the fallback for when that tab has already closed — an agent
+        # match wins there if one exists (the common case: replying to
+        # an agent's own notification), otherwise any matching tab does
+        # (a plain tab mid-interactive-command has no agent to prefer).
         def type_into_session(chat_id, target, text)
           exact = @registry.refresh.find(target["session_id"])
-          return execute(chat_id, exact, text) if exact&.agent? && !exact.terminalless?
+          return execute(chat_id, exact, text, show_result: !exact.agent?) if exact && !exact.terminalless?
 
-          matching = @registry.agents.select { |s| s.cwd == target["cwd"] && !s.terminalless? }
+          candidates = @registry.sessions.select { |s| s.cwd == target["cwd"] && !s.terminalless? }
+          agent_matches = candidates.select(&:agent?)
+          matching = agent_matches.empty? ? candidates : agent_matches
 
           case matching.size
           when 0 then say(chat_id, "#{target['label']} isn't waiting anymore, and I couldn't find the tab.")
-          when 1 then execute(chat_id, matching.first, text)
+          when 1 then execute(chat_id, matching.first, text, show_result: !matching.first.agent?)
           else say(chat_id, "#{target['label']} has several tabs — use /run NUMBER to pick one.")
           end
         end
@@ -188,7 +197,19 @@ module AgentsControl
           with_session(chat_id, number) do |session|
             next say(chat_id, "This session has no terminal — nothing to run there.") if session.terminalless?
 
-            remote?(session) ? confirm_remote(chat_id, session, command) : execute(chat_id, session, command)
+            if remote?(session)
+              confirm_remote(chat_id, session, command)
+            else
+              # An agent isn't a shell command that finishes in a
+              # couple of seconds — it's a real task, and hooks already
+              # own telling Telegram when it's actually done or needs
+              # something. Capturing a "result" a moment after typing
+              # would just catch it mid-thought and fall back to
+              # dumping its whole transcript, which isn't a result at
+              # all — same reasoning as replying to an agent's own
+              # question (type_into_session).
+              execute(chat_id, session, command, show_result: !session.agent?)
+            end
           end
         end
 
@@ -216,13 +237,125 @@ module AgentsControl
         # input: a merged call can fail to send multi-line text at all.
         TYPING_PAUSE = 0.4
 
-        def execute(chat_id, session, command)
+        # How long to wait after the command lands before reading the
+        # screen back. There's no way to know when a command actually
+        # finishes without polling for it, so this is a fixed guess
+        # tuned for the common case (git status, ls, a quick build
+        # check) — long enough for those, short enough not to feel
+        # laggy. A slower command just gets caught mid-flight, same as
+        # looking over someone's shoulder while it's still running;
+        # /screen still shows the up-to-date state a moment later.
+        RUN_SETTLE_PAUSE = 1.2
+
+        def run_result_lines = @config.get("terminal.run_result_lines", 200)
+
+        def execute(chat_id, session, command, show_result: false)
           backend = @registry.backend_for(session)
+          before = show_result ? capture_screen(session, lines: run_result_lines) : nil
 
           ok = backend.send_text(session.id, command, newline: false) &&
                sleep(TYPING_PAUSE).then { backend.send_text(session.id, "", newline: true) }
 
-          say(chat_id, ok ? "Sent to #{session.label}." : "Couldn't send.")
+          return say(chat_id, "Couldn't send.") unless ok
+          return say(chat_id, "Sent to #{session.label}.") unless show_result
+
+          sleep(RUN_SETTLE_PAUSE)
+          show_command_result(chat_id, session, since: before, command: command)
+        end
+
+        # Shows what's new since `since` (the screen right before the
+        # command was typed) rather than an arbitrary tail slice of the
+        # current screen — otherwise a short result could be padded out
+        # with whatever the terminal already had on it a moment ago.
+        def show_command_result(chat_id, session, since:, command:)
+          after = capture_screen(session, lines: run_result_lines)
+          text = new_output_since(after, since, command: command)
+          log("run result: session=#{session.id} before=#{since.to_s.length}b " \
+              "after=#{after.to_s.length}b prefix_match=#{after.to_s.start_with?(since.to_s)} " \
+              "command_anchor=#{command.to_s.strip.length >= MIN_COMMAND_ANCHOR && after.to_s.include?(command.to_s.strip)} " \
+              "result=#{text.to_s.length}b")
+
+          if text && !text.empty?
+            sent = say_chunked(chat_id, "🖥 #{session_descriptor(session)}\n\n", text, code: true)
+            return sent.each { |msg| remember_reply(chat_id, msg, session) }
+          end
+
+          # new_output_since only comes back empty when the capture
+          # itself was empty — a genuinely blank screen. The transcript
+          # fallback below is keyed by cwd, not by this specific session
+          # — several tabs (or VS Code sessions) can sit on the exact
+          # same project directory, and it'll pick whichever of them
+          # wrote to its transcript most recently. For a plain shell tab
+          # that's cross-session noise: a result from a totally
+          # different session shown as if it were this one's. Only
+          # worth the ambiguity when there's genuinely nothing else to
+          # offer — an agent (its own conversation is at least
+          # thematically the right session) or a session with no
+          # terminal at all (nothing else exists to show).
+          return say(chat_id, "The screen is empty.") unless session.agent? || session.terminalless?
+
+          show_agent_context(chat_id, session)
+        end
+
+        # A one- or two-character reply ("y", "n", "q" mid `git add -p`)
+        # turns up constant false matches in ordinary output — not a
+        # safe anchor at all. Anything shorter than this falls straight
+        # through to the prefix/marker fallback instead.
+        MIN_COMMAND_ANCHOR = 3
+
+        # Returns whatever showed up in `after` beyond `since`.
+        #
+        # The command itself is the sharpest anchor available: the
+        # shell echoes it back verbatim, and unlike the prompt (which
+        # looks identical after every command) the command text is
+        # specific to this exact invocation. rindex, not index — the
+        # *last* occurrence is the one nearest to now, i.e. this send,
+        # not some earlier time the same command happened to run. This
+        # is also what makes it more reliable than prefix/marker
+        # matching when the tab is shared with a human actively typing
+        # in it: `since` doesn't have to relate to `after` at all for
+        # this to work, since it just locates the command's own echo
+        # directly.
+        #
+        # An exact prefix match is the fallback: unambiguous whenever
+        # nothing scrolled out of the capture window between the two
+        # snapshots, since `after` is then simply `since` with new
+        # content appended and there's nothing to search for at all.
+        #
+        # Marker search (since's own last two lines, most recent
+        # occurrence) is the last resort, for whatever's too short to
+        # anchor on and doesn't fit as a literal prefix either.
+        #
+        # No matter which method resolves it, an anchor is never
+        # allowed to produce silence: if it lands on nothing (the
+        # reference point itself, unchanged, or a boundary right at the
+        # tail), what's actually on screen right now is still real and
+        # still worth showing — the whole point of /run is seeing the
+        # result, and reporting "no new output" when there's visibly a
+        # result sitting right there is a worse failure than
+        # occasionally including a line of stale context.
+        def new_output_since(after, since, command: nil)
+          after_s = after.to_s
+          since_s = since.to_s
+
+          needle = command.to_s.strip
+          if needle.length >= MIN_COMMAND_ANCHOR
+            index = after_s.rindex(needle)
+            return after_s[index..].to_s if index
+          end
+
+          return after_s if since_s.strip.empty?
+
+          tail = if after_s.start_with?(since_s)
+                   after_s[since_s.length..]
+                 else
+                   marker = since_s.rstrip.lines.last(2).join
+                   index = marker.strip.empty? ? nil : after_s.rindex(marker)
+                   index ? after_s[(index + marker.length)..] : nil
+                 end
+
+          tail = tail.to_s.sub(/\A\n+/, "")
+          tail.empty? ? after_s : tail
         end
 
         def create_tab(chat_id, directory)
@@ -389,7 +522,7 @@ module AgentsControl
           case payload["action"]
           when "focus" then focus_session(chat_id, session)
           when "screen" then show_screen(chat_id, session)
-          when "run" then execute(chat_id, session, payload["text"])
+          when "run" then execute(chat_id, session, payload["text"], show_result: !session.agent?)
           when "close_confirm" then say(chat_id, "Close #{session.label}?",
                                         markup: @keyboards.confirm("close", session))
           when "close" then close_session(chat_id, session)
@@ -406,23 +539,35 @@ module AgentsControl
         # just finished lines from the transcript. The transcript stays
         # the fallback for terminalless sessions and for a freshly
         # created tab's blank screen.
-        def show_screen(chat_id, session)
-          text = capture_screen(session)
+        def show_screen(chat_id, session, lines: @config.get("terminal.context_lines", 80))
+          text = capture_screen(session, lines: lines)
           if text && !text.empty?
-            sent = say_chunked(chat_id, "", text, code: true)
+            sent = say_chunked(chat_id, "🖥 #{session_descriptor(session)}\n\n", text, code: true)
             return sent.each { |msg| remember_reply(chat_id, msg, session) }
           end
 
+          return say(chat_id, "The screen is empty.") unless session.agent? || session.terminalless?
+
           show_agent_context(chat_id, session)
         end
 
-        def capture_screen(session)
-          @registry.backend_for(session).capture(session.id,
-                                                  lines: @config.get("terminal.context_lines", 80))
+        def capture_screen(session, lines: @config.get("terminal.context_lines", 80))
+          @registry.backend_for(session).capture(session.id, lines: lines)
         rescue Terminals::Unsupported
           nil
         end
 
+        # The label alone isn't always enough to tell tabs apart — several
+        # can share the same project directory and so the same label. The
+        # tty is what actually distinguishes them, and it's the same
+        # identifier a terminal's own window/tab chrome would show.
+        def session_descriptor(session)
+          return session.label if session.terminalless?
+
+          tty = session.tty.to_s.sub(%r{\A/dev/}, "")
+          tty.empty? ? session.label : "#{session.label} · #{tty}"
+        end
+
         def show_agent_context(chat_id, session)
           transcript = Transcript.for_cwd(session.cwd, root: transcript_root)
 
@@ -476,6 +621,10 @@ module AgentsControl
 
           @api.send_message(chat_id: chat_id, text: text, reply_markup: markup)
         end
+
+        def log(message)
+          @logger&.puts("[#{Time.now.strftime('%H:%M:%S')}] #{message}")
+        end
       end
     end
   end

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

@@ -30,7 +30,9 @@ module AgentsControl
           { key: "answers.reply_timeout", label: "Reply timeout",
             values: [300, 600, 900, 1800, 3600], unit: "s", default: 900 },
           { key: "terminal.context_lines", label: "Context lines",
-            values: [40, 80, 200, 500], unit: "", default: 80 }
+            values: [40, 80, 200, 500], unit: "", default: 80 },
+          { key: "terminal.run_result_lines", label: "Command result lines",
+            values: [100, 200, 500, 1000], unit: "", default: 200 }
         ].freeze
 
         def initialize(store:, config:)

data/lib/agents_control/daemon.rb

@@ -234,7 +234,7 @@ module AgentsControl
     def start_bot
       router = Channels::Telegram::Router.new(
         api: api, registry: Registry.new, store: @store,
-        config: @config, pending: pending
+        config: @config, pending: pending, logger: @logger
       )
 
       @bot = Channels::Telegram::Bot.new(api: api, router: router, store: @store,

data/lib/agents_control/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agents_control
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Sapar Kurmanov
@@ -24,8 +24,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 description: |
-  A daemon that catches the moments a terminal AI agent stops and waits
-  on a human, and relays them to Telegram — with the question's text and
+  A daemon that catches the moments Claude Code stops and waits on a
+  human, and relays them to Telegram — with the question's text and
   reply buttons. Plus a remote for the terminal itself: list tabs, create
   them, send commands.
 executables:
@@ -81,7 +81,12 @@ files:
 homepage: https://github.com/saparjohnick/agents_control
 licenses:
 - Apache-2.0
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/saparjohnick/agents_control
+  bug_tracker_uri: https://github.com/saparjohnick/agents_control/issues
+  documentation_uri: https://github.com/saparjohnick/agents_control/blob/main/README.md
+  changelog_uri: https://github.com/saparjohnick/agents_control/releases
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -98,5 +103,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Control terminal AI agents from Telegram
+summary: Control terminal AI agents (Claude Code, Codex) from Telegram
 test_files: []