agentgram 0.0.0-stage โ 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +201 -2
- package/dist/index.d.ts +717 -0
- package/dist/index.js +3067 -0
- package/dist/index.js.map +1 -0
- package/package.json +58 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Rumuze (https://rumuze.com)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,202 @@
|
|
|
1
|
-
#
|
|
1
|
+
# โก AgentGram
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Turn your Telegram into a live AI Agent Control Room & Ops Mission Control**
|
|
4
|
+
> Control [OpenCode](https://opencode.ai), AI coding agents, and terminal operations on your machine or VPS directly from your phone via Telegram.
|
|
5
|
+
|
|
6
|
+
[](https://www.npmjs.com/package/agentgram)
|
|
7
|
+
[](https://www.npmjs.com/package/agentgram)
|
|
8
|
+
[-success.svg?style=flat-square)](https://www.npmjs.com/package/agentgram)
|
|
9
|
+
[](https://github.com/rumuze/agentgram/actions)
|
|
10
|
+
[](https://github.com/rumuze/agentgram/releases/latest)
|
|
11
|
+
[](LICENSE)
|
|
12
|
+
[](https://www.typescriptlang.org/)
|
|
13
|
+
[](https://nodejs.org)
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="https://www.npmjs.com/package/agentgram"><b>๐ฆ View on NPM</b></a> โข
|
|
17
|
+
<a href="https://github.com/rumuze/agentgram/releases/latest"><b>๐ท๏ธ Releases</b></a> โข
|
|
18
|
+
<a href="#-quick-start"><b>๐ Quick Start</b></a> โข
|
|
19
|
+
<a href="#-telegram-experience"><b>๐ฑ Features</b></a> โข
|
|
20
|
+
<a href="#-frequently-asked-questions-faq"><b>โ FAQ</b></a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## ๐ Why AgentGram?
|
|
26
|
+
|
|
27
|
+
Developers shouldn't be chained to their desks waiting for an AI agent to finish modifying code, executing test suites, or running remote deployment scripts.
|
|
28
|
+
|
|
29
|
+
**AgentGram** turns your phone into a mobile developer cockpit:
|
|
30
|
+
* ๐ฒ **Live Streaming Mission Control:** Real-time progress updates inside a dynamic message (updates smoothly every ~2.5s with tools, steps, and output tails).
|
|
31
|
+
* ๐ **One-Tap Permission Buttons:** Approve or reject file edits and commands with `[ โ
Allow Once ]`, `[ โพ๏ธ Always Allow ]`, or `[ โ Reject ]`.
|
|
32
|
+
* โก **Auto Mode:** Enable full autonomy for routine tasks; safety policies automatically intercept destructive commands.
|
|
33
|
+
* ๐ก๏ธ **Enterprise Prompt Injection Shield:** Multi-layer defense against role hijacking, jailbreaks, delimiter evasion, and malicious prompt injections.
|
|
34
|
+
* ๐ **Pluggable Hexagonal Architecture:** Out-of-the-box support for **Telegram** and **OpenCode** as defaults, plus plug-and-play adapters for alternative channels (**Terminal Console**, **Webhooks**, **Slack/Discord**) and coding engines (**Claude Code**, **Aider**, **Shell CLI**).
|
|
35
|
+
* ๐ **Multi-Machine & Server Ops:** Run operations, SSH jump-host connections, deploy scripts (`pinpoint-go`), and remote log diagnostics directly from your phone.
|
|
36
|
+
* โก **Zero Runtime Dependencies:** 100% Pure Node.js & TypeScript with zero external runtime dependencies. Ultra-lightweight and blazingly fast!
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ๐๏ธ Architecture
|
|
41
|
+
|
|
42
|
+
```mermaid
|
|
43
|
+
flowchart LR
|
|
44
|
+
User["๐ฑ Telegram / Console / Webhook"] <-->|IChannelAdapter| ControlRoom["โก AgentGram Control Room"]
|
|
45
|
+
ControlRoom <-->|IAgentEngine| Engine["๐ค OpenCode / Claude Code / Shell"]
|
|
46
|
+
Engine <-->|Sandboxed Execution| Project["๐ Project Files & Git"]
|
|
47
|
+
ControlRoom <-->|Authorized Ops / SSH| Remote["๐ฅ๏ธ Remote VPS / Server"]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### The Live Experience
|
|
51
|
+
|
|
52
|
+
```text
|
|
53
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
54
|
+
โ โก AgentGram ยท Live Mission Control โ
|
|
55
|
+
โ โ
|
|
56
|
+
โ Agent: ๐ง build (OpenCode) | Mode: ๐ build โ
|
|
57
|
+
โ Channel: ๐ก Telegram Bot โ
|
|
58
|
+
โ Status: ๐ข Executing bash (npm test) โ
|
|
59
|
+
โ Step: 4/12 ยท โณ 14s ยท ๐ 3 files modified โ
|
|
60
|
+
โ โ
|
|
61
|
+
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
|
|
62
|
+
โ > PASS tests/auth.test.js โ
|
|
63
|
+
โ > PASS tests/api.test.js โ
|
|
64
|
+
โ > All 14 tests passing โ
|
|
65
|
+
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
|
|
66
|
+
โ โ
|
|
67
|
+
โ [ โน Stop ] [ ๐ค Diff ] [ ๐ Mode ] โ
|
|
68
|
+
โ [ ๐ Projects ] [ ๐ Language ] โ
|
|
69
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## ๐ Quick Start
|
|
75
|
+
|
|
76
|
+
### 1. Instant Run via NPX (Zero Install)
|
|
77
|
+
|
|
78
|
+
Run immediately in any repository without installing globally:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# Launch interactive pairing wizard (takes 30 seconds)
|
|
82
|
+
npx agentgram init
|
|
83
|
+
|
|
84
|
+
# Start the live control room
|
|
85
|
+
npx agentgram start
|
|
86
|
+
|
|
87
|
+
# Or run in background as a detached daemon
|
|
88
|
+
npx agentgram start --daemon
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. Global Installation
|
|
92
|
+
|
|
93
|
+
Install globally across your development machine or VPS:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npm install -g agentgram
|
|
97
|
+
|
|
98
|
+
# Initialize pairing in any repo
|
|
99
|
+
agentgram init
|
|
100
|
+
|
|
101
|
+
# Start control room
|
|
102
|
+
agentgram start
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 3. Running as a Persistent System Service (Auto-Start on Boot)
|
|
106
|
+
|
|
107
|
+
Want AgentGram to run 24/7 on your machine or cloud VPS?
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# On macOS (installs to ~/Library/LaunchAgents/com.agentgram.plist)
|
|
111
|
+
# On Linux (installs to ~/.config/systemd/user/agentgram.service)
|
|
112
|
+
npx agentgram service install
|
|
113
|
+
|
|
114
|
+
# Check service status
|
|
115
|
+
npx agentgram service status
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### 4. Via Docker Compose (Headless Cloud VPS)
|
|
119
|
+
|
|
120
|
+
Run 24/7 on any cloud server or VPS:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
git clone https://github.com/rumuze/agentgram.git && cd agentgram
|
|
124
|
+
TG_BOT_TOKEN="your_bot_token" TG_ALLOWED_CHAT_ID="your_chat_id" docker compose up -d
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## ๐ฎ Telegram Controls & Commands
|
|
130
|
+
|
|
131
|
+
Once connected, your Telegram chat becomes your project mission control:
|
|
132
|
+
|
|
133
|
+
| Command / Control | Description |
|
|
134
|
+
|---|---|
|
|
135
|
+
| **Live Status Card** | Edits automatically every ~2.5s showing active tools, steps, and output tails |
|
|
136
|
+
| **Interactive Approvals** | Commands requiring approval render inline buttons: `[ โ
Allow Once ]`, `[ โพ๏ธ Always Allow ]`, `[ โ Reject ]` |
|
|
137
|
+
| **Interactive Questions** | Agent questions appear as clickable buttons (single-choice, multi-select, or custom text) |
|
|
138
|
+
| `/mode` | Switch execution mode: `read` (read-only diagnosis), `build` (interactive approval), or `auto` (autonomous execution) |
|
|
139
|
+
| `/agents` | Switch active agent persona on the fly (e.g. `build`, `delegate`, `code-review`) |
|
|
140
|
+
| `/models` | Switch LLM provider and model dynamically |
|
|
141
|
+
| `/diff` | Get a condensed git diff summary of unstaged and staged changes |
|
|
142
|
+
| `/usage` | View token usage, quota renewal countdowns, and rate limits |
|
|
143
|
+
| `/stop` | Immediately interrupt and terminate the running agent process |
|
|
144
|
+
| `/lang` | Toggle between English and Arabic UI |
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## ๐ Security Sandboxing & Prompt Injection Shield
|
|
149
|
+
|
|
150
|
+
AgentGram is engineered with enterprise zero-trust principles:
|
|
151
|
+
|
|
152
|
+
1. **๐ก๏ธ Advanced Prompt Injection Defense:**
|
|
153
|
+
- **Role Hijacking & Jailbreak Defense:** Detects and blocks imperative prompt overrides ("ignore previous instructions", "disregard prior directives", "DAN mode", "system override:", and Arabic variants "ุชุฌุงูู ุงูุชุนููู
ุงุช ุงูุณุงุจูุฉ", "ุฃูุช ุงูุขู ูู ูุถุน ุงูู
ุทูุฑ").
|
|
154
|
+
- **System Boundary Isolation:** Blocks delimiter evasion and token spoofing (`</untrusted-report>`, `<system>`, `<|im_start|>`, `[INST] <<SYS>>`).
|
|
155
|
+
- **Unicode & Obfuscation Stripping:** Normalizes Unicode (NFKC) and strips zero-width/invisible evasion characters (`\u200B`, `\u200C`, `\uFEFF`, `\u2060`) and BiDi overrides (`\u202E`). Recursively inspects base64 payloads.
|
|
156
|
+
- **Data Exfiltration Defense:** Blocks markdown image (``) and HTML link exfiltration vectors.
|
|
157
|
+
2. **๐ Cryptographic Quarantine Envelopes:**
|
|
158
|
+
- External error logs, server alerts, and untrusted inputs are wrapped inside isolated blocks (`<untrusted-report id="...">`) signed with cryptographically random nonces (`secrets.token_hex(8)`).
|
|
159
|
+
3. **๐ซ Execution Blocklist:**
|
|
160
|
+
- Irreversible destructive host wiping is blocked by default (`rm -rf /`, `rm -rf ~`, `mkfs`, `shutdown`, `dd if=`).
|
|
161
|
+
4. **๐ค Single Chat ID Lock:** Every message and inline callback query validates `chat.id == ALLOWED_CHAT_ID`. Unknown users are ignored.
|
|
162
|
+
5. **๐ Loopback & Token Isolation:** OpenCode server runs strictly on `127.0.0.1` with a per-session randomized high-entropy password; bot token is saved with strict `0600` file permissions.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ๐ ๏ธ CLI Reference
|
|
167
|
+
|
|
168
|
+
```text
|
|
169
|
+
agentgram <command> [options]
|
|
170
|
+
npx agentgram <command> [options]
|
|
171
|
+
|
|
172
|
+
COMMANDS:
|
|
173
|
+
init Interactive setup wizard & automatic Telegram pairing
|
|
174
|
+
start Start the control room for the current project
|
|
175
|
+
stop Stop running background daemon
|
|
176
|
+
status Display current daemon, server, and workspace status
|
|
177
|
+
service install Install as persistent background service (macOS launchd / Linux systemd)
|
|
178
|
+
service uninstall Remove persistent background service
|
|
179
|
+
service status Check persistent background service status
|
|
180
|
+
help Display help message
|
|
181
|
+
|
|
182
|
+
OPTIONS:
|
|
183
|
+
--dir <path> Set target project directory (defaults to current working directory)
|
|
184
|
+
--daemon, -d Run in background as a detached process
|
|
185
|
+
--channel <name> Communication channel: telegram (default), console
|
|
186
|
+
--engine <name> AI coding engine: opencode (default), shell, claude, aider
|
|
187
|
+
--version, -v Show version number
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## ๐ค Contributing & Community
|
|
193
|
+
|
|
194
|
+
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## ๐ License
|
|
199
|
+
|
|
200
|
+
Distributed under the **MIT License**. See [LICENSE](LICENSE) for more details.
|
|
201
|
+
|
|
202
|
+
Developed with โค๏ธ by **[Rumuze](https://rumuze.com)**.
|