agents_control 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ca83918e01b4dc98c7b72f17da5cd31d859d863d61614f7eee74dd01e62ecb2
-  data.tar.gz: d50f30441533aded38f243800dda29a884fd01fda135506dee034115eeb63e7a
+  metadata.gz: 7cbdfdaec647d99052be4572b93c02e8a1ba8f1169219a85c3abebb1ce1d794b
+  data.tar.gz: 5d486d2543a88f451eec31e8261ddf8fafb8170446f09f1f13596b07e639f19a
 SHA512:
-  metadata.gz: 9dd870ff93dd579dd1bbbc7cffd7e9f62d7a5d25ba79d2f69adb6018ac1ae8061614b5e1d09db5bc817d65f8f6a33fc7557b8a6a035245d640e92373bcdc598d
-  data.tar.gz: 71c5a463b794b2196fa3023a0a703ab6cd02da596f2b1f003ea1365db96f9a67e8d3ab3e1ddc51bdd470d76217395907565a2d53ef65dccf6fc0b411c04dee0a
+  metadata.gz: e47eca628d62039dd339691b713ad2b123f5fe9205b0394f623fe51806cbb0711b3ee93f5708548855049d6ebf3631776276e8f21b3b977e776392f7bb842be1
+  data.tar.gz: cdec6b32aade79e9b165c72ac9fc121116b1a90ab1c7e16066737561653c9e5090ab87b593e55da04ca78dbe02099a4903bc626b008fe16170a448a65ab8ecf3

data/README.md

@@ -89,6 +89,14 @@ agents_control           # after that, just open the console
 The wizard catches your `chat_id` from your own message and adds it to
 the allowed list — no need to type in a long number by hand.
 
+At the end it offers to set a **passphrase for destructive commands**.
+A few commands are held back when they arrive from Telegram — `rm -rf ~`,
+`mkfs`, `dd` writing to a raw device, a fork bomb. With a passphrase set
+you're asked to type it before one of those is sent; without one they
+ask for a tap on a button instead. It's optional and skippable, and
+`agents_control passphrase set` adds one later. See
+[Destructive commands ask first](#destructive-commands-ask-first).
+
 Bot commands:
 
 | Command | What it does |
@@ -126,6 +134,14 @@ shell command that finishes in a couple of seconds, so there's no
 telling Telegram when it's actually done or needs something, the same
 as replying to one of its own questions.
 
+A tab stuck inside `less`, `vim`, a REPL, or anything else that reads
+keystrokes as its own input rather than a line to submit gets a
+confirmation first instead of a blind send — the text would go to
+whatever's actually running there, not run as a command. A pager not
+on that recognized list still gets caught: a bare `:` as the entire
+last line is the one thing practically every pager agrees on for
+"waiting on you," and a real shell prompt never looks like that.
+
 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
@@ -143,6 +159,50 @@ that, it's Telegram's client caching the old list, not a missing step
 on your end: close and reopen the chat, or restart the Telegram app,
 to force it to refresh.
 
+### Sending files in
+
+Photos, videos, voice notes and documents — logs, a CSV, a spreadsheet,
+a screenshot — can be sent to the bot and handed to a session. The file
+is downloaded to `~/.local/state/agents_control/inbox/` and what reaches
+the pane is its **local path**, so the agent opens it the way it opens
+anything else:
+
+```
+you  › [screenshot.png]  caption: /run 3 why does this render wrong?
+
+pane › why does this render wrong? /Users/you/.local/state/agents_control/inbox/20260907-171530-screenshot.png
+```
+
+Three ways to say where it goes:
+
+| | |
+|---|---|
+| caption `/run N …` | that tab, with the rest of the caption as the message |
+| reply with a file to a session's own message | that session |
+| neither | saved, and the path comes back so you can use it |
+
+Guessing a target for a file is how it ends up pasted into the wrong
+project, so with nothing to go on it isn't guessed. However it gets
+there, a file's path is checked and escaped like anything else typed
+into a pane — a caption is a way of saying `/run`, so it's guarded like
+one.
+
+**A path and never a link, deliberately.** Telegram serves file bytes
+from `https://api.telegram.org/file/bot<TOKEN>/…` — the download URL
+*is* the bot token. Pasting that into a pane would put the token in the
+terminal, in the agent's context, and in the shell history, and a
+leaked token is remote code execution on this machine. The URL is built
+inside the API client and never leaves it.
+
+The name comes from whoever sent the file, so it doesn't get to be a
+path: no separators, no `..`, no leading dot, and cut to a length any
+filesystem takes. Files are written `0600` inside a `0700` directory —
+logs and screenshots are exactly what carries a token or a customer's
+name through in passing — and swept after `telegram.inbox_keep_days`
+(14 by default), since an agent reads them within minutes and the
+directory would otherwise only grow. Telegram caps what a bot can
+download at 20MB; anything larger is refused before the round trip.
+
 ### Two modes
 
 This whole section is about Claude Code specifically — its hooks are
@@ -249,8 +309,10 @@ the full `Registry` — they see bare iTerm2 tabs and tmux panes alike.
 
 **CLI menus** (`terminal.watch_menus`, on by default, polled every 20
 seconds — `terminal.menu_poll_interval`). Notices the "❯ 1. … / 2. …"
-pattern Claude Code uses to draw any choice, and sends it to Telegram
-as buttons — pressing one types the option's number straight into the pane.
+pattern Claude Code (or a skill's own wizard) uses to draw any choice —
+options can carry a couple of lines of description each, or a divider
+before a trailing one — and sends it to Telegram as buttons; pressing
+one types the option's number straight into the pane.
 
 **Limit reset** (`answers.auto_resume_after_limit`, on by default,
 polled once a minute — `terminal.rate_limit_poll_interval`). Notices a
@@ -308,6 +370,73 @@ This tool lets you run commands on your machine from Telegram. That comes with s
 - Auto-replying "continue" is on by default; automatic tool approval is
   off. These are separate settings on purpose.
 
+### Destructive commands ask first
+
+A few commands are held back when they arrive from Telegram: a
+recursive force delete aimed at `/` or `$HOME`, a fork bomb, `mkfs`,
+`dd` writing to a raw device. Each comes back saying what it actually
+does — "this recursively deletes `~` — there is no undo" — rather than
+which rule caught it. `rm -rf /tmp/build` goes straight through, as it
+should: the list is a seatbelt for a thumb on the wrong line in a tab
+listing, not a policy engine, and it stays short enough to hold in
+your head.
+
+By default that's a confirmation button, and the first times one of
+these turns up the bot offers a passphrase alongside it — that's the
+one moment the reason for it is on screen. **Don't ask again** makes
+the refusal stick; `/settings` keeps the offer reachable either way.
+The bot also says so once, on the first daemon start with no
+passphrase set, because someone who never types a destructive command
+themselves would otherwise never learn the option exists — and the
+first one that does turn up might not be theirs.
+
+A passphrase can be set from the chat itself (two entries, both
+deleted) or with `agents_control passphrase set` at the machine. Set
+from the chat, it guards against whoever gets to that chat *later*,
+not whoever has it right now — the bot says so when it saves. That's
+the honest trade: the alternative is that most people never set one,
+since you only think about this while away from the keyboard.
+
+Set a passphrase — during `agents_control setup`, from the bot, or any
+time after — and the button becomes a question instead:
+
+```sh
+agents_control passphrase set      # entered without echo, stored in the Keychain
+```
+
+```
+you  › /run 3 rm -rf ~
+
+bot  › this recursively deletes ~ — there is no undo
+
+         rm -rf ~
+
+       Reply to this message with the passphrase to send it to
+       mobile-app. Anything else cancels.
+
+you  › ················            ← deleted from the chat once read
+```
+
+A tap answers "did you mean this?" — which covers the wrong tab
+number. A passphrase answers "are you you?", which is the other half:
+an unlocked phone in someone else's hand taps just as well as its
+owner does. It replaces the button rather than joining it — two steps
+for one decision is how people learn to hurry through both — and the
+message carrying it is deleted from the chat the moment it's read,
+right or wrong, since a chat history syncs to every device the account
+is signed in on.
+
+The passphrase is stored derived (PBKDF2-HMAC-SHA256, salted) next to
+the bot token, and is never accepted as a command-line argument.
+`agents_control passphrase clear` goes back to the button.
+
+## Changes between versions
+
+[CHANGELOG.md](CHANGELOG.md) — what changed and why, newest first. Read
+the current entry before upgrading if you rely on `/run`: while the
+major is 0, a minor bump may change behaviour, and the entry says so
+where it does.
+
 ## Development
 
 ```sh

data/lib/agents_control/agents/claude_code.rb

@@ -31,6 +31,21 @@ module AgentsControl
 
         def binaries = %w[claude]
 
+        # Our own Stop entry, found by the marker rather than by
+        # position. merge_hook appends ours last, so index 0 is someone
+        # else's the moment the user has a Stop hook of their own —
+        # which is common, and which made the startup self-check probe a
+        # stranger's endpoint with a stranger's credentials.
+        def own_hook(path = settings_path)
+          return unless File.exist?(path)
+
+          groups = JSON.parse(File.read(path)).dig("hooks", "Stop")
+          Array(groups).flat_map { |group| Array(group["hooks"]) }
+                       .find { |hook| hook["_agents_control"] }
+        rescue JSON::ParserError
+          nil
+        end
+
         def handles?(payload)
           payload.is_a?(Hash) && payload.key?("hook_event_name")
         end

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

@@ -26,6 +26,10 @@ module AgentsControl
         # noticeably shorter than that.
         CALL_TIMEOUT = 8
 
+        # A phone on a train uploading a screen recording is a slow
+        # request that's still working, not a stuck one.
+        DOWNLOAD_TIMEOUT = 120
+
         Error = Class.new(AgentsControl::Error)
 
         # Another process is already reading updates with this same
@@ -66,6 +70,26 @@ module AgentsControl
           )
         end
 
+        # Two steps by design on Telegram's side: getFile resolves a
+        # file_id to a path that's valid for about an hour, and the
+        # bytes come from a different host prefix.
+        def file_path_for(file_id)
+          call("getFile", { file_id: file_id })["file_path"]
+        end
+
+        # Streams to disk rather than through memory: a 20MB video read
+        # into a String would sit in the daemon's heap for as long as
+        # Ruby felt like keeping it.
+        #
+        # The download URL carries the token in its path, which is why
+        # this method builds it and nothing else ever sees it — no
+        # caller, no log line, no message back to the chat.
+        def download(file_path, to:, max_bytes: nil)
+          @http.get_to_file(file_url_for(file_path), to, read_timeout: DOWNLOAD_TIMEOUT, max_bytes: max_bytes)
+        rescue Http::NetworkError => e
+          raise Unavailable, redact(e.message)
+        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,
@@ -82,6 +106,16 @@ module AgentsControl
 
         # The command menu in the Telegram UI: a button next to the
         # input field instead of hunting through the chat for a list.
+        # Best-effort on purpose: a passphrase typed into a chat is
+        # deleted the moment it's read, and a bot that can't delete it
+        # (too old, permissions) must still not leave the command it
+        # was unlocking half-done.
+        def delete_message(chat_id:, message_id:)
+          call("deleteMessage", chat_id: chat_id, message_id: message_id)
+        rescue Error, Unavailable
+          false
+        end
+
         def set_my_commands(commands)
           payload = commands.map { |name, description| { command: name, description: description } }
 
@@ -128,6 +162,17 @@ module AgentsControl
 
         def url_for(method) = URI("https://#{HOST}/bot#{@token}/#{method}")
 
+        # Telegram serves file bytes from /file/bot<token>/<path>.
+        # Escaped per path segment: the path comes back from the API
+        # and gets to decide part of a URL, so it doesn't get to smuggle
+        # a "?" or a "../" into one.
+        def file_url_for(file_path)
+          segments = file_path.to_s.split("/").reject(&:empty?).map { |part| URI::DEFAULT_PARSER.escape(part) }
+          raise Error, "getFile: refusing a path that escapes its directory" if segments.any? { |s| s == ".." }
+
+          URI("https://#{HOST}/file/bot#{@token}/#{segments.join('/')}")
+        end
+
         # Drop nil fields: Telegram treats them as values that were actually passed.
         def compact(params) = params.compact
 
@@ -156,6 +201,35 @@ module AgentsControl
       class Http
         NetworkError = Class.new(StandardError)
 
+        # Written straight to the open file as chunks arrive. The caller
+        # owns the path; a failure part-way leaves a partial file, which
+        # is why callers download to a temporary name and rename.
+        # max_bytes is counted as the bytes arrive, not taken from a
+        # header or from what the sender said the file weighs: both are
+        # claims, and the disk fills either way if they're wrong.
+        def get_to_file(uri, path, read_timeout:, max_bytes: nil)
+          Net::HTTP.start(uri.host, uri.port,
+                          use_ssl: true, open_timeout: 10, read_timeout: read_timeout) do |http|
+            http.request(Net::HTTP::Get.new(uri)) do |response|
+              raise NetworkError, "download failed (HTTP #{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+              written = 0
+              File.open(path, "wb") do |file|
+                response.read_body do |chunk|
+                  written += chunk.bytesize
+                  raise NetworkError, "the file is larger than expected" if max_bytes && written > max_bytes
+
+                  file.write(chunk)
+                end
+              end
+            end
+          end
+
+          path
+        rescue SystemCallError, Timeout::Error, IOError, OpenSSL::SSL::SSLError, SocketError => e
+          raise NetworkError, e.message
+        end
+
         def post(uri, params, read_timeout:)
           request = Net::HTTP::Post.new(uri)
           request.set_form_data(params)