# Antigravity (AGY) Telegram Bot Service

A high-performance, asynchronous Telegram Bot designed to interact seamlessly with Google Antigravity (`agy` CLI) directly from Telegram with **Native System Authentication** (Zero API Key required).

---

## 🌟 Key Features

- ⚡ **Real-Time Streaming**: Stream tokens, thinking/reasoning process, and tool execution status directly to Telegram with debounce rate-limit protection.
- 🔑 **Native System Authentication**: Uses pre-authenticated local AGY session natively without requiring external Gemini API keys.
- 🧠 **Multi-Model Support**: Switch effortlessly between **Gemini 3.7 Flash**, **Gemini 3.1 Pro**, **Claude Sonnet 4.6**, **GPT-OSS 120B**, and more via interactive inline menus (`/model`).
- 🎯 **Reasoning Effort Control**: Fine-tune depth on the fly with `/effort low`, `/effort medium`, or `/effort high`.
- 📁 **Workspace Control**: Dynamically bind agent workspaces to any directory on the server (`/workspace /path/to/project`).
- 📎 **File & Document Analysis**: Upload code files, images, logs, or documents directly into Telegram for instant inspection and editing.
- 🛑 **Task Cancellation**: Abort long-running generations or tool steps instantly with `/cancel`.
- 🔒 **Enterprise-Grade Security**: Whitelist user IDs, admin-only shell executor (`/exec`), and optional PIN/Password authentication (`/auth <password>`).
- 🔄 **Systemd Service**: Auto-restart on failure, launch on system boot, and manage logs via journalctl.

---

## 📁 Directory Structure

```text
/root/telegram-agy-bot/
├── .env                # Bot credentials & configuration
├── .env.example        # Configuration template
├── bot.py              # Main Telegram Bot application & handlers
├── agy_engine.py       # Native AGY CLI async streaming engine
├── formatters.py       # HTML parsing, message chunking, reasoning styling
├── config.py           # Configuration management
├── manage.sh           # Management utility script
├── sessions.json       # Persisted user sessions & state
└── venv/               # Dedicated Python 3.12 virtual environment
```

---

## 🚀 Quick Setup

### 1. Configure Bot Token
Obtain a bot token from [@BotFather](https://t.me/BotFather) on Telegram and set it:
```bash
/root/telegram-agy-bot/manage.sh set-token "YOUR_TELEGRAM_BOT_TOKEN"
```

### 2. Whitelist Telegram User ID
```bash
# Whitelist your Telegram User ID (get your ID from @userinfobot):
/root/telegram-agy-bot/manage.sh add-user 12345678
```

### 3. Start the Service
```bash
/root/telegram-agy-bot/manage.sh start
```

### 4. Check Status & Logs
```bash
/root/telegram-agy-bot/manage.sh status
/root/telegram-agy-bot/manage.sh logs
```

---

## 🤖 Available Bot Commands

| Command | Description |
| :--- | :--- |
| `/start` | Launch bot, verify access, and display interactive dashboard |
| `/help` | Complete command reference and usage examples |
| `/tasks` or `/schedule` | Interactive Scheduled Tasks & Cron Job Manager |
| `/schedule <timing> \| <prompt>` | Schedule an AI prompt, shell cmd, or reminder |
| `/projects` or `/project` | Interactive Multi-Project Manager |
| `/newproject <name>` | Create & activate an isolated project workspace |
| `/switch <name>` | Switch active project |
| `/backup [name]` | Zip project workspace into <=50MB files and deliver to chat |
| `/new` or `/reset` | Start a clean, fresh conversation session |
| `/lastconv` or `/resume` | Reopen and resume the last or previous conversation |
| `/conversations` or `/convs` | Interactive conversation history browser & switcher |
| `/usage` or `/quota` | Check real-time AGY usage, 5h & 7d quotas |
| `/model` | Interactive inline keyboard to select active AI model |
| `/lang [code\|name]` | Set agent response language (Persian, English, etc.) |
| `/effort [low\|med\|high]` | Configure reasoning depth and effort |
| `/workspace [path]` | View or change the working directory on the server |
| `/status` | View system status, active conversation, model, disk space |
| `/server` or `/hardware` | Real-time RAM, CPU, Swap, Disk storage, and Uptime monitor |
| `/cancel` | Cancel any active generation or agent execution |
| `/invite [user_id]` | (Admin only) Invite user or create invite link |
| `/users` or `/whitelist` | (Admin only) Manage authorized users & invitations |
| `/uninvite <user_id>` | (Admin only) Revoke user authorization |
| `/invitelink` | (Admin only) Generate new single-use or multi-use invite link |
| `/auth <pass>` | Authenticate dynamically with PIN password |
| `/exec <cmd>` | (Admin only) Run shell commands on the server |

---

## ⚙️ Service Management

You can manage the bot service using either `systemctl` or `./manage.sh`:

```bash
# Using systemctl:
systemctl start agy-telegram-bot
systemctl stop agy-telegram-bot
systemctl restart agy-telegram-bot
systemctl status agy-telegram-bot
journalctl -u agy-telegram-bot -f

# Using helper script:
/root/telegram-agy-bot/manage.sh start
/root/telegram-agy-bot/manage.sh restart
/root/telegram-agy-bot/manage.sh logs
```