@gorlitzer-labs/seldon 0.13.1 → 0.14.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/README.md +38 -0
- package/bin/seldon.js +50 -2
- package/lib/telegram.mjs +89 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -168,6 +168,44 @@ seldon serve --allow-reply # let the phone type into agents (off by default
|
|
|
168
168
|
- **Alerts:** while the page is open, the phone buzzes and notifies when an agent starts
|
|
169
169
|
needing you.
|
|
170
170
|
|
|
171
|
+
## On Telegram — `seldon tell`
|
|
172
|
+
|
|
173
|
+
Any agent, on any machine, can message you — text, screenshots, videos, files — and the
|
|
174
|
+
watcher sends its news there too (needs you, failed, finished), so the phone hears about it
|
|
175
|
+
with the app closed.
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
seldon tell "the build is green" # text (long text is split)
|
|
179
|
+
pnpm test 2>&1 | tail -20 | seldon tell # or from stdin
|
|
180
|
+
seldon tell --file out/pitch.mp4 "first cut" # a file, with a caption
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Images show inline, videos play, GIFs animate, audio plays, anything else is a document; a
|
|
184
|
+
bot can send up to 50 MB per file.
|
|
185
|
+
|
|
186
|
+
**Once:** make a bot with [@BotFather](https://t.me/BotFather), store its token in comb —
|
|
187
|
+
`comb set TELEGRAM_BOT_TOKEN` — send your bot `/start`, then `seldon tell --setup` (it finds
|
|
188
|
+
your chat and keeps its id in `~/.seldon/telegram.json`). Stored it under another name?
|
|
189
|
+
`seldon tell --setup --token-name MY_NAME` — seldon remembers it.
|
|
190
|
+
|
|
191
|
+
- **The token never shows.** seldon does not store it: without it in the environment,
|
|
192
|
+
`seldon tell` re-runs itself under `comb run --with TELEGRAM_BOT_TOKEN`, so an agent can send
|
|
193
|
+
without ever seeing it. Every machine with comb synced can send.
|
|
194
|
+
- **Sending only.** Any number of sessions can send through one bot. Writing *to* an agent from
|
|
195
|
+
Telegram (text, or a screenshot from your phone) is Claude Code's own Telegram channel
|
|
196
|
+
(`claude --channels plugin:telegram@claude-plugins-official`), and the same bot works for
|
|
197
|
+
both: sending never competes with its one reader. Run `seldon tell --setup` before starting
|
|
198
|
+
that channel — setup reads the bot's messages once to find your chat.
|
|
199
|
+
|
|
200
|
+
Tell your agents once, in `~/.claude/CLAUDE.md` / `AGENTS.md`:
|
|
201
|
+
|
|
202
|
+
```markdown
|
|
203
|
+
## Telegram
|
|
204
|
+
Send the operator what they'd want to see on their phone with `seldon tell "…"` /
|
|
205
|
+
`seldon tell --file <path> "caption"`: a finished piece of work, a screenshot or video of it,
|
|
206
|
+
a link, a blocker. Short. Never a secret.
|
|
207
|
+
```
|
|
208
|
+
|
|
171
209
|
## Holds — taking turns on shared things
|
|
172
210
|
|
|
173
211
|
Agents on different projects share one machine: one boots the Android emulator, another
|
package/bin/seldon.js
CHANGED
|
@@ -14,6 +14,7 @@ import { startLane, stopLane, resumeLane, removeLane, findLane } from "../lib/ac
|
|
|
14
14
|
import { listMachines, addMachine, fetchLanes, remoteGroups, sshArgs, lastJsonLine } from "../lib/machines.mjs";
|
|
15
15
|
import { notify } from "../lib/notify.mjs";
|
|
16
16
|
import { serve, serveToken, ownerFromStatus } from "../lib/serve.mjs";
|
|
17
|
+
import { tokenName, readChat, writeChat, chatFromUpdates, getUpdates, sendText, sendFile } from "../lib/telegram.mjs";
|
|
17
18
|
import { reportFromEvent, mergeCodexHooks, removeCodexHooks, opencodePlugin } from "../lib/reports.mjs";
|
|
18
19
|
import { buildRows, headline, ago, laneDetail, unlistedAgents, GLYPH } from "../lib/home.mjs";
|
|
19
20
|
import { parseDuration, describe as describeHold, NAME_RE, DEFAULT_FOR_MS } from "../lib/holds.mjs";
|
|
@@ -1433,6 +1434,7 @@ ${C.bold("seldon")} — the agent factory: your projects, and the stack that run
|
|
|
1433
1434
|
${C.bold("seldon up")} start the stack (voice + supervisor) and print where to go
|
|
1434
1435
|
${C.bold("seldon up --tailnet")} expose the voice over HTTPS (tailscale serve) so the mic works on your phone
|
|
1435
1436
|
${C.bold("seldon serve")} [--tailnet] the panel as a phone web app (--allow-reply to answer agents)
|
|
1437
|
+
${C.bold("seldon tell")} "…" message yourself on Telegram (--file to send one; --setup once)
|
|
1436
1438
|
${C.bold("seldon up --brain=X")} pick the voice brain: qwen (in-process) | bonsai (local server); remembered
|
|
1437
1439
|
${C.bold("seldon status")} what's running · ${C.bold("seldon down")} stop it
|
|
1438
1440
|
${C.bold("seldon adopt")} [dir] put an existing repo on the line: foundation docs (never overwritten),
|
|
@@ -1464,6 +1466,14 @@ ${C.bold("seldon")} — the agent factory: your projects, and the stack that run
|
|
|
1464
1466
|
const SELF = fileURLToPath(import.meta.url);
|
|
1465
1467
|
const startWatch = () => startDaemon("seldon-watch", process.execPath, [SELF, "watch"]);
|
|
1466
1468
|
|
|
1469
|
+
// The watcher's news on the phone too, once `seldon tell --setup` has been run. A child
|
|
1470
|
+
// `seldon tell` per event, so the token goes through comb exactly as it does for an agent.
|
|
1471
|
+
function tellInBackground(text) {
|
|
1472
|
+
if (process.env.SELDON_NO_NOTIFY || !readChat()) return;
|
|
1473
|
+
const child = spawn(process.execPath, [process.argv[1], "tell", text], { stdio: "ignore", detached: true });
|
|
1474
|
+
child.on("error", () => {}); child.unref();
|
|
1475
|
+
}
|
|
1476
|
+
|
|
1467
1477
|
async function watchCmd(flags) {
|
|
1468
1478
|
ensureSiblingPath();
|
|
1469
1479
|
const every = parseDuration(flags.interval, 5000) || 5000;
|
|
@@ -1475,7 +1485,9 @@ async function watchCmd(flags) {
|
|
|
1475
1485
|
try { lanes = readLanes().flatMap((g) => g.lanes); } catch (e) { console.log(`${stamp()} read failed: ${e.message}`); }
|
|
1476
1486
|
for (const e of transitions(prev, lanes)) {
|
|
1477
1487
|
console.log(`${stamp()} ${e.text}`);
|
|
1478
|
-
|
|
1488
|
+
const where = path.basename(e.lane.project || e.lane.cwd || "");
|
|
1489
|
+
notify(e.to === "needs-you" ? "Seldon · needs you" : "Seldon", `${e.text} — ${where}`);
|
|
1490
|
+
tellInBackground(`${e.to === "needs-you" ? "⚑" : e.to === "failed" ? "✗" : "✓"} ${e.text} — ${where}`);
|
|
1479
1491
|
}
|
|
1480
1492
|
prev = new Map(lanes.map((l) => [l.key, l.state]));
|
|
1481
1493
|
if (flags.once) return;
|
|
@@ -1554,6 +1566,41 @@ function serveCmd(flags) {
|
|
|
1554
1566
|
} catch (e) { console.log(C.red(" tailscale serve failed: " + ((e.stderr || e.message || "").toString().split("\n")[0]))); }
|
|
1555
1567
|
}
|
|
1556
1568
|
|
|
1569
|
+
// `seldon tell "…"` — message the operator on Telegram, from any agent. The token comes from
|
|
1570
|
+
// comb in the environment: without it, seldon re-runs itself under `comb run`, so the value
|
|
1571
|
+
// is never in an argument, a file seldon writes, or the agent's transcript.
|
|
1572
|
+
async function tellCmd(words, flags) {
|
|
1573
|
+
const fail = (msg) => { console.error(C.red(msg)); process.exitCode = 1; };
|
|
1574
|
+
const name = typeof flags["token-name"] === "string" ? flags["token-name"] : tokenName();
|
|
1575
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return fail(`not a secret name: ${name}`);
|
|
1576
|
+
const token = process.env[name];
|
|
1577
|
+
if (!token) {
|
|
1578
|
+
if (process.env.SELDON_TELL_VIA_COMB) return fail(`comb has no ${name} — store it once: comb set ${name}`);
|
|
1579
|
+
if (!has("comb")) return fail(`no ${name} in the environment, and comb is not installed (seldon install comb)`);
|
|
1580
|
+
const r = spawnSync("comb", ["run", "--with", name, "--", process.execPath, process.argv[1], ...process.argv.slice(2)],
|
|
1581
|
+
{ stdio: "inherit", env: { ...process.env, SELDON_TELL_VIA_COMB: "1" } });
|
|
1582
|
+
process.exitCode = r.status ?? 1;
|
|
1583
|
+
return;
|
|
1584
|
+
}
|
|
1585
|
+
try {
|
|
1586
|
+
if (flags.setup) {
|
|
1587
|
+
const chat = chatFromUpdates(await getUpdates(token));
|
|
1588
|
+
if (!chat) return fail("no message to the bot yet — open your bot in Telegram, send it /start, then run this again");
|
|
1589
|
+
writeChat({ ...chat, ...(name !== "TELEGRAM_BOT_TOKEN" ? { tokenName: name } : {}) });
|
|
1590
|
+
await sendText(token, chat.id, "✓ seldon is connected. Agents can reach you here with: seldon tell \"…\"");
|
|
1591
|
+
return console.log(C.green(`✓ connected to ${chat.name || "your chat"}`) + C.dim(" — try: seldon tell \"hello\""));
|
|
1592
|
+
}
|
|
1593
|
+
const chat = readChat();
|
|
1594
|
+
if (!chat) return fail("not set up yet — send your bot /start in Telegram, then: seldon tell --setup");
|
|
1595
|
+
let text = words.join(" ");
|
|
1596
|
+
if (!text && !process.stdin.isTTY) { for await (const c of process.stdin) text += c; text = text.trim(); }
|
|
1597
|
+
if (typeof flags.file === "string") await sendFile(token, chat.id, flags.file, text);
|
|
1598
|
+
else if (text) await sendText(token, chat.id, text);
|
|
1599
|
+
else return fail('usage: seldon tell "message" · … | seldon tell · seldon tell --file shot.png "caption" · seldon tell --setup');
|
|
1600
|
+
console.log(C.green("✓ sent"));
|
|
1601
|
+
} catch (e) { fail(e.message); }
|
|
1602
|
+
}
|
|
1603
|
+
|
|
1557
1604
|
// `seldon machines` — the other computers the panel shows (bifrost's realms, one list).
|
|
1558
1605
|
function machinesCmd(verb, name, target) {
|
|
1559
1606
|
if (verb === "add") {
|
|
@@ -1680,7 +1727,7 @@ function holdsCmd() {
|
|
|
1680
1727
|
// (`--no-attach`). The value form has to be CONSUMED: filtering out everything starting with
|
|
1681
1728
|
// `--` and keeping the rest as positionals read `seldon go --agent claude` as the project
|
|
1682
1729
|
// named "claude".
|
|
1683
|
-
const VALUE_FLAGS = new Set(["agent", "model", "effort", "name", "port", "pm", "stall", "dir", "for", "wait", "as", "note", "interval", "task", "owner"]);
|
|
1730
|
+
const VALUE_FLAGS = new Set(["agent", "model", "effort", "name", "port", "pm", "stall", "dir", "for", "wait", "as", "note", "interval", "task", "owner", "file", "token-name"]);
|
|
1684
1731
|
function parseArgv(raw) {
|
|
1685
1732
|
const flags = {}, positional = [];
|
|
1686
1733
|
for (let i = 0; i < raw.length; i++) {
|
|
@@ -1735,6 +1782,7 @@ const ids = tokens.filter((id) => byId[id]); // only the valid module
|
|
|
1735
1782
|
if (cmd === "machines") return machinesCmd(tokens[0], tokens[1], tokens[2]);
|
|
1736
1783
|
if (cmd === "lane") return laneCmd(tokens[0], tokens[1], flags);
|
|
1737
1784
|
if (cmd === "serve") return serveCmd(flags);
|
|
1785
|
+
if (cmd === "tell") return tellCmd(tokens, flags);
|
|
1738
1786
|
if (cmd === "setup") return setupCmd(tokens[0], flags);
|
|
1739
1787
|
if (cmd === "panel" || cmd === "board") return panel();
|
|
1740
1788
|
if (cmd && cmd !== "install") { help(); process.exitCode = 1; return; }
|
package/lib/telegram.mjs
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
// `seldon tell` — any agent can message you on Telegram: `seldon tell "the build is green"`.
|
|
2
|
+
//
|
|
3
|
+
// The bot token is a secret and lives in comb (TELEGRAM_BOT_TOKEN): seldon never stores it,
|
|
4
|
+
// prints it or puts it on a command line — `comb run` hands it over in the environment. The
|
|
5
|
+
// chat id is not a secret (it is useless without the token), so `seldon tell --setup` finds it
|
|
6
|
+
// once and keeps it in ~/.seldon/telegram.json.
|
|
7
|
+
//
|
|
8
|
+
// Sending only. Many sessions can send through one bot at once; reading a bot's messages is
|
|
9
|
+
// one-reader-only — Claude Code's own Telegram channel, on the same bot, for one session.
|
|
10
|
+
// --setup reads once (getUpdates), so it runs before that channel starts.
|
|
11
|
+
import { readFileSync, writeFileSync, mkdirSync, statSync } from "node:fs";
|
|
12
|
+
import { join, basename } from "node:path";
|
|
13
|
+
import { SELDON_HOME } from "./agents.mjs";
|
|
14
|
+
|
|
15
|
+
export const TOKEN_NAME = "TELEGRAM_BOT_TOKEN";
|
|
16
|
+
// The comb name the token is stored under: TELEGRAM_BOT_TOKEN unless setup was told another.
|
|
17
|
+
export const tokenName = (chat = readChat()) => chat?.tokenName || TOKEN_NAME;
|
|
18
|
+
export const MAX = 4096; // Telegram's limit per message
|
|
19
|
+
export const MAX_UPLOAD = 50 * 1024 * 1024; // a bot may upload up to 50 MB
|
|
20
|
+
const CONFIG = () => join(SELDON_HOME, "telegram.json");
|
|
21
|
+
|
|
22
|
+
// ---- pure -------------------------------------------------------------------------
|
|
23
|
+
// Long text goes out in pieces, split at a line break when there is one near the limit.
|
|
24
|
+
export function chunks(text, max = MAX) {
|
|
25
|
+
const out = [];
|
|
26
|
+
let s = String(text);
|
|
27
|
+
while (s.length > max) {
|
|
28
|
+
const cut = s.lastIndexOf("\n", max);
|
|
29
|
+
const at = cut > max * 0.5 ? cut : max;
|
|
30
|
+
out.push(s.slice(0, at));
|
|
31
|
+
s = s.slice(at).replace(/^\n/, "");
|
|
32
|
+
}
|
|
33
|
+
if (s.length) out.push(s);
|
|
34
|
+
return out;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// The private chat that last wrote to the bot: whoever just sent it /start during --setup.
|
|
38
|
+
export function chatFromUpdates(updates) {
|
|
39
|
+
const msgs = (updates?.result || []).map((u) => u.message || u.edited_message).filter((m) => m?.chat?.type === "private");
|
|
40
|
+
const m = msgs.at(-1);
|
|
41
|
+
return m ? { id: m.chat.id, name: m.chat.username || m.chat.first_name || null } : null;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
// ---- I/O --------------------------------------------------------------------------
|
|
45
|
+
export function readChat() {
|
|
46
|
+
try { return JSON.parse(readFileSync(CONFIG(), "utf8")); } catch { return null; }
|
|
47
|
+
}
|
|
48
|
+
export function writeChat(chat) {
|
|
49
|
+
mkdirSync(SELDON_HOME, { recursive: true });
|
|
50
|
+
writeFileSync(CONFIG(), JSON.stringify(chat) + "\n", { mode: 0o600 });
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
// Errors name the method and Telegram's description, never the URL (it carries the token).
|
|
54
|
+
async function call(token, method, body) {
|
|
55
|
+
const r = await fetch(`https://api.telegram.org/bot${token}/${method}`, body instanceof FormData
|
|
56
|
+
? { method: "POST", body } : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body || {}) });
|
|
57
|
+
const j = await r.json().catch(() => ({}));
|
|
58
|
+
if (!j.ok) throw new Error(`telegram ${method}: ${j.description || r.status}`);
|
|
59
|
+
return j;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export const getUpdates = (token) => call(token, "getUpdates", { allowed_updates: ["message"] });
|
|
63
|
+
|
|
64
|
+
export async function sendText(token, chatId, text) {
|
|
65
|
+
for (const part of chunks(text)) await call(token, "sendMessage", { chat_id: chatId, text: part, disable_web_page_preview: true });
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
// How a file shows up in the chat: images inline, videos playable, GIFs animated, audio as a
|
|
69
|
+
// track, anything else as a document.
|
|
70
|
+
export function mediaKind(path) {
|
|
71
|
+
const ext = String(path).toLowerCase().split(".").pop();
|
|
72
|
+
if (["png", "jpg", "jpeg", "webp"].includes(ext)) return { method: "sendPhoto", field: "photo" };
|
|
73
|
+
if (["mp4", "mov", "m4v", "webm"].includes(ext)) return { method: "sendVideo", field: "video" };
|
|
74
|
+
if (ext === "gif") return { method: "sendAnimation", field: "animation" };
|
|
75
|
+
if (["mp3", "m4a", "ogg", "wav", "flac"].includes(ext)) return { method: "sendAudio", field: "audio" };
|
|
76
|
+
return { method: "sendDocument", field: "document" };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export async function sendFile(token, chatId, path, caption = "") {
|
|
80
|
+
const size = statSync(path).size;
|
|
81
|
+
if (size > MAX_UPLOAD) throw new Error(`${basename(path)} is ${(size / 1048576).toFixed(0)} MB — Telegram bots can send up to 50 MB`);
|
|
82
|
+
const { method, field } = mediaKind(path);
|
|
83
|
+
const form = new FormData();
|
|
84
|
+
form.set("chat_id", String(chatId));
|
|
85
|
+
if (caption) form.set("caption", caption.slice(0, 1024));
|
|
86
|
+
if (method === "sendVideo") form.set("supports_streaming", "true");
|
|
87
|
+
form.set(field, new Blob([readFileSync(path)]), basename(path));
|
|
88
|
+
await call(token, method, form);
|
|
89
|
+
}
|