aethralive 0.3.4 → 0.3.5
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 +385 -384
- package/dist/cli.js +6 -2
- package/dist/cli.js.map +1 -1
- package/dist/controls.d.ts +6 -2
- package/dist/controls.js +110 -55
- package/dist/controls.js.map +1 -1
- package/package.json +1 -1
- package/.env.example +0 -13
package/README.md
CHANGED
|
@@ -1,384 +1,385 @@
|
|
|
1
|
-
# AethraLive
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/aethralive)
|
|
4
|
-
[](https://nodejs.org/)
|
|
5
|
-
[](https://github.com/VUPPALA-AKSHAY/AethraLive-)
|
|
6
|
-
[](https://t.me/AethraLiveBot)
|
|
7
|
-
|
|
8
|
-
> **Live coding-agent activity in your private Telegram chat.**
|
|
9
|
-
> Readable streaming replies, expandable thoughts and tool cards, full output attachments, and automatic pause when a run stops. Send the next task from Telegram to your selected OpenCode session. Activity is forwarded without AI summaries.
|
|
10
|
-
|
|
11
|
-
Formerly **CodeRemote**. All users share [@AethraLiveBot](https://t.me/AethraLiveBot), with separate private pairings. The shared relay is hosted on Convex at `https://standing-armadillo-358.convex.site`. The CLI is published as [`aethralive`](https://www.npmjs.com/package/aethralive).
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
## Table of Contents
|
|
16
|
-
|
|
17
|
-
- [Features](#-features)
|
|
18
|
-
- [Quick Start (End Users)](#-quick-start-end-users)
|
|
19
|
-
- [Installation](#-installation)
|
|
20
|
-
- [Supported Agents](#-supported-agents)
|
|
21
|
-
- [Commands](#-commands)
|
|
22
|
-
- [Configuration](#-configuration)
|
|
23
|
-
- [Architecture](#-architecture)
|
|
24
|
-
- [Run Locally (Relay Owner Only)](#-run-locally-relay-owner-only)
|
|
25
|
-
- [Deploy & Validate](#-deploy--validate)
|
|
26
|
-
- [Ghost Mode (Windows)](#-ghost-mode-windows-reversible)
|
|
27
|
-
- [Status Widgets](#-status-widgets)
|
|
28
|
-
- [Presentation & Lifecycle](#-presentation--lifecycle)
|
|
29
|
-
- [Storage, Reconnects & Privacy](#-storage-reconnects--privacy)
|
|
30
|
-
- [Security](#-security)
|
|
31
|
-
- [Limitations](#-limitations)
|
|
32
|
-
- [Contributing](#-contributing)
|
|
33
|
-
- [License](#-license)
|
|
34
|
-
- [Sources](#-sources)
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## ✨ Features
|
|
39
|
-
|
|
40
|
-
- **Readable streaming replies** — assistant text appears directly; IDs, JSON envelopes, model metadata, usage accounting and lifecycle bookkeeping never surface as chat messages.
|
|
41
|
-
- **Expandable thoughts & tool cards** — native Telegram block quotations; tool start, input and completion update the same card.
|
|
42
|
-
- **Full output attachments** — large tool outputs become `.txt` attachments with the actual content; files over 512 KiB split into byte parts.
|
|
43
|
-
- **Automatic pause** — interrupting a run, an unfinished run becoming idle, or a source disconnection cancels pending presentation; the next `Running` event resumes delivery.
|
|
44
|
-
- **Two-way prompting** — send the next task from Telegram to your selected OpenCode session (OpenCode only).
|
|
45
|
-
- **
|
|
46
|
-
- **
|
|
47
|
-
- **
|
|
48
|
-
- **
|
|
49
|
-
- **
|
|
50
|
-
- **
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
aethralive
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
npm.cmd
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
| **
|
|
104
|
-
| **
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
{"agent":"My agent","session":"external","kind":"
|
|
115
|
-
{"agent":"My agent","session":"external","kind":"
|
|
116
|
-
{"agent":"My agent","session":"external","kind":"tool","id":"tool-1","
|
|
117
|
-
{"agent":"My agent","session":"external","kind":"
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
npm.cmd start -- --agent
|
|
129
|
-
npm.cmd start -- --agent
|
|
130
|
-
npm.cmd start --
|
|
131
|
-
npm.cmd start --
|
|
132
|
-
npm.cmd start --
|
|
133
|
-
npm.cmd start --
|
|
134
|
-
npm.cmd start --
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
| `
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
| `
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
|
169
|
-
|
|
|
170
|
-
| `--
|
|
171
|
-
| `--
|
|
172
|
-
| `--
|
|
173
|
-
| `--
|
|
174
|
-
| `--
|
|
175
|
-
| `--
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
│
|
|
187
|
-
│ (OpenCode
|
|
188
|
-
│
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
│
|
|
194
|
-
│
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
│
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
|
222
|
-
|
|
|
223
|
-
| `src/
|
|
224
|
-
| `src/
|
|
225
|
-
| `src/
|
|
226
|
-
| `src/
|
|
227
|
-
| `src/
|
|
228
|
-
| `src/
|
|
229
|
-
| `src/
|
|
230
|
-
| `src/
|
|
231
|
-
| `src/
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
npm.cmd
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
npm.cmd
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
- **
|
|
301
|
-
- **
|
|
302
|
-
- **
|
|
303
|
-
- **
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
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
|
-
|
|
342
|
-
|
|
343
|
-
-
|
|
344
|
-
-
|
|
345
|
-
-
|
|
346
|
-
-
|
|
347
|
-
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
-
|
|
355
|
-
-
|
|
356
|
-
-
|
|
357
|
-
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
- [
|
|
383
|
-
-
|
|
384
|
-
-
|
|
1
|
+
# AethraLive
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/aethralive)
|
|
4
|
+
[](https://nodejs.org/)
|
|
5
|
+
[](https://github.com/VUPPALA-AKSHAY/AethraLive-)
|
|
6
|
+
[](https://t.me/AethraLiveBot)
|
|
7
|
+
|
|
8
|
+
> **Live coding-agent activity in your private Telegram chat.**
|
|
9
|
+
> Readable streaming replies, expandable thoughts and tool cards, full output attachments, and automatic pause when a run stops. Send the next task from Telegram to your selected OpenCode session. Activity is forwarded without AI summaries.
|
|
10
|
+
|
|
11
|
+
Formerly **CodeRemote**. All users share [@AethraLiveBot](https://t.me/AethraLiveBot), with separate private pairings. The shared relay is hosted on Convex at `https://standing-armadillo-358.convex.site`. The CLI is published as [`aethralive`](https://www.npmjs.com/package/aethralive).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Table of Contents
|
|
16
|
+
|
|
17
|
+
- [Features](#-features)
|
|
18
|
+
- [Quick Start (End Users)](#-quick-start-end-users)
|
|
19
|
+
- [Installation](#-installation)
|
|
20
|
+
- [Supported Agents](#-supported-agents)
|
|
21
|
+
- [Commands](#-commands)
|
|
22
|
+
- [Configuration](#-configuration)
|
|
23
|
+
- [Architecture](#-architecture)
|
|
24
|
+
- [Run Locally (Relay Owner Only)](#-run-locally-relay-owner-only)
|
|
25
|
+
- [Deploy & Validate](#-deploy--validate)
|
|
26
|
+
- [Ghost Mode (Windows)](#-ghost-mode-windows-reversible)
|
|
27
|
+
- [Status Widgets](#-status-widgets)
|
|
28
|
+
- [Presentation & Lifecycle](#-presentation--lifecycle)
|
|
29
|
+
- [Storage, Reconnects & Privacy](#-storage-reconnects--privacy)
|
|
30
|
+
- [Security](#-security)
|
|
31
|
+
- [Limitations](#-limitations)
|
|
32
|
+
- [Contributing](#-contributing)
|
|
33
|
+
- [License](#-license)
|
|
34
|
+
- [Sources](#-sources)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## ✨ Features
|
|
39
|
+
|
|
40
|
+
- **Readable streaming replies** — assistant text appears directly; IDs, JSON envelopes, model metadata, usage accounting and lifecycle bookkeeping never surface as chat messages.
|
|
41
|
+
- **Expandable thoughts & tool cards** — native Telegram block quotations; tool start, input and completion update the same card.
|
|
42
|
+
- **Full output attachments** — large tool outputs become `.txt` attachments with the actual content; files over 512 KiB split into byte parts.
|
|
43
|
+
- **Automatic pause** — interrupting a run, an unfinished run becoming idle, or a source disconnection cancels pending presentation; the next `Running` event resumes delivery.
|
|
44
|
+
- **Two-way prompting** — send the next task from Telegram to your selected OpenCode session (OpenCode only).
|
|
45
|
+
- **Native Telegram controls** — the `/` command menu and menu button open paginated inline keyboards for sessions, devices, agents, models, project commands, permissions, forms and Ghost Mode. Button navigation edits one message instead of posting raw command lists.
|
|
46
|
+
- **Multi-device support** — `/devices` and `/use <device-id>` resolve ambiguity across active devices.
|
|
47
|
+
- **Ghost Mode (Windows)** — keep the laptop awake with the lid closed, reversible, with recovery agent.
|
|
48
|
+
- **Status widgets** — native private status cards with expandable session details; automatic fallback.
|
|
49
|
+
- **Shared bot, isolated chats** — one bot token on the relay; each installation gets its own pairing credential and chat mapping.
|
|
50
|
+
- **At-least-once delivery** — local journaling, checkpoints, retry on Telegram throttling, network-resilient resume.
|
|
51
|
+
- **Unicode-safe continuation** — text continues in a new message after 3,600 UTF-16 units, preserving Unicode pairs.
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## 🚀 Quick Start (End Users)
|
|
56
|
+
|
|
57
|
+
Requires **Node.js 24+** and an existing supported coding agent.
|
|
58
|
+
|
|
59
|
+
```powershell
|
|
60
|
+
npx.cmd aethralive
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
1. On first use, send the printed **AL- code** directly to **@AethraLiveBot**. Alternatively, scan the QR/open the link and tap **Start**.
|
|
64
|
+
2. Wait for **Streaming** in the terminal. AethraLive resumes your saved session automatically. On first use it selects a recent main session, preferring the current project.
|
|
65
|
+
3. Keep the watcher and OpenCode running, then send your task in Telegram. Use `/sessions` to choose a different chat.
|
|
66
|
+
|
|
67
|
+
Already paired? The next run resumes without another QR. After `/revoke`, run `npx aethralive` again for a fresh QR/code; the last session selection stays saved. Codes expire after ten minutes and refresh automatically while the terminal waits. A code already used by your own account reports that you are connected instead of asking you to pair again.
|
|
68
|
+
|
|
69
|
+
If Telegram links do not open, search for **@AethraLiveBot** inside Telegram and paste the AL- code; no browser is needed. `/start` reports whether you are connected, paired but offline, or need to pair. On upgrading an existing installation, use `npx aethralive@latest` (inside a source checkout, build the updated source with `npm.cmd run build`).
|
|
70
|
+
|
|
71
|
+
With multiple active devices, send `/devices` and tap the device button. `/menu` opens the full native control panel; long model/session lists use Previous and Next buttons.
|
|
72
|
+
|
|
73
|
+
> End users do **not** need a bot token, a separate bot, a server, or a relay URL. Codex and JSONL currently support **viewing activity only**; Telegram task submission is implemented for OpenCode.
|
|
74
|
+
|
|
75
|
+
Existing installations retain their saved relay. To intentionally move an older local pairing to the shared bot: stop its watcher, run `aethralive unpair`, then pair again with `aethralive connect`. A self-hosted relay remains supported through `--relay`.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 📦 Installation
|
|
80
|
+
|
|
81
|
+
### End users (global)
|
|
82
|
+
|
|
83
|
+
```powershell
|
|
84
|
+
npm.cmd install --global aethralive
|
|
85
|
+
aethralive connect
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The command prints a QR, pairing link, and an AL- code that you can send directly to the bot. `connect` pairs only; run `aethralive` afterward to start the watcher. Each installation gets its own pairing credential and receives only its own agent activity, while all users continue using the same shared bot. Never copy the relay owner's `.env` or `TELEGRAM_BOT_TOKEN` to an end-user machine.
|
|
89
|
+
|
|
90
|
+
### From source (relay owner / contributor)
|
|
91
|
+
|
|
92
|
+
```powershell
|
|
93
|
+
npm.cmd install
|
|
94
|
+
npm.cmd run build
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## 🤖 Supported Agents
|
|
100
|
+
|
|
101
|
+
| Agent | Observe activity | Telegram task submission | Notes |
|
|
102
|
+
| --- | --- | --- | --- |
|
|
103
|
+
| **OpenCode** | ✅ via official client (v2.3.x) | ✅ `session.prompt` | Discovers existing background service; never starts another session. |
|
|
104
|
+
| **Codex** | ✅ experimental local-log adapter | ❌ viewing only | Tails `$CODEX_HOME/sessions` (default `~/.codex/sessions`). |
|
|
105
|
+
| **JSONL** | ✅ neutral integration | ❌ viewing only | Tails a file supplied by another integration. |
|
|
106
|
+
|
|
107
|
+
**OpenCode:** discovers an existing OpenCode v2.3.x background service through the official client. It never starts another agent session. `--opencode-url URL` selects an explicit existing endpoint; `OPENCODE_TOKEN` supplies optional bearer authentication. Source events are live-only and session/descendant scoped. Filesystem/global events without session attribution are not guessed or forwarded.
|
|
108
|
+
|
|
109
|
+
**Codex:** discovers recent logs in `$CODEX_HOME/sessions` (default `~/.codex/sessions`). `--events FILE` selects an explicit Codex log. It tails newly appended assistant messages, exposed reasoning summaries, tool calls/results, and task lifecycle. Encrypted reasoning, instructions and duplicate agent-message records are ignored. This is an experimental local-log adapter verified against installed records, not an official streaming API. Text timing depends on when Codex writes its log; token-by-token output is not guaranteed.
|
|
110
|
+
|
|
111
|
+
**Other agents:** `--agent jsonl` tails a file supplied by another integration. That integration writes the neutral `Activity` contract from `src/activity.ts`, for example:
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{"agent":"My agent","session":"external","kind":"status","id":"run-1","state":"Running"}
|
|
115
|
+
{"agent":"My agent","session":"external","kind":"text","id":"reply-1","phase":"delta","text":"Actual streamed text"}
|
|
116
|
+
{"agent":"My agent","session":"external","kind":"tool","id":"tool-1","title":"Read","input":"src/main.ts","state":"Running"}
|
|
117
|
+
{"agent":"My agent","session":"external","kind":"tool","id":"tool-1","text":"Actual file contents","state":"Completed"}
|
|
118
|
+
{"agent":"My agent","session":"external","kind":"status","id":"run-1","state":"Stopped"}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Kinds are `text`, `thought`, `tool`, `status`, and `notice`. Text phases are `start`, `delta`, and `end`; block IDs identify the same logical message or tool across updates. Lifecycle states include `Running`, `Completed`, `Failed`, `Idle`, `Stopped`, and `Offline`. The source must emit lifecycle signals to enable automatic stop detection. Antigravity and other editors need a source adapter/feed; they are not automatically observable just because they are installed.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## ⌨️ Commands
|
|
126
|
+
|
|
127
|
+
```powershell
|
|
128
|
+
npm.cmd start -- --agent opencode --session SESSION_ID
|
|
129
|
+
npm.cmd start -- --agent codex
|
|
130
|
+
npm.cmd start -- --agent jsonl --events ./agent-events.jsonl --session external
|
|
131
|
+
npm.cmd start -- agents
|
|
132
|
+
npm.cmd start -- connect
|
|
133
|
+
npm.cmd start -- status
|
|
134
|
+
npm.cmd start -- stop
|
|
135
|
+
npm.cmd start -- unpair
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
`npm.cmd start` loads `.env`. Direct `node dist/cli.js` uses shell environment variables. Use `AETHRALIVE_HOME` or `--home DIR` consistently; the default is `~/.aethralive`. Previous CodeRemote state can be reused by pointing this variable to its previous directory. One foreground watcher runs per home directory. `stop` stops monitoring without stopping your agent or revoking pairing. `unpair` revokes this device; Telegram `/revoke` revokes all devices belonging to that sender.
|
|
139
|
+
|
|
140
|
+
### Ghost Mode CLI
|
|
141
|
+
|
|
142
|
+
```powershell
|
|
143
|
+
aethralive ghost on|off|status|install|remove
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`/ghost status` shows the expiry time and the saved originals.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## ⚙️ Configuration
|
|
151
|
+
|
|
152
|
+
### Relay (`.env`)
|
|
153
|
+
|
|
154
|
+
| Variable | Default | Description |
|
|
155
|
+
| --- | --- | --- |
|
|
156
|
+
| `TELEGRAM_BOT_TOKEN` | — | Bot token from BotFather. Relay-only; never distribute. |
|
|
157
|
+
| `TELEGRAM_MODE` | `polling` | `polling` (dev) or `webhook` (production). |
|
|
158
|
+
| `TELEGRAM_WEBHOOK_SECRET` | — | 32–256 URL-safe chars; required for webhook mode. |
|
|
159
|
+
| `AETHRALIVE_WIDGETS` | `true` | Enable native status widgets. |
|
|
160
|
+
| `AETHRALIVE_HOST` | `127.0.0.1` | Bind host. Use `0.0.0.0` only inside a private container/network. |
|
|
161
|
+
| `PORT` | `8787` | HTTP port. |
|
|
162
|
+
| `AETHRALIVE_DB` | `./data/pairing.sqlite` | SQLite database path. |
|
|
163
|
+
| `AETHRALIVE_RELAY` | `http://127.0.0.1:8787` | Relay URL used by the CLI. |
|
|
164
|
+
| `AETHRALIVE_HOME` | `~/.aethralive` | Writable dir for credentials, raw logs, outbox. |
|
|
165
|
+
|
|
166
|
+
### CLI flags
|
|
167
|
+
|
|
168
|
+
| Flag | Description |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `--agent <name>` | `opencode`, `codex`, or `jsonl`. |
|
|
171
|
+
| `--session <id>` | Session id (OpenCode/JSONL). |
|
|
172
|
+
| `--select-session` | Show the terminal picker instead of automatically resuming/selecting a session. |
|
|
173
|
+
| `--events <file>` | Events file (Codex/JSONL). |
|
|
174
|
+
| `--opencode-url <url>` | Explicit OpenCode endpoint. |
|
|
175
|
+
| `--home <dir>` / `AETHRALIVE_HOME` | Override home directory. |
|
|
176
|
+
| `--relay <url>` | Override relay URL. |
|
|
177
|
+
|
|
178
|
+
Environment: `OPENCODE_TOKEN` (optional bearer auth for OpenCode), `CODEX_HOME` (default `~/.codex`), `AETHRALIVE_RELAY`.
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## 🏗 Architecture
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
┌─────────────┐ observe ┌──────────────────┐
|
|
186
|
+
│ Coding │ ────────────────► │ Local Watcher │
|
|
187
|
+
│ Agent │ (OpenCode / │ (CLI, Node 24+) │
|
|
188
|
+
│ (OpenCode, │ Codex / JSONL) │ │
|
|
189
|
+
│ Codex, …) │ └────────┬─────────┘
|
|
190
|
+
└─────────────┘ │ post activity
|
|
191
|
+
▼
|
|
192
|
+
┌──────────────────┐
|
|
193
|
+
│ Relay (HTTP) │
|
|
194
|
+
│ owns bot token │
|
|
195
|
+
│ SQLite state │
|
|
196
|
+
└────────┬─────────┘
|
|
197
|
+
│ Telegram Bot API
|
|
198
|
+
▼
|
|
199
|
+
┌──────────────────┐
|
|
200
|
+
│ Your private │
|
|
201
|
+
│ Telegram chat │
|
|
202
|
+
└──────────────────┘
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
1. The **relay** owns `TELEGRAM_BOT_TOKEN` and is the only Telegram update receiver for the bot.
|
|
206
|
+
2. A **CLI installation** creates a one-time pairing QR/link.
|
|
207
|
+
3. Telegram pairs the installation to a **device credential**.
|
|
208
|
+
4. The **local watcher** observes the user's agent and posts activity to the relay.
|
|
209
|
+
5. The relay maps the authenticated device to its Telegram chat and delivers formatted messages.
|
|
210
|
+
|
|
211
|
+
The relay uses SQLite for device ownership, pairing expiry, revocations, Telegram update offsets, receipts, message IDs, and stream generations. It does not store source code or the bot token in the database.
|
|
212
|
+
|
|
213
|
+
### Shared-bot model
|
|
214
|
+
|
|
215
|
+
All users use the same bot, but each installation has its own pairing credential and chat mapping. The bot token must stay on the relay host. End users should never receive the token or the relay owner's `.env` file.
|
|
216
|
+
|
|
217
|
+
One relay/update receiver must run for a bot. A local `127.0.0.1` relay is only reachable from the same computer. A public multi-user product needs one always-on HTTPS relay URL.
|
|
218
|
+
|
|
219
|
+
### Source map
|
|
220
|
+
|
|
221
|
+
| File | Responsibility |
|
|
222
|
+
| --- | --- |
|
|
223
|
+
| `src/cli.ts` | CLI commands, QR pairing, session selection, watcher and delivery loop |
|
|
224
|
+
| `src/agents.ts`, `src/adapter.ts` | Codex, JSONL and OpenCode source adapters |
|
|
225
|
+
| `src/activity.ts` | Source event to neutral activity conversion |
|
|
226
|
+
| `src/lifecycle.ts` | Active-run state, interruption and stale-delivery cancellation |
|
|
227
|
+
| `src/local.ts` | Local journal, checkpoints and batching |
|
|
228
|
+
| `src/protocol.ts` | Telegram presentation operations and content formatting |
|
|
229
|
+
| `src/relay-main.ts`, `src/relay.ts` | HTTP server, Telegram update receiver and message delivery |
|
|
230
|
+
| `src/store.ts` | SQLite pairing, device and delivery state |
|
|
231
|
+
| `src/telegram.ts`, `src/widget.ts` | Telegram API calls and optional status widget/fallback |
|
|
232
|
+
| `src/test/` | CLI, presentation, relay and widget tests |
|
|
233
|
+
|
|
234
|
+
### Pairing & operating details
|
|
235
|
+
|
|
236
|
+
The CLI requests a pairing, displays a QR and polls with a separate bearer credential. Pairing tokens expire after ten minutes and are single-use. A private Telegram `/start` message completes the pairing. The relay stores hashes of pairing and device credentials; the local client keeps its own device credential in its AethraLive home directory. Protect the local home directory and relay database as sensitive data. `/revoke` revokes the sender's devices; `aethralive unpair` revokes one device. Pairing credentials are not interchangeable with the bot token.
|
|
237
|
+
|
|
238
|
+
`aethralive connect` pairs without selecting an agent. `aethralive` starts watching; use `--agent opencode`, `--agent codex`, or `--agent jsonl --events <file>`. `status` reports local state and `stop` requests watcher shutdown. The default relay is localhost; remote URLs must use HTTPS. An installation tied to a different relay must currently unpair before changing it.
|
|
239
|
+
|
|
240
|
+
### Delivery guarantees & boundaries
|
|
241
|
+
|
|
242
|
+
Text is batched mechanically, without summarizing, and continues into new messages at 3,600 UTF-16 units. Telegram may rate-limit sends or edits, so the watcher retries. Events are journaled locally and delivery is at least once: a crash after Telegram accepts a message but before its receipt is saved can produce a duplicate. Interruptions suppress stale pending presentation while preserving pairing. Telegram and the relay necessarily receive the activity text; avoid sending sensitive project contents if this is unacceptable. No automatic journal-retention policy is implemented.
|
|
243
|
+
|
|
244
|
+
OpenCode discovery observes an existing service and does not require modifying the user's OpenCode configuration. Other agents require an implemented adapter or a compatible JSONL producer.
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## 🏠 Run Locally (Relay Owner Only)
|
|
249
|
+
|
|
250
|
+
Requires Node.js 24+, a supported source, and one Telegram bot from [BotFather](https://t.me/BotFather). The bot and token are configured **once by the relay owner**; do not ask every AethraLive user to create a bot.
|
|
251
|
+
|
|
252
|
+
```powershell
|
|
253
|
+
npm.cmd install
|
|
254
|
+
npm.cmd run build
|
|
255
|
+
# First setup only: do not overwrite an existing configured .env
|
|
256
|
+
Copy-Item .env.example .env
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Save `TELEGRAM_BOT_TOKEN` directly in the relay owner's `.env`. Never commit, embed, or distribute it. Start the single shared relay:
|
|
260
|
+
|
|
261
|
+
```powershell
|
|
262
|
+
npm.cmd run relay
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
In another terminal, with your coding agent running:
|
|
266
|
+
|
|
267
|
+
```powershell
|
|
268
|
+
npm.cmd start
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
On first run, the terminal shows a unique QR code, a clickable Telegram pairing link, and the path to a QR image **before looking for an agent**. Scan the QR or open the link and tap Start. Then choose your agent/session. If `t.me` is inaccessible, open the bot in Telegram and send the exact `/start TOKEN` command printed in the terminal. Pairings expire in ten minutes and work once. Used/expired QR images are removed when the command finishes.
|
|
272
|
+
|
|
273
|
+
Use `npm.cmd start -- connect` (or `aethralive connect` after installation) to pair by itself without an agent installed/running. Already-paired installations show their bot link and keep their existing pairing; no fresh QR is required. Installation does not launch a hidden postinstall process: users explicitly run `npx aethralive` or the installed `aethralive` command.
|
|
274
|
+
|
|
275
|
+
The published CLI defaults to the shared Convex relay. When testing a local owner relay, select it explicitly with `--relay http://127.0.0.1:8787` or `AETHRALIVE_RELAY`. End users do not need BotFather, a bot token, or a second relay.
|
|
276
|
+
|
|
277
|
+
The relay holds the bot token and determines the recipient from the authenticated device. Each user's chat is isolated. Run only one relay/update receiver for a bot.
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## 🚢 Deploy & Validate
|
|
282
|
+
|
|
283
|
+
Use one always-on Node process behind HTTPS, with persistent SQLite storage configured through `AETHRALIVE_DB`. Set `AETHRALIVE_HOST=0.0.0.0` only inside the intended private container/network and proxy it securely. CLI remote URLs must use HTTPS. Monitor `/health`, disk space and sanitized logs. Disable request-body/Authorization logging at the proxy. The relay caps JSON requests at 2 MiB and queued operations at 100.
|
|
284
|
+
|
|
285
|
+
Polling is the development default. For webhooks, set `TELEGRAM_MODE=webhook`, generate `TELEGRAM_WEBHOOK_SECRET` (32–256 URL-safe characters), and explicitly register `/telegram/webhook` through Telegram's `setWebhook` with the same `secret_token` and `allowed_updates: ["message", "callback_query"]`. Callback queries must be acknowledged with `answerCallbackQuery`. Polling refuses to run while a webhook exists. Back up SQLite using SQLite-aware backup or a stopped process.
|
|
286
|
+
|
|
287
|
+
```powershell
|
|
288
|
+
npm.cmd test
|
|
289
|
+
npm.cmd pack
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Tests use temporary databases and fake sources/Telegram transport, including the actual CLI subprocess. They cover readable streaming, Unicode continuation, attachments, lifecycle cancellation, queue races, account isolation, pairing persistence, and alternate adapters. The package excludes local history, tokens, databases, tests and the source transcript. Publishing and hosting are separate operations.
|
|
293
|
+
|
|
294
|
+
---
|
|
295
|
+
|
|
296
|
+
## 👻 Ghost Mode (Windows, reversible)
|
|
297
|
+
|
|
298
|
+
`/ghost on` from Telegram (or `aethralive ghost on`) keeps the laptop awake with the lid closed, so the agent keeps running and the chat stays live. It temporarily sets three Windows power values — lid-close action, automatic sleep timer and automatic hibernate timer — to "do nothing", for **both** plugged-in (AC) and battery (DC). Nothing else changes: no OpenCode configuration, no files, no drivers.
|
|
299
|
+
|
|
300
|
+
- **Originals saved first.** Before changing anything, the current AC and DC values of all three settings are stored in `ghost.json` inside the AethraLive home directory. `/ghost off` restores those exact values and deletes the marker.
|
|
301
|
+
- **Refusal over guessing.** If any current value cannot be read (hidden setting, localized output), Ghost Mode refuses to enable and changes nothing.
|
|
302
|
+
- **Recovery agent.** Two per-user scheduled tasks (logon + every 5 minutes) run `aethralive-ghost-recovery`, which restores the originals when the watcher process is dead, the session expired, or the laptop was shut down mid-session — Windows never reverts `powercfg` changes by itself across a reboot. `aethralive ghost install|remove` manages the tasks; they are installed automatically on the first `/ghost on`.
|
|
303
|
+
- **8-hour expiry.** The marker expires after 8 hours; the recovery agent restores the originals even if the chat is unreachable.
|
|
304
|
+
- **Heat warning.** Every enable reply warns: hard surface, vents clear, never inside a bag — a running laptop with a closed lid builds heat.
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## 📊 Status Widgets
|
|
309
|
+
|
|
310
|
+
Private native status cards show the current agent, latest observed state, device, observation time and expandable session details. The fixed HTML uses Telegram theme variables and system fonts with no network access. `sendWidget` creates a card and `editMessageWidgetData` updates message-specific `chat_data`; no session content is published as shared widget data.
|
|
311
|
+
|
|
312
|
+
Set `AETHRALIVE_WIDGETS=false` on the relay to use a regular editable status message. Unsupported requests (Bot API 400/404) disable widgets for that device and automatically fall back to that readable status message. Re-pair to retry native widgets after upgrading the API. Older Telegram clients may show unsupported media; expandable thought/tool blocks remain independent of widget support. A timestamp is an observation, not a heartbeat.
|
|
313
|
+
|
|
314
|
+
`node scripts/widget-preview.mjs` generates local light/dark previews. Tests check Telegram HTML/compression/state limits and the local details toggle. A real Telegram client is needed to verify native rendering.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## 🎬 Presentation & Lifecycle
|
|
319
|
+
|
|
320
|
+
- Assistant text appears directly. IDs, JSON envelopes, model metadata, usage accounting, and lifecycle bookkeeping never appear as chat messages.
|
|
321
|
+
- Thoughts and tool inputs/results use native expandable Telegram block quotations. Tool start, input, and completion update the same card. End events finalize streamed blocks without repeating their full content.
|
|
322
|
+
- Text continues in a new message after 3,600 UTF-16 units, preserving Unicode pairs. Consecutive queued updates for the same message combine mechanically without summarizing content.
|
|
323
|
+
- Large tool outputs become `.txt` attachments containing actual output. Files larger than 512 KiB split into byte parts; concatenate them numerically to recover the full content. Source HTML is escaped before relay-generated formatting is applied.
|
|
324
|
+
- Interrupting a run, an unfinished run becoming idle, or a source disconnection cancels pending presentation for that run. Late tool/text events are suppressed. Pairing and monitoring remain alive; the next root Running event resumes delivery. Successful completion preserves its final reply.
|
|
325
|
+
- The relay enforces per-device delivery generations and cancels an in-flight request when the generation changes. A message Telegram already accepted cannot be recalled by cancelling its request.
|
|
326
|
+
- Closing a TUI alone does not mean its shared background service stopped working. State reflects the actual agent session, not whether a window is visible.
|
|
327
|
+
- Telegram API throttling remains in effect. Active-run deliveries retry after `retry_after`; interruption supersedes the old queue. Detailed rate-limit tuning is deferred.
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## 💾 Storage, Reconnects & Privacy
|
|
332
|
+
|
|
333
|
+
Raw events are flushed to local `events.jsonl` before delivery. The checkpoint saves presentation state after acknowledgement. An active run can resume delivery through network failures. Interrupting or restarting the watcher intentionally skips old pending presentation while preserving the local archive. A torn final append is repaired; completed corrupt records fail loudly. Unknown agent events stay local until an adapter gives them presentation semantics.
|
|
334
|
+
|
|
335
|
+
The relay SQLite database stores pairing ownership, hashed credentials, revocation, message IDs, operation hashes, delivery generations, and the polling offset. It does not store code or chat-history payloads. The relay handles outgoing contents transiently; Telegram stores delivered messages. Protect local files with OS permissions, including Windows ACLs.
|
|
336
|
+
|
|
337
|
+
Delivery is at least once. A crash after Telegram accepts a message but before its receipt is committed can duplicate that message. Local logs and receipt metadata currently have no automatic retention policy.
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
## 🔒 Security
|
|
342
|
+
|
|
343
|
+
- Never commit `.env`, Telegram tokens, npm tokens, Convex deploy keys, or GitHub credentials.
|
|
344
|
+
- Do not paste secrets into chat.
|
|
345
|
+
- Keep the GitHub repository private unless public source distribution is intentional.
|
|
346
|
+
- Review `npm pack --dry-run` before every npm publish.
|
|
347
|
+
- The bot token must stay on the relay host; end users never receive it.
|
|
348
|
+
- Protect the local home directory and relay database as sensitive data.
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
## ⚠️ Limitations
|
|
353
|
+
|
|
354
|
+
- The original relay is a long-running Node process using native SQLite. A separate Convex implementation now exists and has been deployed without Telegram activation; live end-to-end testing and cutover remain outstanding.
|
|
355
|
+
- PocketBase, Cloudflare Workers, and Trigger.dev are not drop-in deployment targets for the original Node server.
|
|
356
|
+
- Codex and JSONL support viewing activity only; remote prompting is OpenCode-only.
|
|
357
|
+
- No automatic journal-retention policy is implemented.
|
|
358
|
+
- Real incoming Telegram task verification remains outstanding (see `todo.md` / `convex.md`).
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
## 🤝 Contributing
|
|
363
|
+
|
|
364
|
+
1. Fork and clone the repository.
|
|
365
|
+
2. Install dependencies: `npm.cmd install`.
|
|
366
|
+
3. Build: `npm.cmd run build`.
|
|
367
|
+
4. Run tests: `npm.cmd test`.
|
|
368
|
+
5. Open a pull request against `main`.
|
|
369
|
+
|
|
370
|
+
Please keep the GitHub repository private unless public source distribution is intentional, and never commit secrets.
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
## 📄 License
|
|
375
|
+
|
|
376
|
+
License information is available in the repository. (No license file is currently declared in `package.json`.)
|
|
377
|
+
|
|
378
|
+
---
|
|
379
|
+
|
|
380
|
+
## 🙏 Sources
|
|
381
|
+
|
|
382
|
+
- [OpenCode client](https://opencode.ai/docs/build/client/)
|
|
383
|
+
- [Telegram Bot API](https://core.telegram.org/bots/api)
|
|
384
|
+
- npm: [`aethralive`](https://www.npmjs.com/package/aethralive)
|
|
385
|
+
- GitHub: [VUPPALA-AKSHAY/AethraLive-](https://github.com/VUPPALA-AKSHAY/AethraLive-)
|