agentforge-telegram-gateway 3.1.0__py3-none-any.whl

agent_client.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Small dependency-free client SDK/CLI for user-owned agents."""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import mimetypes
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+__all__ = ["TelegramAgentClient"]
+
+
+class TelegramAgentClient:
+    def __init__(self, source: str, *, key: str = "", base_url: str = "http://127.0.0.1:8818", timeout: float = 15.0) -> None:
+        self.source = source
+        self.key = key.strip()
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @classmethod
+    def from_key_file(cls, source: str, key_file: str | Path, **kwargs: Any) -> "TelegramAgentClient":
+        return cls(source, key=Path(key_file).read_text(encoding="utf-8").strip(), **kwargs)
+
+    def _request(self, method: str, path: str, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        headers = {"X-Notifier-Source": self.source, "Accept": "application/json"}
+        if self.key:
+            headers["Authorization"] = f"Bearer {self.key}"
+        data = None
+        if payload is not None:
+            data = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                result = json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            try:
+                result = json.loads(exc.read().decode("utf-8"))
+                error = str(result.get("error") or "request_failed")
+            except (ValueError, TypeError, UnicodeDecodeError):
+                error = "request_failed"
+            raise RuntimeError(error) from None
+        except (urllib.error.URLError, TimeoutError, OSError, ValueError):
+            raise RuntimeError("gateway_unavailable") from None
+        if not isinstance(result, dict) or not result.get("ok"):
+            raise RuntimeError(str(result.get("error") if isinstance(result, dict) else "invalid_gateway_response"))
+        return result
+
+    def inbox(self, *, after: str = "", limit: int = 50) -> dict[str, Any]:
+        query = urllib.parse.urlencode({"after": after, "limit": str(limit)})
+        return self._request("GET", f"/v1/inbox?{query}")
+
+    def reply_text(self, event_id: str, text: str, *, title: str = "") -> dict[str, Any]:
+        return self._request("POST", "/v1/reply", {"event_id": event_id, "kind": "text", "title": title, "text": text})
+
+    def reply_file(self, event_id: str, file_path: str | Path, *, caption: str = "", photo: bool = False) -> dict[str, Any]:
+        path = Path(file_path)
+        content = path.read_bytes()
+        return self._request(
+            "POST",
+            "/v1/reply",
+            {
+                "event_id": event_id,
+                "kind": "photo" if photo else "document",
+                "filename": path.name,
+                "content_type": mimetypes.guess_type(path.name)[0] or "application/octet-stream",
+                "content_base64": base64.b64encode(content).decode("ascii"),
+                "text": caption,
+            },
+        )
+
+    def download(self, event_id: str) -> tuple[str, str, bytes]:
+        query = urllib.parse.urlencode({"event_id": event_id})
+        result = self._request("GET", f"/v1/file?{query}")
+        return str(result["filename"]), str(result["content_type"]), base64.b64decode(result["content_base64"], validate=True)
+
+    def notify(self, text: str, *, title: str = "") -> dict[str, Any]:
+        return self._request("POST", "/v1/notify", {"kind": "text", "title": title, "text": text})
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Talk to the local Telegram agent gateway")
+    parser.add_argument("--source", required=True)
+    parser.add_argument("--key-file", required=True)
+    parser.add_argument("--base-url", default="http://127.0.0.1:8818")
+    sub = parser.add_subparsers(required=True)
+
+    inbox = sub.add_parser("inbox")
+    inbox.add_argument("--after", default="")
+    inbox.add_argument("--limit", type=int, default=50)
+
+    reply = sub.add_parser("reply")
+    reply.add_argument("event_id")
+    reply.add_argument("--text", required=True)
+
+    send_file = sub.add_parser("reply-file")
+    send_file.add_argument("event_id")
+    send_file.add_argument("file")
+    send_file.add_argument("--caption", default="")
+    send_file.add_argument("--photo", action="store_true")
+
+    download = sub.add_parser("download")
+    download.add_argument("event_id")
+    download.add_argument("--output", required=True)
+
+    notify = sub.add_parser("notify")
+    notify.add_argument("--text", required=True)
+    notify.add_argument("--title", default="")
+
+    args = parser.parse_args()
+    client = TelegramAgentClient.from_key_file(args.source, args.key_file, base_url=args.base_url)
+    if args.__dict__.get("after") is not None:
+        print(json.dumps(client.inbox(after=args.after, limit=args.limit), indent=2))
+    elif hasattr(args, "event_id") and hasattr(args, "text"):
+        print(json.dumps(client.reply_text(args.event_id, args.text), indent=2))
+    elif hasattr(args, "file"):
+        print(json.dumps(client.reply_file(args.event_id, args.file, caption=args.caption, photo=args.photo), indent=2))
+    elif hasattr(args, "output"):
+        filename, content_type, content = client.download(args.event_id)
+        output = Path(args.output)
+        output.write_bytes(content)
+        print(json.dumps({"ok": True, "filename": filename, "content_type": content_type, "output": str(output), "bytes": len(content)}))
+    else:
+        print(json.dumps(client.notify(args.text, title=args.title), indent=2))
+
+
+if __name__ == "__main__":
+    main()

agentforge_telegram_gateway-3.1.0.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: agentforge-telegram-gateway
+Version: 3.1.0
+Summary: Telegram bridge and MCP gateway for user-owned AI agents
+Author: AgentForge Labs
+License: AGPL-3.0-only
+Project-URL: Homepage, https://github.com/AgentForge-Labs/shared-telegram-notifier
+Project-URL: Repository, https://github.com/AgentForge-Labs/shared-telegram-notifier
+Project-URL: Issues, https://github.com/AgentForge-Labs/shared-telegram-notifier/issues
+Keywords: telegram,mcp,ai-agents,chatgpt,claude,codex,qwen
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# AgentForge Telegram Gateway
+
+Connect user-owned AI agents to people through Telegram for notifications, conversations and file exchange.
+
+**Community Edition · MVP/Beta · GNU AGPL v3 (`AGPL-3.0-only`)**
+
+[Quickstart](#quickstart) · [Features](#features) · [MCP](#mcp-access) · [Security](#security) · [Architecture](docs/ARCHITECTURE.md) · [Contributing](CONTRIBUTING.md)
+
+AgentForge Telegram Gateway is for developers and operators who want a small, self-hosted bridge between Telegram and local or remote AI-agent workflows. Pair a Telegram chat once, provision a source-scoped agent identity, then exchange text, documents and photos without putting a Telegram chat ID or bot token into agent prompts.
+
+It works with MCP-capable clients and agent workflows such as ChatGPT, Codex, Claude and Qwen. The gateway is provider-independent: provider-account authentication remains with the provider's own tooling.
+
+## Quickstart
+
+### 1. Install
+
+```bash
+git clone https://github.com/AgentForge-Labs/shared-telegram-notifier.git
+cd shared-telegram-notifier
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install .
+```
+
+This installs four commands:
+
+```text
+agentforge-telegram          inbox, reply, file and notification CLI
+agentforge-telegram-mcp      MCP diagnostics and tool access
+agentforge-telegram-admin    bot setup, source provisioning and pairing
+agentforge-telegram-gateway  gateway server
+```
+
+### 2. Create a Telegram bot
+
+Create a bot with Telegram's `@BotFather`, then store the token through the protected setup flow:
+
+```bash
+sudo agentforge-telegram-admin telegram-setup
+sudo agentforge-telegram-admin telegram-doctor
+```
+
+The bot token is entered through a hidden prompt and stored outside the repository. Do not commit bot tokens, chat IDs or generated source credentials.
+
+### 3. Provision and pair an agent source
+
+```bash
+sudo agentforge-telegram-admin provision my-agent \
+  --output /var/lib/my-agent/telegram-gateway-key \
+  --owner my-agent:my-agent
+
+sudo agentforge-telegram-admin pair my-agent
+```
+
+Open the generated Telegram deep link. The pairing flow learns the authorized Telegram identity from Telegram itself; users do not need to copy a numeric chat ID.
+
+### 4. Run the gateway
+
+A hardened systemd unit is included at [`deploy/telegram-notifier.service`](deploy/telegram-notifier.service). After installing the service and configuration paths for your host:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now telegram-notifier
+curl http://127.0.0.1:8818/health
+```
+
+The gateway defaults to loopback. Put a TLS reverse proxy in front of it if an MCP client must connect remotely.
+
+## Features
+
+- one-time Telegram pairing links — no manual chat-ID discovery;
+- bidirectional text messages;
+- inbound and outbound documents/photos;
+- per-source `receive`, `send` and `files` permissions;
+- multiple agent sources with isolated credentials and bindings;
+- Telegram commands such as `/agents`, `/use`, `/status` and `/help`;
+- REST/agent CLI for inbox, replies, files and proactive notifications;
+- Streamable HTTP-style MCP endpoint;
+- Bearer authentication for header-capable MCP clients;
+- URL-secret mode for clients that cannot send custom authorization headers;
+- OAuth 2.1 Authorization Code + PKCE for OAuth-capable MCP clients;
+- source-scoped authorization so one agent credential cannot impersonate another source;
+- loopback-first deployment and protected file-based secrets.
+
+## MCP access
+
+The MCP gateway exposes the Telegram bridge to MCP-capable clients while preserving source isolation.
+
+### Bearer
+
+Use the normal MCP endpoint with the source credential:
+
+```text
+POST https://telegram.example.com/mcp
+Authorization: Bearer <source-secret>
+```
+
+### URL secret
+
+For clients that cannot attach an authorization header:
+
+```text
+https://telegram.example.com/client/<source-secret>/mcp
+```
+
+Treat that URL as a credential. Configure reverse-proxy access logs so the secret-bearing path is never recorded verbatim.
+
+### OAuth + PKCE
+
+OAuth-capable MCP clients can use the gateway's protected-resource and authorization-server discovery endpoints with Authorization Code + PKCE S256. Configure OAuth with protected secret files; do not place client secrets directly in committed service files.
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the authentication and trust boundaries.
+
+## Generate an MCP connection file
+
+The admin CLI can write a protected client configuration without printing the source secret to standard output:
+
+```bash
+sudo agentforge-telegram-admin mcp-config my-agent \
+  --provider qwen \
+  --base-url https://telegram.example.com \
+  --key-file /var/lib/my-agent/telegram-gateway-key \
+  --output /var/lib/my-agent/telegram-mcp.json \
+  --owner my-agent:my-agent
+```
+
+Use the provider value that matches the client you are configuring. Generated connection files are credentials and should remain outside the repository.
+
+## Agent CLI examples
+
+Check the authenticated inbox:
+
+```bash
+agentforge-telegram --help
+```
+
+The CLI supports receiving events, replying, retrieving inbound files and sending notifications. Run `--help` for the current command surface rather than copying credentials into shell history.
+
+### Python SDKs
+
+The REST client is importable directly after installing the PyPI package:
+
+```python
+from agent_client import TelegramAgentClient
+
+client = TelegramAgentClient.from_key_file(
+    "my-agent", "/var/lib/my-agent/telegram-gateway-key"
+)
+events = client.inbox(limit=10)
+```
+
+For MCP transport diagnostics and arbitrary tool calls, use
+`mcp_client.TelegramMcpClient` or the matching CLI command:
+
+```bash
+agentforge-telegram-mcp --base-url https://telegram.example.com \
+  --auth bearer --key-file /var/lib/my-agent/telegram-gateway-key call \
+  telegram_inbox --arguments '{"limit":10}'
+```
+
+## Security
+
+The project is designed around a simple rule: **Telegram identity, gateway identity and model-provider identity are separate trust boundaries.**
+
+Key defaults and protections include:
+
+- gateway TCP bind defaults to `127.0.0.1:8818`;
+- the bot token lives in a protected file outside the repository;
+- source credentials are generated per agent/source;
+- persistent registries store credential digests rather than plaintext source keys;
+- pairing codes are short-lived and one-use;
+- OAuth uses exact redirect-URI matching and PKCE S256;
+- OAuth authorization/access/refresh state is stored as digests where applicable;
+- URL-secret application logs are redacted;
+- audit metadata excludes message text, file contents and raw credentials;
+- group chats are disabled by default.
+
+Example configuration lives in [`.env.example`](.env.example) and contains placeholders/file paths only. Never commit a real bot token, numeric personal chat/user identifier, real conversation fixture, private webhook URL or generated agent credential.
+
+For trust boundaries and protocol flow, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+
+## Deployment notes
+
+The included systemd unit is a reference for Linux hosts. Review service user/group ownership and paths before enabling it on your system. Remote MCP access should use HTTPS at the reverse proxy; do not expose the loopback HTTP listener directly to the public internet.
+
+Useful diagnostics:
+
+```bash
+agentforge-telegram-admin telegram-doctor
+agentforge-telegram-mcp --help
+agentforge-telegram-gateway --check
+```
+
+## What this project is — and is not
+
+This repository is the focused Telegram communication bridge. It does not contain the AgentForge cloud control plane, private AgentScope backend, enterprise infrastructure orchestration or production credentials.
+
+For broader AgentForge projects and public releases, visit [AgentForge Labs on GitHub](https://github.com/AgentForge-Labs).
+
+Within the AgentForge product family:
+
+- **AgentScope** is the natural next step when you need observability and operations around agent runs;
+- **AgentForge Runtime** is the commercial expansion when you need controlled infrastructure access and enterprise runtime capabilities.
+
+No private repository is required to use this Community Edition.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Please keep examples synthetic and never include real Telegram credentials, personal chat/user IDs or customer messages in issues, fixtures or pull requests.
+
+## License
+
+AgentForge Telegram Gateway Community Edition is licensed under the **GNU Affero General Public License v3.0 only** (`AGPL-3.0-only`). See [`LICENSE`](LICENSE).
+
+## Maintainers
+
+Maintained by [AgentForge Labs](https://github.com/AgentForge-Labs).
+
+## Commercial web application
+
+The private commercial repository includes a separate Next.js marketing and checkout app in `web/`.
+
+```bash
+cd web
+npm ci
+npm run validate
+npm run dev
+```
+
+Payment credentials and provider product/variant IDs are documented in `web/.env.example`. They are server-side only.

agentforge_telegram_gateway-3.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+agent_client.py,sha256=_1Z7PBksQBcDr2tDNpWPQsFGuOEy9EsNzCSnV4AgZUE,6048
+bridge_state.py,sha256=Bb9GxNPclr-EtajM_X2LoURygZcdZNyfhVJZYf0lJpk,15071
+file_lock.py,sha256=I2zSZ5f8qHLaEpOYvPBze3CzAUTDt3GScBgt573zIyg,2302
+mcp_auth.py,sha256=CLZLPjjRVdPJrw-ta83OWM7gy4U3XUv1CuHYWHD5ZOw,23567
+mcp_client.py,sha256=4ue9bfClyj0xtTtvHprwx0sf-m_mrwd7KlgQKcT03HU,9295
+mcp_protocol.py,sha256=LgDld2__HwmifqjYhhCVXyIb9AsMr5MJvuUWLec2IDY,13906
+notifier_admin.py,sha256=zsCS58VobVuj-0hKp1vG-fZfNn9FUj1zwbiqvSwLAj4,21433
+notifier_gateway.py,sha256=addKjP9u8jLtPgDki724wIj4J4Yo39gdqbdwW2Dvmr4,51046
+provider_auth.py,sha256=kGVv7eDud3PnUWkbZ6yiQ0mV6P8oIMrKqyWMhOTho0Q,7869
+__pycache__/agent_client.cpython-313.pyc,sha256=PM7FxXGodXomi8LJiAOplS81gBaS9nQF9bb3ARpZddI,10246
+__pycache__/bridge_state.cpython-313.pyc,sha256=NGtcF5_yCWXDofKioENEch9frjs22alZvGK7TkXL5ME,27387
+__pycache__/file_lock.cpython-313.pyc,sha256=POpx99YR-OPnfSHNnU_f1x8Yx3uAA1Cqs1vNVUs3fpU,4110
+__pycache__/mcp_auth.cpython-313.pyc,sha256=yN0Va8O0W-Tj8ecsGZWwHP1FdtM5KCDSoQZKFi-cBc0,34969
+__pycache__/mcp_client.cpython-313.pyc,sha256=WQ7_v0Gwac4MMHTZotyOH0UK7hugmIdb7pF9rIX09UY,13720
+__pycache__/mcp_protocol.cpython-313.pyc,sha256=F6lc2_Y-vx69qbRgWrVBG1ZwVcZ1K-Vx6VxXt6zNaWI,13772
+__pycache__/notifier_admin.cpython-313.pyc,sha256=aHFi1zkzR4pZc5hxhr3qdqUnHGW7gCYPUPu8Wu6O4sI,32848
+__pycache__/notifier_gateway.cpython-313.pyc,sha256=DdO-J-qGF3xxZQ7IDyY54kTRCmyPv_5VagDN8q8ha6Y,76699
+__pycache__/provider_auth.cpython-313.pyc,sha256=29leuaeuvUi0YzUZP1m1-bst9wnn0VoqiXfI986meog,11647
+agentforge_telegram_gateway-3.1.0.dist-info/licenses/LICENSE,sha256=4O7bphXVzRuYavtsWzpLGuM3E-fp3HTRna7F4yIfnS4,35184
+agentforge_telegram_gateway-3.1.0.dist-info/METADATA,sha256=XFj3DnsUl3yZKLuwaclaQ76aqUE_VVK3AA4-UskOM9A,10327
+agentforge_telegram_gateway-3.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agentforge_telegram_gateway-3.1.0.dist-info/entry_points.txt,sha256=cyZmZxsnRxJWBLwbY1Ml_QdecGmwQ3fyjaaVc-iT308,200
+agentforge_telegram_gateway-3.1.0.dist-info/top_level.txt,sha256=a35DKJGeuAtoD0x3ld2wouwpbGw5zKJ4gA2ajG_8pJE,115
+agentforge_telegram_gateway-3.1.0.dist-info/RECORD,,

agentforge_telegram_gateway-3.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentforge_telegram_gateway-3.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+agentforge-telegram = agent_client:main
+agentforge-telegram-admin = notifier_admin:main
+agentforge-telegram-gateway = notifier_gateway:main
+agentforge-telegram-mcp = mcp_client:main