teleton 0.8.3 → 0.8.4
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/README.md +230 -294
- package/dist/{bootstrap-DDFVEMYI.js → bootstrap-NNEI3Z5H.js} +3 -5
- package/dist/{chunk-OIMAE24Q.js → chunk-5LOHRZYY.js} +15 -4
- package/dist/{chunk-2ERTYRHA.js → chunk-G7PCW63M.js} +10 -10
- package/dist/chunk-JROBTXWY.js +908 -0
- package/dist/{chunk-7MWKT67G.js → chunk-LZQOX6YY.js} +13 -670
- package/dist/{chunk-AERHOXGC.js → chunk-NH2CNRKJ.js} +223 -91
- package/dist/{chunk-33Z47EXI.js → chunk-UMUONAD6.js} +11 -13
- package/dist/cli/index.js +13 -16
- package/dist/index.js +4 -5
- package/dist/{server-N4T7E25M.js → server-AJCOURH7.js} +4 -5
- package/dist/{server-JF6FX772.js → server-WWGVDFPW.js} +5 -6
- package/dist/{setup-server-IX3BFPPH.js → setup-server-VDY64CWW.js} +3 -3
- package/package.json +1 -1
- package/dist/chunk-AEHTQI3H.js +0 -142
- package/dist/chunk-FUNF6H4W.js +0 -251
package/README.md
CHANGED
|
@@ -19,15 +19,23 @@
|
|
|
19
19
|
|
|
20
20
|
### Key Highlights
|
|
21
21
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
22
|
+
<table>
|
|
23
|
+
<tr>
|
|
24
|
+
<td align="center" width="33%"><br><b><ins>Full Telegram Access</ins></b><br>Real user via MTProto,<br>not a bot<br><br></td>
|
|
25
|
+
<td align="center" width="33%"><br><b><ins>Agentic Loop</ins></b><br>Think, act, observe, repeat<br>until shit gets done<br><br></td>
|
|
26
|
+
<td align="center" width="33%"><br><b><ins>15 LLM Providers</ins></b><br>Anthropic, OpenAI, Google, xAI, Groq, and more<br><br></td>
|
|
27
|
+
</tr>
|
|
28
|
+
<tr>
|
|
29
|
+
<td align="center"><br><b><ins>TON Blockchain</ins></b><br>Wallet, jettons, DEX swaps, DNS, NFTs<br><br></td>
|
|
30
|
+
<td align="center"><br><b><ins>Persistent Memory</ins></b><br>Hybrid RAG, vector + keyword, auto-compaction<br><br></td>
|
|
31
|
+
<td align="center"><br><b><ins>125+ Built-in Tools</ins></b><br>Messaging, media, crypto, DEX, DNS, files<br><br></td>
|
|
32
|
+
</tr>
|
|
33
|
+
<tr>
|
|
34
|
+
<td align="center"><br><b><ins>Plugin SDK</ins></b><br>Custom tools, isolated DBs, secrets, hooks<br><br></td>
|
|
35
|
+
<td align="center"><br><b><ins>MCP Client</ins></b><br>Connect any MCP tool server<br><br></td>
|
|
36
|
+
<td align="center"><br><b><ins>Secure by Design</ins></b><br>Sandbox, plugin isolation, prompt defense<br><br></td>
|
|
37
|
+
</tr>
|
|
38
|
+
</table>
|
|
31
39
|
|
|
32
40
|
---
|
|
33
41
|
|
|
@@ -35,39 +43,40 @@
|
|
|
35
43
|
|
|
36
44
|
### Tool Categories
|
|
37
45
|
|
|
38
|
-
| Category | Tools | Description
|
|
39
|
-
| ------------- | ----- |
|
|
40
|
-
| Telegram | 77 |
|
|
41
|
-
| TON & Jettons | 15 |
|
|
42
|
-
| STON.fi DEX | 5 | Swap, quote, search, trending
|
|
43
|
-
| DeDust DEX | 5 | Swap, quote, pools, prices, token analytics
|
|
44
|
-
| TON DNS | 8 |
|
|
45
|
-
| Deals | 5 | P2P escrow
|
|
46
|
-
| Journal | 3 | Trade
|
|
47
|
-
| Web | 2 |
|
|
48
|
-
| Workspace | 6 | Sandboxed file operations
|
|
49
|
-
| Exec | 4 |
|
|
46
|
+
| Category | Tools | Description |
|
|
47
|
+
| ------------- | ----- | -------------------------------------------------------------- |
|
|
48
|
+
| Telegram | 77 | Messages, media, chats, polls, stickers, gifts, stars, stories |
|
|
49
|
+
| TON & Jettons | 15 | Wallet, send/receive, balances, prices, NFTs, DEX router |
|
|
50
|
+
| STON.fi DEX | 5 | Swap, quote, search, trending, pools |
|
|
51
|
+
| DeDust DEX | 5 | Swap, quote, pools, prices, token analytics |
|
|
52
|
+
| TON DNS | 8 | Auctions, bidding, linking, TON Sites, resolution |
|
|
53
|
+
| Deals | 5 | P2P escrow, on-chain verification, anti double-spend |
|
|
54
|
+
| Journal | 3 | Trade logging, P&L tracking, natural language queries |
|
|
55
|
+
| Web | 2 | Search and page extraction via Tavily |
|
|
56
|
+
| Workspace | 6 | Sandboxed file operations, path traversal protection |
|
|
57
|
+
| Exec | 4 | Shell, files, processes (off by default, admin-only) |
|
|
50
58
|
|
|
51
59
|
### Advanced Capabilities
|
|
52
60
|
|
|
53
|
-
| Capability | Description
|
|
54
|
-
| ----------------------- |
|
|
55
|
-
| **Multi-Provider LLM** |
|
|
56
|
-
| **RAG + Hybrid Search** |
|
|
57
|
-
| **Auto-Compaction** | AI
|
|
58
|
-
| **Observation Masking** | Compresses old tool results
|
|
59
|
-
| **Plugin SDK** | Frozen
|
|
60
|
-
| **Smart DEX Router** |
|
|
61
|
-
| **Vision Analysis** | Image understanding via
|
|
62
|
-
| **Scheduled Tasks** |
|
|
63
|
-
| **Message Debouncing** |
|
|
64
|
-
| **Daily Logs** |
|
|
65
|
-
| **Multi-Policy Access** |
|
|
66
|
-
| **Tool RAG** |
|
|
67
|
-
| **MCP Client** |
|
|
68
|
-
| **System Execution** | YOLO mode
|
|
69
|
-
| **TON Proxy** | Browse .ton domains via
|
|
70
|
-
| **
|
|
61
|
+
| Capability | Description |
|
|
62
|
+
| ----------------------- | ------------------------------------------------------------------------ |
|
|
63
|
+
| **Multi-Provider LLM** | 15 providers, hot-swap from dashboard or CLI |
|
|
64
|
+
| **RAG + Hybrid Search** | Vector (sqlite-vec) + keyword (FTS5) fused search |
|
|
65
|
+
| **Auto-Compaction** | AI summarizes old context, saves to `memory/*.md` |
|
|
66
|
+
| **Observation Masking** | Compresses old tool results, saves ~90% context |
|
|
67
|
+
| **Plugin SDK** | Frozen SDK, isolated DBs, secrets, lifecycle hooks |
|
|
68
|
+
| **Smart DEX Router** | Compares STON.fi vs DeDust, picks best rate |
|
|
69
|
+
| **Vision Analysis** | Image understanding via utility model |
|
|
70
|
+
| **Scheduled Tasks** | Cron-like tasks with dependency chains |
|
|
71
|
+
| **Message Debouncing** | Batches rapid group messages, DMs stay instant |
|
|
72
|
+
| **Daily Logs** | Auto session summaries, persisted across resets |
|
|
73
|
+
| **Multi-Policy Access** | DM/group policies (open, allowlist, admin-only, disabled), per-group |
|
|
74
|
+
| **Tool RAG** | Sends only top-K relevant tools per message |
|
|
75
|
+
| **MCP Client** | stdio, SSE, Streamable HTTP, auto-discovery, CLI or WebUI |
|
|
76
|
+
| **System Execution** | YOLO mode: shell, files, processes (off by default, admin-only) |
|
|
77
|
+
| **TON Proxy** | Browse .ton domains via HTTP proxy, auto-installed |
|
|
78
|
+
| **Management API** | HTTPS control plane for remote admin, bootstrap mode, lifecycle control |
|
|
79
|
+
| **Sandboxed Workspace** | Path traversal protection, symlink detection, immutable configs |
|
|
71
80
|
|
|
72
81
|
---
|
|
73
82
|
|
|
@@ -105,35 +114,21 @@ cd teleton-agent
|
|
|
105
114
|
npm install && npm run build
|
|
106
115
|
```
|
|
107
116
|
|
|
108
|
-
### 2. Setup
|
|
117
|
+
### 2. Setup & Start
|
|
109
118
|
|
|
110
119
|
```bash
|
|
111
|
-
teleton setup
|
|
120
|
+
teleton setup --ui
|
|
112
121
|
```
|
|
113
122
|
|
|
114
|
-
The wizard
|
|
115
|
-
- LLM provider selection (15 providers: Anthropic, Claude Code, OpenAI, Google, xAI, Groq, OpenRouter, Moonshot, Mistral, Cerebras, ZAI, MiniMax, Hugging Face, Cocoon, Local)
|
|
116
|
-
- Telegram authentication (API credentials, phone, login code)
|
|
117
|
-
- Access policies (DM/group response rules)
|
|
118
|
-
- Admin user ID
|
|
119
|
-
- TON wallet generation (W5R1 with 24-word mnemonic)
|
|
120
|
-
- Workspace initialization (SOUL.md, STRATEGY.md, SECURITY.md, MEMORY.md)
|
|
123
|
+
The WebUI wizard walks you through everything: LLM provider, Telegram auth (QR code or phone), access policies, admin ID, TON wallet, and workspace files. Once done, the agent starts automatically.
|
|
121
124
|
|
|
122
|
-
|
|
123
|
-
- `~/.teleton/config.yaml` - Main configuration
|
|
124
|
-
- `~/.teleton/wallet.json` - TON wallet (backup mnemonic securely)
|
|
125
|
-
- `~/.teleton/memory.db` - SQLite database (WAL mode, sqlite-vec, FTS5)
|
|
126
|
-
- `~/.teleton/workspace/` - Sandboxed file storage
|
|
127
|
-
|
|
128
|
-
### 3. Start
|
|
129
|
-
|
|
130
|
-
If setup completed without errors, your agent is ready to go:
|
|
125
|
+
To restart later with the dashboard:
|
|
131
126
|
|
|
132
127
|
```bash
|
|
133
|
-
teleton start
|
|
128
|
+
teleton start --webui
|
|
134
129
|
```
|
|
135
130
|
|
|
136
|
-
###
|
|
131
|
+
### 3. Verify
|
|
137
132
|
|
|
138
133
|
Send a message to your agent on Telegram:
|
|
139
134
|
|
|
@@ -198,25 +193,31 @@ ton_proxy: # Optional: .ton domain proxy
|
|
|
198
193
|
|
|
199
194
|
### Supported Models
|
|
200
195
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
196
|
+
70+ models across 15 providers. Defined in `src/config/model-catalog.ts`, shared across CLI, WebUI, and Dashboard.
|
|
197
|
+
|
|
198
|
+
<table>
|
|
199
|
+
<tr>
|
|
200
|
+
<td align="center" width="20%"><br><b>Anthropic</b><br>Claude Opus 4.6<br><br></td>
|
|
201
|
+
<td align="center" width="20%"><br><b>Claude Code</b><br>Auto-detected<br><br></td>
|
|
202
|
+
<td align="center" width="20%"><br><b>OpenAI</b><br>GPT-5<br><br></td>
|
|
203
|
+
<td align="center" width="20%"><br><b>Google</b><br>Gemini 3 Pro<br><br></td>
|
|
204
|
+
<td align="center" width="20%"><br><b>xAI</b><br>Grok 4.1<br><br></td>
|
|
205
|
+
</tr>
|
|
206
|
+
<tr>
|
|
207
|
+
<td align="center"><br><b>Groq</b><br>Llama 4 Maverick<br><br></td>
|
|
208
|
+
<td align="center"><br><b>OpenRouter</b><br>Multi-provider<br><br></td>
|
|
209
|
+
<td align="center"><br><b>Moonshot</b><br>Kimi K2.5<br><br></td>
|
|
210
|
+
<td align="center"><br><b>Mistral</b><br>Devstral<br><br></td>
|
|
211
|
+
<td align="center"><br><b>Cerebras</b><br>Qwen 3 235B<br><br></td>
|
|
212
|
+
</tr>
|
|
213
|
+
<tr>
|
|
214
|
+
<td align="center"><br><b>ZAI</b><br>GLM-5<br><br></td>
|
|
215
|
+
<td align="center"><br><b>MiniMax</b><br>M2.5<br><br></td>
|
|
216
|
+
<td align="center"><br><b>Hugging Face</b><br>DeepSeek V3.2<br><br></td>
|
|
217
|
+
<td align="center"><br><b>Cocoon</b><br>Decentralized (TON)<br><br></td>
|
|
218
|
+
<td align="center"><br><b>Local</b><br>Ollama, vLLM, LM Studio<br><br></td>
|
|
219
|
+
</tr>
|
|
220
|
+
</table>
|
|
220
221
|
|
|
221
222
|
### MCP Servers
|
|
222
223
|
|
|
@@ -251,49 +252,6 @@ When the WebUI is enabled, the **MCP Servers** page lets you add/remove servers,
|
|
|
251
252
|
|
|
252
253
|
Tools are namespaced as `mcp_<server>_<tool>` (e.g. `mcp_filesystem_read_file`). Each server supports `scope` (always, dm-only, group-only, admin-only) and `enabled` toggle.
|
|
253
254
|
|
|
254
|
-
### Web Search & Fetch
|
|
255
|
-
|
|
256
|
-
The agent has two built-in web tools powered by [Tavily](https://tavily.com/) (free tier available):
|
|
257
|
-
|
|
258
|
-
| Tool | Description |
|
|
259
|
-
|------|-------------|
|
|
260
|
-
| `web_search` | Search the web - returns titles, URLs, content snippets, relevance scores. Supports `topic`: general, news, finance |
|
|
261
|
-
| `web_fetch` | Extract readable text from a URL - articles, docs, links shared by users |
|
|
262
|
-
|
|
263
|
-
Both tools require a Tavily API key. Set it via CLI or config:
|
|
264
|
-
|
|
265
|
-
```bash
|
|
266
|
-
teleton config set tavily_api_key
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
Or in `config.yaml`:
|
|
270
|
-
```yaml
|
|
271
|
-
tavily_api_key: "tvly-..."
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
Once configured, the agent can autonomously search the web and read pages when needed to answer questions or verify information.
|
|
275
|
-
|
|
276
|
-
### Managing Config Keys
|
|
277
|
-
|
|
278
|
-
Use `teleton config` to manage optional keys without editing YAML manually:
|
|
279
|
-
|
|
280
|
-
```bash
|
|
281
|
-
# List all configurable keys and their status
|
|
282
|
-
teleton config list
|
|
283
|
-
|
|
284
|
-
# Set a key (prompts interactively if value omitted)
|
|
285
|
-
teleton config set tavily_api_key
|
|
286
|
-
teleton config set tonapi_key AFTWPHSLN3...
|
|
287
|
-
|
|
288
|
-
# View a key (sensitive values are masked)
|
|
289
|
-
teleton config get tavily_api_key
|
|
290
|
-
|
|
291
|
-
# Remove a key
|
|
292
|
-
teleton config unset tavily_api_key
|
|
293
|
-
```
|
|
294
|
-
|
|
295
|
-
Configurable keys: `tavily_api_key`, `tonapi_key`, `telegram.bot_token`, `telegram.bot_username`.
|
|
296
|
-
|
|
297
255
|
### Environment Variables
|
|
298
256
|
|
|
299
257
|
All environment variables override the corresponding `config.yaml` value at startup - useful for Docker and CI:
|
|
@@ -301,95 +259,78 @@ All environment variables override the corresponding `config.yaml` value at star
|
|
|
301
259
|
| Variable | Description | Default |
|
|
302
260
|
|----------|-------------|---------|
|
|
303
261
|
| `TELETON_HOME` | Data directory (config, DB, session) | `~/.teleton` |
|
|
304
|
-
| `TELETON_API_KEY` | LLM API key
|
|
305
|
-
| `
|
|
306
|
-
| `
|
|
307
|
-
| `
|
|
308
|
-
| `
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
262
|
+
| `TELETON_API_KEY` | LLM API key | - |
|
|
263
|
+
| `TELETON_BASE_URL` | Custom LLM base URL | - |
|
|
264
|
+
| `TELETON_TG_API_ID` | Telegram API ID | - |
|
|
265
|
+
| `TELETON_TG_API_HASH` | Telegram API Hash | - |
|
|
266
|
+
| `TELETON_TG_PHONE` | Phone number | - |
|
|
267
|
+
| `TELETON_TAVILY_API_KEY` | Tavily API key for web tools | - |
|
|
268
|
+
| `TELETON_TONAPI_KEY` | TonAPI key | - |
|
|
269
|
+
| `TELETON_TONCENTER_API_KEY` | Toncenter API key | - |
|
|
270
|
+
| `TELETON_WEBUI_ENABLED` | Enable WebUI | `false` |
|
|
271
|
+
| `TELETON_WEBUI_PORT` | WebUI port | `7777` |
|
|
272
|
+
| `TELETON_WEBUI_HOST` | WebUI bind address | `127.0.0.1` |
|
|
273
|
+
| `TELETON_API_ENABLED` | Enable Management API | `false` |
|
|
274
|
+
| `TELETON_API_PORT` | Management API port | `7778` |
|
|
275
|
+
| `TELETON_LOG_LEVEL` | Log level (debug, info, warn, error) | `info` |
|
|
312
276
|
|
|
313
277
|
---
|
|
314
278
|
|
|
315
279
|
## WebUI Dashboard
|
|
316
280
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
**Enable via CLI flag:**
|
|
342
|
-
```bash
|
|
343
|
-
teleton start --webui
|
|
344
|
-
# or specify custom port
|
|
345
|
-
teleton start --webui --webui-port 8080
|
|
346
|
-
```
|
|
281
|
+
Optional web dashboard, localhost only, token auth. Start with `teleton start --webui` or `teleton setup --ui`.
|
|
282
|
+
|
|
283
|
+
<table>
|
|
284
|
+
<tr>
|
|
285
|
+
<td align="center" width="25%"><br><b>Dashboard</b><br>Status, model, tokens, config<br><br></td>
|
|
286
|
+
<td align="center" width="25%"><br><b>Tools</b><br>Toggle, scope, per-module<br><br></td>
|
|
287
|
+
<td align="center" width="25%"><br><b>Plugins</b><br>Marketplace, install, secrets<br><br></td>
|
|
288
|
+
<td align="center" width="25%"><br><b>Soul Editor</b><br>SOUL, SECURITY, STRATEGY, MEMORY<br><br></td>
|
|
289
|
+
</tr>
|
|
290
|
+
<tr>
|
|
291
|
+
<td align="center"><br><b>Memory Search</b><br>Vector + keyword hybrid<br><br></td>
|
|
292
|
+
<td align="center"><br><b>Live Logs</b><br>Real-time SSE streaming<br><br></td>
|
|
293
|
+
<td align="center"><br><b>Workspace</b><br>File browser + editor<br><br></td>
|
|
294
|
+
<td align="center"><br><b>MCP Servers</b><br>Add, remove, configure<br><br></td>
|
|
295
|
+
</tr>
|
|
296
|
+
<tr>
|
|
297
|
+
<td align="center"><br><b>TON Proxy</b><br>Start/stop, auto-install<br><br></td>
|
|
298
|
+
<td align="center"><br><b>Tasks</b><br>Schedule, dependencies, bulk<br><br></td>
|
|
299
|
+
<td align="center"><br><b>Setup Wizard</b><br>QR code + phone auth<br><br></td>
|
|
300
|
+
<td align="center"><br><b>Config</b><br>Provider switch, key validation<br><br></td>
|
|
301
|
+
</tr>
|
|
302
|
+
</table>
|
|
303
|
+
|
|
304
|
+
Auth token is printed at startup. Stored as HttpOnly cookie for 7 days. For remote access:
|
|
347
305
|
|
|
348
|
-
**Enable via environment variable:**
|
|
349
306
|
```bash
|
|
350
|
-
|
|
307
|
+
ssh -L 7777:localhost:7777 user@remote-server
|
|
351
308
|
```
|
|
352
309
|
|
|
353
|
-
###
|
|
310
|
+
### Coding Agent
|
|
354
311
|
|
|
355
|
-
|
|
356
|
-
```
|
|
357
|
-
🌐 WebUI: http://localhost:7777?token=your-token-here
|
|
358
|
-
🔑 Token: your-token-here
|
|
359
|
-
```
|
|
312
|
+
By default, the agent has a **sandboxed workspace** at `~/.teleton/workspace/` with 6 file tools (read, write, delete, rename, list, info). Path traversal protection, symlink detection, and 500 MB quota. Core files (`SOUL.md`, `STRATEGY.md`, `SECURITY.md`) are immutable. Write operations are DM-only.
|
|
360
313
|
|
|
361
|
-
|
|
362
|
-
2. Paste the token from the console (displayed once at startup)
|
|
363
|
-
3. Token is stored as HttpOnly cookie (7 days) for subsequent visits
|
|
314
|
+
**YOLO mode** unlocks full system access (off by default, Linux only):
|
|
364
315
|
|
|
365
|
-
|
|
316
|
+
| Tool | Description |
|
|
317
|
+
|------|-------------|
|
|
318
|
+
| `exec_run` | Execute any bash command |
|
|
319
|
+
| `exec_install` | Install packages (apt, pip, npm, docker) |
|
|
320
|
+
| `exec_service` | Manage systemd services |
|
|
321
|
+
| `exec_status` | Server health (disk, RAM, CPU, uptime) |
|
|
366
322
|
|
|
367
|
-
-
|
|
368
|
-
- **Bearer token auth**: All API routes require authentication (timing-safe comparison)
|
|
369
|
-
- **HttpOnly cookies**: SameSite=Strict, prevents XSS token theft
|
|
370
|
-
- **No persistence**: Runtime changes (like model switches via WebUI) are not saved to config.yaml
|
|
371
|
-
- **For remote access**: Use SSH tunneling or reverse proxy (nginx/caddy) with HTTPS
|
|
323
|
+
All commands are audit-logged with user, command, output, exit code, and duration. Configurable timeout (default 120s), scope (`admin-only`, `allowlist`, `all`), and output capture limit.
|
|
372
324
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
325
|
+
```yaml
|
|
326
|
+
capabilities:
|
|
327
|
+
exec:
|
|
328
|
+
mode: "yolo" # off | yolo
|
|
329
|
+
scope: "admin-only" # admin-only | allowlist | all
|
|
330
|
+
limits:
|
|
331
|
+
timeout: 120 # seconds (1-3600)
|
|
377
332
|
```
|
|
378
333
|
|
|
379
|
-
### Workspace Files
|
|
380
|
-
|
|
381
|
-
The agent's personality and rules are configured via markdown files in `~/.teleton/workspace/`. Default templates are generated during `teleton setup` - you can edit any of them to customize your agent:
|
|
382
|
-
|
|
383
|
-
| File | Purpose | Mutable by Agent |
|
|
384
|
-
|------|---------|-----------------|
|
|
385
|
-
| `SOUL.md` | Personality, tone, behavior guidelines | No |
|
|
386
|
-
| `STRATEGY.md` | Trading rules, buy/sell thresholds | No |
|
|
387
|
-
| `SECURITY.md` | Security principles, threat recognition | No |
|
|
388
|
-
| `MEMORY.md` | Persistent memory (facts, contacts, decisions) | Yes |
|
|
389
|
-
| `memory/*.md` | Session summaries, daily logs (auto-generated) | Yes |
|
|
390
|
-
|
|
391
|
-
> **Tip**: Templates are located in `src/templates/` if installing from source. Edit the workspace copies in `~/.teleton/workspace/` - not the source templates.
|
|
392
|
-
|
|
393
334
|
### Admin Commands
|
|
394
335
|
|
|
395
336
|
All admin commands support `/`, `!`, or `.` prefix:
|
|
@@ -416,6 +357,94 @@ All admin commands support `/`, `!`, or `.` prefix:
|
|
|
416
357
|
|
|
417
358
|
---
|
|
418
359
|
|
|
360
|
+
## Plugins
|
|
361
|
+
|
|
362
|
+
Extend the agent with custom tools. Install from the WebUI marketplace in one click, or drop a `.js` file in `~/.teleton/plugins/`. Loaded at startup, no rebuild needed. See [official example plugins](https://github.com/TONresistor/teleton-plugins).
|
|
363
|
+
|
|
364
|
+
```
|
|
365
|
+
~/.teleton/plugins/
|
|
366
|
+
├── weather.js # Single-file plugin
|
|
367
|
+
└── my-plugin/
|
|
368
|
+
├── index.js # Folder plugin
|
|
369
|
+
├── package.json # npm deps (auto-installed via npm ci)
|
|
370
|
+
└── package-lock.json
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
Plugins export a `tools` function (recommended) or array, plus optional lifecycle hooks:
|
|
374
|
+
|
|
375
|
+
```js
|
|
376
|
+
// ~/.teleton/plugins/weather.js
|
|
377
|
+
|
|
378
|
+
export const manifest = {
|
|
379
|
+
name: "weather",
|
|
380
|
+
version: "1.0.0",
|
|
381
|
+
sdkVersion: "^1.0.0",
|
|
382
|
+
};
|
|
383
|
+
|
|
384
|
+
// Optional: creates an isolated database at ~/.teleton/plugins/data/weather.db
|
|
385
|
+
export function migrate(db) {
|
|
386
|
+
db.exec(`CREATE TABLE IF NOT EXISTS weather_cache (
|
|
387
|
+
city TEXT PRIMARY KEY, data TEXT, cached_at INTEGER
|
|
388
|
+
)`);
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
// Required: tools as a function receiving the Plugin SDK
|
|
392
|
+
export const tools = (sdk) => [
|
|
393
|
+
{
|
|
394
|
+
name: "weather_get",
|
|
395
|
+
description: "Get current weather for a city",
|
|
396
|
+
parameters: {
|
|
397
|
+
type: "object",
|
|
398
|
+
properties: { city: { type: "string", description: "City name" } },
|
|
399
|
+
required: ["city"],
|
|
400
|
+
},
|
|
401
|
+
execute: async (params) => {
|
|
402
|
+
sdk.log.info(`Fetching weather for ${params.city}`);
|
|
403
|
+
const res = await fetch(`https://wttr.in/${params.city}?format=j1`);
|
|
404
|
+
if (!res.ok) return { success: false, error: "City not found" };
|
|
405
|
+
const data = await res.json();
|
|
406
|
+
return { success: true, data: { temp: data.current_condition[0].temp_C } };
|
|
407
|
+
},
|
|
408
|
+
},
|
|
409
|
+
];
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
### Plugin SDK
|
|
413
|
+
|
|
414
|
+
The SDK provides namespaced access to core services:
|
|
415
|
+
|
|
416
|
+
| Namespace | Methods |
|
|
417
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
418
|
+
| `sdk.ton` | **Wallet**: `getAddress()`, `getBalance()`, `getPrice()`, `sendTON()`, `getTransactions()`, `verifyPayment()` |
|
|
419
|
+
| | **Jettons**: `getJettonBalances()`, `getJettonInfo()`, `sendJetton()`, `getJettonWalletAddress()` |
|
|
420
|
+
| | **Analytics**: `getJettonPrice()`, `getJettonHolders()`, `getJettonHistory()` |
|
|
421
|
+
| | **NFT**: `getNftItems()`, `getNftInfo()` |
|
|
422
|
+
| | **DEX** (`sdk.ton.dex`): `quote()`, `swap()`, `quoteSTONfi()`, `quoteDeDust()`, `swapSTONfi()`, `swapDeDust()` |
|
|
423
|
+
| | **DNS** (`sdk.ton.dns`): `check()`, `resolve()`, `getAuctions()`, `startAuction()`, `bid()`, `link()`, `unlink()`, `setSiteRecord()` |
|
|
424
|
+
| | **Signed Transfers**: `createTransfer()`, `createJettonTransfer()`, `getPublicKey()`, `getWalletVersion()` |
|
|
425
|
+
| | **Utils**: `toNano()`, `fromNano()`, `validateAddress()` |
|
|
426
|
+
| `sdk.telegram` | **Messages**: `sendMessage()`, `editMessage()`, `deleteMessage()`, `forwardMessage()`, `pinMessage()`, `searchMessages()`, `scheduleMessage()`, `getScheduledMessages()`, `deleteScheduledMessage()`, `sendScheduledNow()`, `getReplies()` |
|
|
427
|
+
| | **Media**: `sendPhoto()`, `sendVideo()`, `sendVoice()`, `sendFile()`, `sendGif()`, `sendSticker()`, `downloadMedia()` |
|
|
428
|
+
| | **Chat & Users**: `getChatInfo()`, `getUserInfo()`, `resolveUsername()`, `getParticipants()`, `getDialogs()`, `getHistory()` |
|
|
429
|
+
| | **Interactive**: `sendDice()`, `sendReaction()`, `createPoll()`, `createQuiz()` |
|
|
430
|
+
| | **Moderation**: `banUser()`, `unbanUser()`, `muteUser()`, `kickUser()` |
|
|
431
|
+
| | **Stars & Gifts**: `getStarsBalance()`, `sendGift()`, `getAvailableGifts()`, `getMyGifts()`, `getResaleGifts()`, `buyResaleGift()`, `getStarsTransactions()`, `transferCollectible()`, `setCollectiblePrice()`, `getCollectibleInfo()`, `getUniqueGift()`, `getUniqueGiftValue()`, `sendGiftOffer()` |
|
|
432
|
+
| | **Advanced**: `getMe()`, `getMessages()`, `isAvailable()`, `getRawClient()`, `setTyping()`, `sendStory()` |
|
|
433
|
+
| `sdk.bot` | `onInlineQuery()`, `onCallback()`, `onChosenResult()`, `editInlineMessage()`, `keyboard()`, `isAvailable`, `username` |
|
|
434
|
+
| `sdk.secrets` | `get()`, `require()`, `has()` |
|
|
435
|
+
| `sdk.storage` | `get()`, `set()`, `delete()`, `has()`, `clear()` (KV with TTL) |
|
|
436
|
+
| `sdk.db` | Raw `better-sqlite3` database, isolated per plugin |
|
|
437
|
+
| `sdk.config` | Sanitized app config (no API keys) |
|
|
438
|
+
| `sdk.pluginConfig` | Plugin-specific config from `config.yaml` |
|
|
439
|
+
| `sdk.log` | `info()`, `warn()`, `error()`, `debug()` |
|
|
440
|
+
| `sdk.on()` | Register hooks: `message:receive`, `response:before/after/error`, `tool:error`, `prompt:after`, `agent:start/stop` |
|
|
441
|
+
|
|
442
|
+
**Lifecycle hooks**: `migrate(db)`, `start(ctx)`, `stop()`, `onMessage(event)`, `onCallbackQuery(event)`
|
|
443
|
+
|
|
444
|
+
**Security**: all SDK objects are frozen. Plugins never see API keys or other plugins' data.
|
|
445
|
+
|
|
446
|
+
---
|
|
447
|
+
|
|
419
448
|
## Architecture
|
|
420
449
|
|
|
421
450
|
### Tech Stack
|
|
@@ -508,7 +537,12 @@ src/
|
|
|
508
537
|
│ └── model-catalog.ts # Shared model catalog (70+ models across all providers)
|
|
509
538
|
├── webui/ # Optional web dashboard
|
|
510
539
|
│ ├── server.ts # Hono server, auth middleware, static serving
|
|
511
|
-
│ └── routes/ #
|
|
540
|
+
│ └── routes/ # 14 route groups (status, tools, logs, memory, soul, plugins, mcp, tasks, workspace, config, marketplace, hooks, ton-proxy, setup)
|
|
541
|
+
├── api/ # Management API (HTTPS control plane)
|
|
542
|
+
│ ├── server.ts # Hono HTTPS server, TLS, middleware stack
|
|
543
|
+
│ ├── bootstrap.ts # API-only mode (no config needed)
|
|
544
|
+
│ ├── middleware/ # Auth, rate-limit, audit, request-id
|
|
545
|
+
│ └── routes/ # Agent lifecycle, system, logs, memory, auth
|
|
512
546
|
├── constants/ # Centralized limits, timeouts, API endpoints
|
|
513
547
|
├── utils/ # Logger, sanitize, retry, fetch
|
|
514
548
|
├── workspace/ # Path validator (anti-traversal, anti-symlink)
|
|
@@ -580,105 +614,6 @@ npm run test # Vitest
|
|
|
580
614
|
npm run format # Prettier
|
|
581
615
|
```
|
|
582
616
|
|
|
583
|
-
### Plugins
|
|
584
|
-
|
|
585
|
-
Plugins extend the agent with custom tools. Drop a `.js` file or folder in `~/.teleton/plugins/` - loaded at startup, hot-reloaded in dev mode, no rebuild needed. See [official example plugins](https://github.com/TONresistor/teleton-plugins) for complete working examples.
|
|
586
|
-
|
|
587
|
-
```
|
|
588
|
-
~/.teleton/plugins/
|
|
589
|
-
├── weather.js # Single-file plugin
|
|
590
|
-
└── my-plugin/
|
|
591
|
-
├── index.js # Folder plugin
|
|
592
|
-
├── package.json # npm deps (auto-installed via npm ci)
|
|
593
|
-
└── package-lock.json
|
|
594
|
-
```
|
|
595
|
-
|
|
596
|
-
Plugins export a `tools` function (recommended) or array, plus optional lifecycle hooks:
|
|
597
|
-
|
|
598
|
-
```js
|
|
599
|
-
// ~/.teleton/plugins/weather.js
|
|
600
|
-
|
|
601
|
-
export const manifest = {
|
|
602
|
-
name: "weather",
|
|
603
|
-
version: "1.0.0",
|
|
604
|
-
sdkVersion: "^1.0.0",
|
|
605
|
-
};
|
|
606
|
-
|
|
607
|
-
// Optional: creates an isolated database at ~/.teleton/plugins/data/weather.db
|
|
608
|
-
export function migrate(db) {
|
|
609
|
-
db.exec(`CREATE TABLE IF NOT EXISTS weather_cache (
|
|
610
|
-
city TEXT PRIMARY KEY, data TEXT, cached_at INTEGER
|
|
611
|
-
)`);
|
|
612
|
-
}
|
|
613
|
-
|
|
614
|
-
// Required: tools as a function receiving the Plugin SDK
|
|
615
|
-
export const tools = (sdk) => [
|
|
616
|
-
{
|
|
617
|
-
name: "weather_get",
|
|
618
|
-
description: "Get current weather for a city",
|
|
619
|
-
parameters: {
|
|
620
|
-
type: "object",
|
|
621
|
-
properties: { city: { type: "string", description: "City name" } },
|
|
622
|
-
required: ["city"],
|
|
623
|
-
},
|
|
624
|
-
execute: async (params) => {
|
|
625
|
-
sdk.log.info(`Fetching weather for ${params.city}`);
|
|
626
|
-
const res = await fetch(`https://wttr.in/${params.city}?format=j1`);
|
|
627
|
-
if (!res.ok) return { success: false, error: "City not found" };
|
|
628
|
-
const data = await res.json();
|
|
629
|
-
return { success: true, data: { temp: data.current_condition[0].temp_C } };
|
|
630
|
-
},
|
|
631
|
-
},
|
|
632
|
-
];
|
|
633
|
-
```
|
|
634
|
-
|
|
635
|
-
#### Plugin SDK
|
|
636
|
-
|
|
637
|
-
When `tools` is a function, the SDK provides namespaced access to core services:
|
|
638
|
-
|
|
639
|
-
| Namespace | Methods |
|
|
640
|
-
|-----------|---------|
|
|
641
|
-
| `sdk.ton` | **Wallet**: `getAddress()`, `getBalance()`, `getPrice()`, `sendTON()`, `getTransactions()`, `verifyPayment()` |
|
|
642
|
-
| | **Jettons**: `getJettonBalances()`, `getJettonInfo()`, `sendJetton()`, `getJettonWalletAddress()` |
|
|
643
|
-
| | **Analytics**: `getJettonPrice()`, `getJettonHolders()`, `getJettonHistory()` |
|
|
644
|
-
| | **NFT**: `getNftItems()`, `getNftInfo()` |
|
|
645
|
-
| | **DEX** (`sdk.ton.dex`): `quote()`, `swap()`, `quoteSTONfi()`, `quoteDeDust()`, `swapSTONfi()`, `swapDeDust()` |
|
|
646
|
-
| | **DNS** (`sdk.ton.dns`): `check()`, `resolve()`, `getAuctions()`, `startAuction()`, `bid()`, `link()`, `unlink()`, `setSiteRecord()` |
|
|
647
|
-
| | **Signed Transfers** (`sdk.ton`): `createTransfer()`, `createJettonTransfer()`, `getPublicKey()`, `getWalletVersion()` |
|
|
648
|
-
| | **Utils**: `toNano()`, `fromNano()`, `validateAddress()` |
|
|
649
|
-
| `sdk.telegram` | **Messages**: `sendMessage()`, `editMessage()`, `deleteMessage()`, `forwardMessage()`, `pinMessage()`, `searchMessages()`, `scheduleMessage()`, `getScheduledMessages()`, `deleteScheduledMessage()`, `sendScheduledNow()`, `getReplies()` |
|
|
650
|
-
| | **Media**: `sendPhoto()`, `sendVideo()`, `sendVoice()`, `sendFile()`, `sendGif()`, `sendSticker()`, `downloadMedia()` |
|
|
651
|
-
| | **Chat & Users**: `getChatInfo()`, `getUserInfo()`, `resolveUsername()`, `getParticipants()`, `getDialogs()`, `getHistory()` |
|
|
652
|
-
| | **Interactive**: `sendDice()`, `sendReaction()`, `createPoll()`, `createQuiz()` |
|
|
653
|
-
| | **Moderation**: `banUser()`, `unbanUser()`, `muteUser()`, `kickUser()` |
|
|
654
|
-
| | **Stars & Gifts**: `getStarsBalance()`, `sendGift()`, `getAvailableGifts()`, `getMyGifts()`, `getResaleGifts()`, `buyResaleGift()`, `getStarsTransactions()`, `transferCollectible()`, `setCollectiblePrice()`, `getCollectibleInfo()`, `getUniqueGift()`, `getUniqueGiftValue()`, `sendGiftOffer()` |
|
|
655
|
-
| | **Advanced**: `getMe()`, `isAvailable()`, `getRawClient()`, `setTyping()`, `sendStory()` |
|
|
656
|
-
| `sdk.secrets` | `get()`, `require()`, `has()` - 3-tier resolution (env var → secrets file → plugin config) |
|
|
657
|
-
| `sdk.storage` | `get()`, `set()`, `delete()`, `has()`, `clear()` - KV store with TTL support |
|
|
658
|
-
| `sdk.db` | Raw `better-sqlite3` database - isolated per plugin at `~/.teleton/plugins/data/<name>.db` |
|
|
659
|
-
| `sdk.config` | Sanitized app config (no API keys exposed) |
|
|
660
|
-
| `sdk.pluginConfig` | Plugin-specific config from `config.yaml` `plugins:` section |
|
|
661
|
-
| `sdk.log` | `info()`, `warn()`, `error()`, `debug()` - Prefixed logger |
|
|
662
|
-
|
|
663
|
-
**Lifecycle hooks**: `migrate(db)`, `start(ctx)`, `stop()`, `onMessage(event)`, `onCallbackQuery(event)`
|
|
664
|
-
|
|
665
|
-
**Security**: all SDK objects are `Object.freeze()`-ed. Plugins never see API keys or other plugins' data.
|
|
666
|
-
|
|
667
|
-
Plugin config in `config.yaml`:
|
|
668
|
-
```yaml
|
|
669
|
-
plugins:
|
|
670
|
-
weather:
|
|
671
|
-
api_key: "abc123"
|
|
672
|
-
```
|
|
673
|
-
|
|
674
|
-
Backward compatible: plugins can export `tools` as a static array without the SDK.
|
|
675
|
-
|
|
676
|
-
At startup:
|
|
677
|
-
```
|
|
678
|
-
🔌 Plugin "weather": 1 tool registered
|
|
679
|
-
✅ 115 tools loaded (1 from plugins)
|
|
680
|
-
```
|
|
681
|
-
|
|
682
617
|
---
|
|
683
618
|
|
|
684
619
|
## Documentation
|
|
@@ -692,6 +627,7 @@ Full documentation is available in the [`docs/`](docs/) directory:
|
|
|
692
627
|
| [Plugin Development](docs/plugins.md) | Step-by-step plugin tutorial |
|
|
693
628
|
| [Telegram Setup](docs/telegram-setup.md) | API credentials, policies, 2FA, admin commands |
|
|
694
629
|
| [TON Wallet](docs/ton-wallet.md) | Wallet setup, DEX trading, security |
|
|
630
|
+
| [Management API](docs/management-api.md) | HTTPS API, bootstrap mode, authentication, endpoints |
|
|
695
631
|
|
|
696
632
|
---
|
|
697
633
|
|