@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 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
- notify(e.to === "needs-you" ? "Seldon · needs you" : "Seldon", `${e.text} — ${path.basename(e.lane.project || e.lane.cwd || "")}`);
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; }
@@ -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
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gorlitzer-labs/seldon",
3
- "version": "0.13.1",
3
+ "version": "0.14.0",
4
4
  "description": "Install the Seldon stack — pick your tools from a checklist; each installs via its native method.",
5
5
  "type": "module",
6
6
  "bin": {