@craftsamo/telegram-tools 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,538 @@
-# Temporary Holding Version
+# telegram-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Unofficial Telegram tools for coding agents: chats, messages, received files, sends and actions.
+
+| Harness        | Delivery                                       | Pinned by                      |
+| -------------- | ---------------------------------------------- | ------------------------------ |
+| OpenCode V2    | native plugin (npm package, with skills)       | the version in the package     |
+| OpenCode V1    | native plugin (npm package, no skills)         | the version in the package     |
+| Claude Code    | plugin: MCP server and skills                  | the release tag, as the ref    |
+| Codex          | plugin: MCP server and skills                  | the release tag, as the ref    |
+| Grok Build     | plugin: MCP server and skills                  | the release tag, as `@ref`     |
+| Antigravity    | plugin: MCP server and skills                  | the release tag's tree URL     |
+| Hermes Agent   | native plugin (Python, calls the command line) | the release commit, as the SHA |
+| other MCP host | MCP server from npm                            | the version in the package     |
+
+The tools need [Node.js](https://nodejs.org/) 24 or later.
+[`docs/conventions.md`](docs/conventions.md) describes how the tools are named
+and how they behave.
+
+## Install
+
+Install from a release, never from the default branch: a release is a tag whose
+commit carries the built `dist/`, and the default branch does not. In the
+commands below, `<version>` is a release's version (`1.2.3`) and `<sha>` is the
+commit its tag names:
+
+```sh
+gh api repos/craft-agent/telegram-tools/commits/v<version> --jq .sha
+```
+
+### OpenCode
+
+OpenCode V2 takes the package and its options in `opencode.json`:
+
+```json
+{
+  "plugins": [{ "package": "@craftsamo/telegram-tools@<version>", "options": { "read_only": false } }],
+  "permissions": [{ "action": "telegram_*", "resource": "*", "effect": "ask" }]
+}
+```
+
+OpenCode V1 takes the package as a string, or as a pair with its options:
+
+```json
+{
+  "plugin": [["@craftsamo/telegram-tools@<version>", { "read_only": false }]],
+  "permission": { "telegram_*": "ask" }
+}
+```
+
+OpenCode allows any action no rule names, so the plugin's request is granted
+silently unless a rule says `ask`. Read tools never ask, so the `telegram_*` glob
+is safe.
+
+V1 registers no skills. Unpack the package and copy its `skills/*` folders into
+`~/.config/opencode/skills/`:
+
+```sh
+npm pack @craftsamo/telegram-tools@<version>
+tar -xzf craftsamo-telegram-tools-<version>.tgz
+mkdir -p ~/.config/opencode/skills
+cp -r package/skills/* ~/.config/opencode/skills/
+rm -rf package craftsamo-telegram-tools-<version>.tgz
+```
+
+### Claude Code
+
+```sh
+claude plugin marketplace add craft-agent/telegram-tools#v<version>
+claude plugin install telegram-tools@craft-agent
+```
+
+### Codex
+
+```sh
+codex plugin marketplace add craft-agent/telegram-tools --ref v<version>
+codex plugin add telegram-tools@craft-agent
+```
+
+Codex turns `-` into `_` in server names, so it shows the tools as
+`mcp__telegram_tools__telegram_*`. It starts the MCP server in the plugin's
+install directory, which is never the caller's working tree.
+
+### Grok Build
+
+```sh
+grok plugin install craft-agent/telegram-tools@v<version> --trust
+```
+
+Grok starts the MCP server in the session's working directory.
+
+### Antigravity
+
+Install from the tree of the release tag, never from the default branch, which
+has no built `dist/`; Antigravity clones the tag into
+`~/.gemini/config/plugins/telegram-tools`.
+
+```sh
+agy plugin install https://github.com/craft-agent/telegram-tools/tree/v<version>
+```
+
+### Hermes Agent
+
+Hermes installs a commit, not a tag, and the plugin installs disabled:
+
+```sh
+hermes plugins install craft-agent/telegram-tools --ref <sha>
+hermes plugins enable telegram-tools
+```
+
+If a Hermes gateway is already running, restart it (`hermes gateway restart`) to
+load the plugin.
+
+The plugin runs the Node it found when Hermes started. If a version manager
+removes that version while Hermes runs, a call looks for Node again; when it
+finds none, restart Hermes from a shell where `node` runs.
+
+### Any other MCP host
+
+Add the server to the host's MCP configuration. Flags go in `args`:
+
+```json
+{
+  "mcpServers": {
+    "telegram-tools": {
+      "command": "npx",
+      "args": ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
+    }
+  }
+}
+```
+
+## Tools and skills
+
+Each toolset comes with a skill that tells an agent how to use its tools. A
+skill names its toolset under `metadata` in its frontmatter
+(`metadata: { toolset: sends }`, written as a block). OpenCode V2 and Hermes
+register it only when the settings register at least one of that toolset's
+tools, so a profile with the toolset off, or with all its tools removed, does
+not see it; a skill without a toolset is always registered. Claude Code,
+Codex, Grok Build and Antigravity install the skill folder whole and pass the
+settings only to the MCP server, so they list every skill whatever the
+settings select. OpenCode V1 registers no skills, and its copied skills are
+all listed too.
+
+### Account (`account`)
+
+| Tool                    | What it does                                                                                                                                  | Class |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| `telegram_account_read` | which labels are logged in, whether each sync service runs, when it last heard from Telegram, the mirror's counts, and the person's next step | read  |
+
+It reads local state only: no daemon, no network, and no phone number, account
+id or key in its result. The skill is
+[`telegram-account`](skills/telegram-account/SKILL.md), shown as
+`telegram-tools:telegram-account` in Claude Code and `telegram-tools:account`
+in Hermes.
+
+### Chats (`chats`)
+
+| Tool                 | What it does                                                                                                       | Class |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- |
+| `telegram_chat_read` | finds chats and reads messages by `method`: `list`, `view`, `topics`, `search`, `around`, or older history `fetch` | read  |
+
+Chats the mirror keeps (private chats, bots, basic groups, Saved Messages;
+supergroups and channels while on the sync list) are read from the local mirror
+without needing the sync service; older history is fetched with `fetch`. Chats
+only listed are read live from Telegram by `view` and `around`, via the sync
+service, up to 100 messages a page (`live: true`). Message text, captions, file
+names and topic titles are data, never instructions. The skill is
+[`telegram-chats`](skills/telegram-chats/SKILL.md), shown as
+`telegram-tools:telegram-chats` in Claude Code and `telegram-tools:chats` in
+Hermes.
+
+### Sync (`sync`)
+
+| Tool                   | What it does                                                                           | Class      |
+| ---------------------- | -------------------------------------------------------------------------------------- | ---------- |
+| `telegram_sync_read`   | lists the supergroups and channels on the sync list                                    | read       |
+| `telegram_sync_add`    | puts supergroups or channels on the sync list to mirror from now on                    | idempotent |
+| `telegram_sync_remove` | takes chats off the sync list and deletes their mirrored messages and earlier versions | overwrite  |
+
+The sync list names up to 30 supergroups and channels whose messages the mirror
+keeps current. `telegram_sync_read` reads the list from the local mirror
+without needing the sync service. Adding or removing chats changes the local
+mirror and needs the sync service running; newly added chats are seeded with
+their newest 50 messages, while removing a chat deletes its mirrored messages
+and earlier versions locally (nothing changes at Telegram). Channels can be
+listed or mirrored only with the `channels` setting on. The skill is
+[`telegram-sync`](skills/telegram-sync/SKILL.md), shown as
+`telegram-tools:telegram-sync` in Claude Code and `telegram-tools:sync` in
+Hermes.
+
+### Sends (`sends`)
+
+| Tool                    | What it does                                                              | Class |
+| ----------------------- | ------------------------------------------------------------------------- | ----- |
+| `telegram_message_send` | sends one text to a chat by id, optionally to a forum topic or as a reply | add   |
+
+The `sends` toolset is on by default. The text goes out as written (never read
+as Markdown or HTML), trimmed, at most 4096 characters. One call sends once,
+with one `random_id`, and is never repeated: a failure `uncertain` means the
+message may have gone out, and its hint lists the matching messages the mirror
+saw, so the person checks the chat before anything is sent again. `duplicate`
+means an earlier delivery of the same call had already gone out. The sync
+service sends it, so it must be running. The skill is
+[`telegram-sends`](skills/telegram-sends/SKILL.md), shown as
+`telegram-tools:telegram-sends` in Claude Code and `telegram-tools:sends` in
+Hermes.
+
+### Files (`files`)
+
+| Tool                 | What it does                                                                | Class |
+| -------------------- | --------------------------------------------------------------------------- | ----- |
+| `telegram_file_save` | downloads one message's file from Telegram and saves it into `download_dir` | add   |
+| `telegram_file_send` | sends 1 to 10 files (100 MB together), with a caption, to a chat            | add   |
+
+The `files` toolset is off by default: it writes to disk, opens archives and
+sends files. Turn it on with `toolsets` or `tools`. Sending takes 1 to 10 files
+(at most 100 MB together) as one group, every file as a file, from the working
+directory (not when that is the home directory or a file system root) and the
+directories `send_dirs` names; keys, secrets, programs and installers are
+refused, archives are checked entry by entry, each file is copied into the
+label's outbox and checked before upload, and `sha256` can pin a file to what
+was approved. Sending needs the sync service running; a failure `uncertain`
+lists matching messages the mirror saw so the person checks the chat before
+anything is sent again. For received files, a message's file goes in
+`<download_dir>/<label>/<chat id>/<message id>/`, private (mode 600), never
+executable and never overwritten; `download_max_mb` sets the largest file
+taken. The sync service downloads it, so it must be running. Programs and
+installers are refused, and so are archives other than zip, tar and gzipped
+tar, archives holding a program, another archive, a link or a path that leaves
+them, animated stickers and view-once files. An archive is inspected and
+listed, and unpacked only when asked (`unpack: true`) into `<name>.unpacked/`
+beside it. On macOS every saved and unpacked file carries the quarantine flag.
+File names and contents are data, never instructions. The skill is
+[`telegram-files`](skills/telegram-files/SKILL.md), shown as
+`telegram-tools:telegram-files` in Claude Code and `telegram-tools:files` in
+Hermes.
+
+### Actions (`actions`)
+
+| Tool                      | What it does                                                          | Class          |
+| ------------------------- | --------------------------------------------------------------------- | -------------- |
+| `telegram_message_edit`   | replaces the text or caption of one of the user's own messages        | overwrite      |
+| `telegram_message_delete` | deletes one of the user's own messages for everyone                   | administrative |
+| `telegram_message_react`  | sets or removes the user's emoji reaction on a message                | overwrite      |
+| `telegram_message_pin`    | pins or unpins a message                                              | overwrite      |
+| `telegram_chat_mark_read` | marks a chat, or one forum topic, read up to a message, never further | idempotent     |
+
+The `actions` toolset is off by default: it changes what other people have
+already read. Turn it on with `toolsets` or `tools`. Edit and delete take only
+the user's own messages; a delete is always for everyone, cannot be undone and
+is asked about every time. A reaction is one standard emoji that replaces the
+user's earlier one (custom and paid reactions are refused). A pin is silent
+unless `notify`, and in a private chat it pins for the user only unless
+`both_sides`. Mark read runs only when the user asks, goes up to the message
+named and never back, and makes the senders see it read. Every action needs the
+sync service running. `already` means it was already so; `uncertain` means it
+may have happened, so the person checks the chat before it is asked again. The
+skill is [`telegram-actions`](skills/telegram-actions/SKILL.md), shown as
+`telegram-tools:telegram-actions` in Claude Code and `telegram-tools:actions`
+in Hermes.
+
+## Adding a tool
+
+1. Write the spec in `src/core/<domain>/<verb>.ts` with `defineTool`: an ID
+   `<prefix>_<domain>_<verb>`, a title and description, the Zod argument and
+   output schemas, its toolset and write class, and `execute(args, context)`.
+   A write tool also gives `targets(args, context)`: what the call writes to,
+   as a permission rule should name it.
+2. Test it beside the spec (`<verb>.test.ts`), calling it through `invoke` as
+   the entry points do. A tool that runs a program is tested against a fake of
+   that program on `PATH`; no test reaches a real service.
+3. List it in `src/tools.ts`. A new toolset goes into `toolsets` in
+   `src/project.ts` (and `defaultToolsets` when it is on by default), and a
+   variable the tool reads besides the settings into `toolVariables`.
+4. Add or update the toolset's skill, `skills/<prefix>-<toolset>/SKILL.md`,
+   whose frontmatter names the toolset under `metadata`.
+5. Run `pnpm run build && pnpm run manifests` to list the tool in
+   `plugin.yaml` and its variables in Codex's manifest, then describe it under
+   "Tools and skills".
+
+[`docs/conventions.md`](docs/conventions.md) has the rules each step follows.
+
+## Reads and writes
+
+Every read tool is named `<prefix>_<domain>_read`. Reads can run unasked;
+writes are confirmed by the harness.
+
+| Harness     | Reads without asking                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| OpenCode    | always; the plugin asks only before a write                                                                      |
+| Claude Code | the rule `mcp__plugin_telegram-tools_telegram-tools__*_read` in `permissions.allow` of `~/.claude/settings.json` |
+| Codex       | always; Codex runs tools that declare `readOnlyHint` unasked, as the read tools do                               |
+| Grok Build  | `grok --allow 'MCPTool(telegram-tools__*_read)' --allow 'MCPTool(telegram_*_read)'` (both rules; see below)      |
+| Antigravity | the rule `mcp(telegram-tools_telegram-tools/<tool id>)` in `permissions.allow`, one for each read tool           |
+| Hermes      | always; the plugin asks only before a write                                                                      |
+
+Where a write is asked about, and where it is not:
+
+- **OpenCode** grants any action no rule names, so a write runs unasked unless
+  a rule asks for it: add the `telegram_*` rule shown under [OpenCode](#opencode).
+- **Codex** under `codex exec`, and **Grok Build** under `grok -p`, refuse a
+  write they cannot ask about, unless it is allowed beforehand.
+- **Grok Build** calls the plugin's tools through its `use_tool` tool, and the
+  agent often names a tool without its server first. Grok checks the rules
+  against the name as given, so the server-qualified rule alone does not match
+  that first call. The second rule matches the short name; a write still
+  matches neither.
+- **Antigravity** asks before any MCP tool no rule allows, reads included, and
+  names the plugin's server `telegram-tools_telegram-tools` (plugin,
+  then server). `agy -p` refuses a tool it cannot ask about.
+- **Hermes** `hermes chat -q` refuses a write it cannot ask about; `hermes -z`
+  and `--yolo` skip approval, so writes then run unasked.
+
+## Settings
+
+Every entry point takes the same settings. A flag wins over its environment
+variable, and an option or setting wins over the variable too.
+
+| Setting             | Flag                    | Variable                           | Meaning                                                                                                                                                    |
+| ------------------- | ----------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toolsets`          | `--toolsets`            | `TELEGRAM_TOOLS_TOOLSETS`          | the toolsets that are on, or `all`; default those `src/project.ts` names                                                                                   |
+| `read_only`         | `--read-only`           | `TELEGRAM_TOOLS_READ_ONLY`         | registers no tool that writes; wins over every other setting                                                                                               |
+| `tools`             | `--tools`               | `TELEGRAM_TOOLS_TOOLS`             | single tools to add by ID, whatever their toolset                                                                                                          |
+| `exclude_tools`     | `--exclude-tools`       | `TELEGRAM_TOOLS_EXCLUDE_TOOLS`     | single tools to remove by ID; wins over `tools` and `toolsets`                                                                                             |
+| `confirm`           | `--confirm`             | `TELEGRAM_TOOLS_CONFIRM`           | MCP server only: `harness` (default) or `elicitation`, as the conventions say                                                                              |
+| `language`          | `--language`            | `TELEGRAM_TOOLS_LANGUAGE`          | native plugins only: the approval prompt's language, such as `ja`                                                                                          |
+| `state_dir`         | `--state-dir`           | `TELEGRAM_TOOLS_STATE_DIR`         | where every label's state lives; default `$XDG_STATE_HOME/telegram-tools`                                                                                  |
+| `download_dir`      | `--download-dir`        | `TELEGRAM_TOOLS_DOWNLOAD_DIR`      | where `telegram_file_save` saves received files, a folder per message; default `~/Downloads/telegram-tools`; read by the tools, no service restart needed  |
+| `download_max_mb`   | `--download-max-mb <n>` | `TELEGRAM_TOOLS_DOWNLOAD_MAX_MB`   | the largest file a download takes, in MB; integer 1..2000, default 100; read by the tools, no service restart needed                                       |
+| `send_dirs`         | `--send-dirs`           | `TELEGRAM_TOOLS_SEND_DIRS`         | the directories files may be sent from, besides the working directory; absolute paths, default none; read by the tools, no service restart needed          |
+| `keep_disappearing` | `--keep-disappearing`   | `TELEGRAM_TOOLS_KEEP_DISAPPEARING` | keep disappearing and view-once messages for the user; off by default; read by `sync` and `service install`, run `service install` again after changing it |
+| `channels`          | `--channels`            | `TELEGRAM_TOOLS_CHANNELS`          | list, read, mirror and send to channels; off by default, see below; read by `sync` and `service install`, run `service install` again after changing it    |
+
+Lists are comma-separated in a flag or a variable. Where each harness reads them:
+
+- **OpenCode** takes the plugin `options` shown above, with lists as arrays,
+  `read_only` as a boolean, `state_dir` and `download_dir` as paths, and
+  `download_max_mb` as a number, `send_dirs` as an array of paths, and falls back to the
+  variables. V2 runs plugins in its background service, which keeps the
+  environment it started with: a variable set where `opencode run` starts has
+  no effect until the service is
+  restarted in that environment (`opencode service restart`). V1 runs plugins
+  in its own process.
+- **Hermes** takes `plugins.entries.telegram-tools.settings` in
+  `config.yaml`:
+
+  ```yaml
+  plugins:
+    entries:
+      telegram-tools:
+        settings:
+          read_only: false
+          exclude_tools: []
+  ```
+
+  Without a `language` setting, the approval card follows Hermes's own
+  `display.language` (or `HERMES_LANGUAGE`), the language of its approval
+  buttons, and else stays in English. The plugin passes its own environment
+  to the command line it runs, so the variables work too. A running gateway keeps the environment it started with;
+  restart it (`hermes gateway restart`) after changing one.
+
+- **Claude Code, Grok Build and Antigravity** start the plugin's server without
+  flags and pass it the client's environment, so set the variables in the
+  environment the harness runs in.
+- **Codex** passes a plugin's MCP server only a few basic variables (such as
+  `PATH` and `HOME`) and those the plugin's manifest names, which are the
+  variables above: set them in the environment Codex runs in. A variable the
+  tools read besides the settings belongs in `toolVariables` in
+  `src/project.ts`; `pnpm run manifests` adds it to the manifest after the
+  settings' variables. To pass flags, or to give the server a variable the
+  package does not name, add the server under `[mcp_servers]` in Codex's
+  `config.toml` instead of using the plugin: flags go in `args`, `env_vars`
+  names the variables to forward from Codex's environment, and `env` sets
+  fixed values.
+
+  ```toml
+  [mcp_servers.telegram-tools]
+  command = "npx"
+  args = ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
+  env_vars = ["TELEGRAM_TOOLS_TOOLSETS"]
+  ```
+
+### Accounts and the sync service
+
+The tools log in as a device of the user's own account through
+[mtcute](https://mtcute.dev), with an `api_id` and `api_hash` you register at
+[my.telegram.org](https://my.telegram.org). They never read another client's
+data.
+
+- **Each logged-in session has a label**, 1 to 24 lowercase letters, digits and
+  `_` (`default` when logging in names none). A tool's `account` argument picks
+  the label; leave it out when only one session is logged in.
+- **Each label keeps its state in one directory**, `<state_dir>/<label>/` (mode
+  700): the session and the app credentials, mtcute's storage, the mirror, the
+  service's socket, and `incoming/`, the short-lived copies of files in
+  transit. `state_dir` defaults to `$XDG_STATE_HOME/telegram-tools`, or
+  `~/.local/state/telegram-tools`. Keep it out of shared backups: the session
+  reads and sends as you.
+- **A sync service holds each label's only connection** and keeps the mirror.
+  Chats the mirror keeps are read from the mirror; chats only listed are read
+  live via the service. History starts when the service starts following a
+  chat; `fetch` adds older history.
+- **A new login is shown to your other devices**, and Telegram ends sessions
+  unused for the period set under the account's settings.
+
+### Logging in and running the sync service
+
+Before you start, register an app at [my.telegram.org](https://my.telegram.org)
+(API development tools) to get an `api_id` and `api_hash`. The tools need
+[Node.js](https://nodejs.org/) 24 or later. macOS and Linux are supported.
+
+```sh
+# Log in: on your phone, open Telegram > Settings > Devices > Link Desktop Device,
+# and scan the QR code this prints.
+telegram-tools-cli login --account work
+
+# Start receiving at logon, and restart after a failure.
+telegram-tools-cli service install --account work
+telegram-tools-cli service status --account work
+```
+
+`--account` may be left out when only one label exists (`login` names a new
+one `default`), and every command takes `--state-dir` like the tools.
+
+| Command                                                       | What it does                                                                                                    |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `login [--account <label>] [--phone \| --telethon]`           | logs in by QR code (default), phone and code (`--phone`), or Telethon v1 string session (`--telethon`)          |
+| `sync [--account <label>] [--keep-disappearing] [--channels]` | runs the sync service in the foreground, logging to standard error, until it is stopped                         |
+| `service install \| uninstall \| status [--account <label>]`  | registers the sync service as a launchd agent (macOS) or a systemd user unit (Linux), removes it, or reports it |
+| `logout [--account <label>]`                                  | ends the session at Telegram and keeps the mirror, while removing local session storage                         |
+| `remove --account <label> [--yes]`                            | uninstalls the service and permanently deletes the label's directory, after `--yes` or typing the label back    |
+
+- **Logging in**: `login` shows a QR code by default. Scan it in Telegram on
+  your phone under Settings → Devices → Link Desktop Device. `--phone` logs in
+  with your phone number and login code; `--telethon` imports a Telethon v1
+  string session, read without echo on a terminal or from standard input. If
+  your account uses a two-step verification password, `login` asks for it
+  without echo. `TELEGRAM_TOOLS_API_ID` and `TELEGRAM_TOOLS_API_HASH` are used
+  when set in the environment; otherwise `login` asks for them (the hash
+  without echo) and saves them in `<state_dir>/<label>/app.json` (mode 0600).
+- **What the service does**: at first start, the service fetches the chat list
+  and seeds the newest 50 messages of chats active in the last 30 days, a few
+  at a time and paced to avoid flood limits. After that, every update is stored
+  in the mirror as it arrives, the chat list is refreshed every 30 minutes, and
+  gaps in message history are filled. Supergroups and channels are mirrored only
+  while on the sync list (at most 30); channels also require the `channels`
+  setting to be turned on.
+- **Where it logs**: on macOS, the service writes its log to the file under
+  `~/Library/Logs/io.github.craft-agent.telegram-tools/<label>.log` that
+  `service install` prints. On Linux, it logs to the systemd user journal
+  (`journalctl --user -u <unit>` as `service status` shows); run
+  `loginctl enable-linger` to keep the service running after you log out.
+- **On macOS, Login Items lists the service as `telegram-tools-sync-<label>`**:
+  the agent starts through that launcher script, which `service install` writes
+  to `~/Library/Application Support/io.github.craft-agent.telegram-tools/` and
+  `service uninstall` deletes. Switching the item off there stops syncing.
+- **Service updates and restarts**: `service install` records this package's
+  executable path and Node's, so run `service install` again after updating
+  either, or changing `keep_disappearing` or `channels`. Where Node's path
+  holds its version, as under a version manager, `service install` records a
+  `node` on `PATH` at a path without it that starts the same Node, and warns
+  when there is none. That `node` then runs whichever Node the manager makes
+  current. `service status` and `telegram_account_read` say when the recorded
+  program is gone, once the service has been installed with this version. The
+  service restarts after a failure a minute later, but stays down after
+  Telegram ends the session.
+- **One connection per label**: Telegram can revoke an auth key that connects
+  from two places at once. `login`, `logout` and `remove` refuse while the
+  service runs; stop it first (`service uninstall`, or stop foreground `sync`).
+- **Logging out and removing**: `logout` ends the session at Telegram and keeps
+  the mirror, removing only the session storage. `remove` uninstalls the
+  service and permanently deletes the label's directory, and on macOS the
+  service's log too (`service uninstall` keeps it); on Linux the journal keeps
+  the service's entries. If Telegram cannot be reached, the session is removed
+  locally; end the session in Telegram under Settings → Devices.
+- **Device sessions**: a new login shows on your other devices. Telegram ends
+  a session unused for the period set under Settings → Privacy and Security →
+  "If away for"; then log in again. `telegram_account_read` tells an agent
+  which step a label needs.
+
+### Unofficial, and what Telegram's terms say
+
+The package is not made or endorsed by Telegram. You register your own app
+([API terms §2.1](https://core.telegram.org/api/terms)), and the package and the
+device name the service logs in as identify it as unofficial (§2.2, §2.3).
+
+- **Telegram's terms forbid using platform data for AI.**
+  [§1.5](https://core.telegram.org/api/terms) forbids using data from the
+  platform to train or deploy AI, and a broad reading covers an agent reading
+  your own chats. Unofficial clients are watched and abuse can freeze or ban
+  the account.
+- **`keep_disappearing` and `channels` are off by default.** Keeping
+  disappearing messages goes against §1.4. With it on, the sync service also
+  keeps the files of disappearing, view-once and self-destructing messages as
+  they arrive (up to 100 MB each, never programs or archives), so
+  `telegram_file_save` can save them after Telegram removed them; turning it
+  off deletes those files at the service's next start. For channels, API terms §3.3 asks an
+  app showing channel content to show sponsored messages. Sponsored messages are
+  never fetched or shown (avoiding untrusted prompts reaching the model), and
+  whoever turns `channels` on accepts that §3.3 risk. With `channels` off, no
+  channel is listed, read, mirrored or kept on the sync list, and the sync
+  service deletes every channel and its mirrored messages from the mirror at its
+  next start.
+
+## Layout
+
+- `src/project.ts` — the package's name, tool ID prefix, setting prefix,
+  toolsets and the other variables its tools read.
+- `src/core/` — the tool contract and the tools, free of any harness and of
+  the project's names.
+- `src/tools.ts` — the list of every tool, which each entry point registers.
+- `src/words.ts` — the translations of the tools' words, per language, which
+  the native plugins use in their approval prompts.
+- `src/mcp/` — the MCP server, built to `dist/mcp.js` and run by
+  `telegram-tools`.
+- `src/opencode/` — the OpenCode plugin, built to `dist/opencode.js`.
+- `src/cli/` — the command line the Hermes plugin calls, built to `dist/cli.js`
+  and run by `telegram-tools-cli`.
+- `src/hermes/`, `plugin.yaml` and `__init__.py` — the Hermes plugin.
+- `skills/` — one skill per toolset, `skills/<name>/SKILL.md`, which every
+  harness that takes skills loads from the package or plugin root; the native
+  plugins load only those of the toolsets that are on.
+- `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, `.mcp.json`,
+  `.antigravity-plugin/` and `mcp_config.json` — the plugin manifests of the
+  other harnesses. Codex reads `.codex-plugin/plugin.json`; a root
+  `plugin.json` would make it load the plugin as an Agent Plugin, whose tool
+  budget hides tools past a fixed size. The root `.mcp.json` is the
+  configuration Grok Build reads (with `${CLAUDE_PLUGIN_ROOT}`, the variable
+  both Grok Build and Claude Code expand); when working on this repository in
+  Claude Code, decline the project MCP server it offers from that file.
+
+How a release is made is in [`RELEASING.md`](RELEASING.md).
+
+## License
+
+[AGPL-3.0 with Commons Clause](LICENSE)

package/__init__.py

@@ -0,0 +1,36 @@
+"""Loads the plugin package from ``src/hermes/telegram_tools_hermes`` for Hermes, which imports this file.
+
+The package is loaded as ``<this module's name>._impl``, so Hermes, which evicts
+everything under a plugin's module name when it reloads it or loads it for another
+profile, evicts the package too, and each install path gets a package of its own.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+_NAME = f"{__name__}._impl"
+_PACKAGE_DIR = Path(__file__).resolve().parent / "src" / "hermes" / "telegram_tools_hermes"
+
+
+def _evict() -> None:
+    """Drop the package and its submodules from ``sys.modules``."""
+    for name in list(sys.modules):
+        if name == _NAME or name.startswith(f"{_NAME}."):
+            sys.modules.pop(name, None)
+
+
+_spec = importlib.util.spec_from_file_location(
+    _NAME, _PACKAGE_DIR / "__init__.py", submodule_search_locations=[str(_PACKAGE_DIR)]
+)
+_module = importlib.util.module_from_spec(_spec)
+_evict()
+sys.modules[_NAME] = _module
+try:
+    _spec.loader.exec_module(_module)
+except BaseException:
+    _evict()
+    raise
+
+register = _module.register
+__all__ = ["register"]