@rhizogrip/spore-plugin-telegram 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,7 @@
 # @rhizogrip/spore-plugin-telegram
 
 A service that puts your spores in Telegram chats. It runs on the machine the spores are
-on, once per bot, as a systemd user unit, and it is an application against the package:
-everything it does goes through `@rhizogrip/spore`'s exports. It gives spores nothing, so it needs
+on, once per bot, as a systemd user unit. It gives spores nothing, so it needs
 no `spore plugin allow`: `spore service` offers it once it is installed.
 
 ```bash
@@ -36,9 +35,8 @@ passed to a spore's runner.
   message rather than losing one. One Telegram will not take is settled refused, with
   Telegram's reason, and one it still had not taken when its retries ran out is tried again
   after the spore's next turn or the service's next start.
-- **A reply is its own turn's.** The answer, how the turn ended and what it handed back
-  come from the turn as `watchAll` yields it — its record, whose `output` is the answer, and
-  the messages it answered as `asked`.
+- **A reply never mixes turns.** Each chat message gets the answer, the end state and the files
+  of the turn that answered it.
 - **A restart loses nothing.** A turn running when the service stopped finishes into the
   chat's `working…` message; a turn that ended while it was down is posted when it is back.
 - **Nothing fails in silence.** A message a spore refuses is told to the chat; a message
@@ -50,11 +48,11 @@ Write to the bot and the message goes to the spore the chat is mapped to. The bo
 `working…`, shows which tools run as they run, and edits the answer into that message when
 the turn ends. How the turn ended is added only when it makes the answer partial — a wrap
 or a stop. A longer answer than Telegram's 4096 continues in further messages. What the
-turn left in `data/out/` follows as documents; a file over Telegram's 50 MB is named
-instead.
+turn left in `data/out/` follows as documents, up to the 50 a turn hands back, then a line
+counting the rest; a file over Telegram's 50 MB is named instead.
 
-A message sent while a turn runs lands between its rounds, because that is what `send`
-does, and its `working…` message says it was heard. A turn ending in a question posts the
+A message sent while a turn runs lands between its rounds, and its `working…` message says it
+was heard. A turn ending in a question posts the
 question, and the reply answers it. The conversation is the spore's transcript; the service
 keeps none.
 
@@ -84,18 +82,18 @@ except when the turn ended `quiet`, which chose to say nothing. A turn that ende
 answer any other way is told. A spore with no default tells no chat. A default naming a chat
 that does not reach the spore through this bot is refused, and the log says why.
 
-A turn a terminal asked for is the terminal's: `spore send` follows it, and no chat is told.
+A turn started with `spore send` is shown only there; no chat is told.
 
 ## The allow-list is the routing
 
 A bot's `chats` say which chats may talk to it and which spore each reaches, as
 `{ "<chat id>": "<spore>" }`. They are read on every message and followed as they change, so
 a chat is added, moved or removed by editing a line. It lives beside `config.json` and
-`sources.json`: it says who reaches what, and nothing a confined agent reads may say that.
+`sources.json`. Spores cannot read or change it.
 
 While a turn works, its chat is shown what kind of call ran — `reading a file`, `running a
 command`, `asking forgejo` by the source's name, a run of the same one counted, a slow one
-timed, a failed one marked — and never what it was given: a Telegram message leaves the
+timed, a command that exited non-zero given its exit code, a call that failed marked — and never what it was given: a Telegram message leaves the
 machine, and a command line or a path is yours. A chat can ask for the calls themselves:
 
 ```json
@@ -118,24 +116,18 @@ refused chat 148392011 (@alice) — to allow it, add "148392011": "<a spore>" to
 which is also how you learn your own chat id: start with `"chats": {}` and message the bot. A
 group's id is negative, and it is the group you add rather than the people in it.
 
-## What a chat is told
-
-Which tool ran, and whether it worked — never its arguments or its result. On a console
-those are the point; in a chat they are a path or a command line leaving the machine.
-`forward.js` is that rule. The answer and the stop reason cross in full.
-
 ## What it keeps
 
 `$XDG_STATE_HOME/spore/telegram/<bot>/state.json`, one per bot, written whole and renamed into
 place: where it stands in each spore it follows, in that spore's database, and every message a chat sent that no turn has answered
-yet, with the `working…` message its answer goes into. What a turn owes a chat is not kept
-here: it is the spore's outbox. A spore it starts following starts from where it is. Nothing
-is kept in the repository or in the spores' home.
+yet, with the `working…` message its answer goes into. A spore added later is followed from its
+latest turn; earlier answers are not posted. Nothing is kept in the repository or in the spores'
+home.
 
 ## Busy
 
 A turn that would start with no admission slot free is refused, and the chat is told it is
-busy. There is no bound of the service's own: the user's slots are the one bound, shared with every other caller.
+busy. The only limit is the machine's admission slots, which every other caller shares.
 
 ## Running it as a service
 
@@ -146,18 +138,16 @@ spore service enable telegram@triage     # and at every login
 spore service log telegram@triage -f
 ```
 
-`define` runs the service's own start-up checks (`spore-telegram.js <bot> --check`) first, so a
-missing bot file or token is refused there rather than as a unit that keeps failing. The unit it
+`define` first runs the service's start-up checks (`--check`) and refuses a missing bot file or
+token. The unit it
 writes is the template `~/.config/systemd/user/spore-telegram@.service`, marked as spore's, and
 each bot is an instance of it; `spore service` never touches a unit it did not write. `spore
 service rm telegram@<bot>` stops and disables one bot; `spore service rm telegram` stops them all
 and removes the template — each given `--yes` when a bot it stops is running. `spore service ls` says where each service
 stands, and whether lingering is on — without it, user services stop when you log out.
 
-The unit keeps a restart of the service from being a stop of every turn it started
-(`KillMode=process`): their runners are in its control group, and systemd otherwise kills
-the whole group. The service picks them up again from what it saved. A refusal — exit 2 —
-is left refused rather than retried every few seconds.
+Restarting the service does not stop the turns it started (`KillMode=process`). The service
+picks them up again from what it saved. After a refusal (exit 2), systemd does not restart it.
 
 `~/.config/spore/environment` is what the service and every runner it starts need, since a
 systemd user session starts with almost nothing: each bot's token, `PATH`, the provider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Telegram for spores: a bot of yours in chats, each chat reaching its spore, run as a service",
   "author": {
     "name": "Christophe Le Bars",

package/src/forward.js

@@ -71,8 +71,9 @@ export function track (items, event) {
     const item = items.find(i => i.callId === event.callId)
     if (!item) return false
     item.durationMs = event.durationMs
-    item.failed = Boolean(event.error)
-    return item.failed || item.durationMs >= SLOW_MS
+    item.exit = event.outcome === 'exit' ? event.exit : null
+    item.failed = event.outcome === undefined ? Boolean(event.error) : !['ok', 'exit'].includes(event.outcome)
+    return item.failed || item.exit !== null || item.durationMs >= SLOW_MS
   }
   const note = (text) => {
     items.push({ plain: text, detailed: text })
@@ -89,6 +90,7 @@ export function render (items, { detailed = false, last = 6 } = {}) {
   for (const item of items) {
     const text = (detailed ? item.detailed : item.plain) +
       (item.failed ? ' — failed' : '') +
+      (item.exit != null ? ` — exit ${item.exit}` : '') +
       (item.durationMs >= SLOW_MS ? ` — ${Math.round(item.durationMs / 1000)} s` : '')
     const previous = lines.at(-1)
     if (previous?.text === text) previous.count++

package/src/service.js

@@ -8,6 +8,7 @@ import { announce, pieces, render, reply, track, waiting } from './forward.js'
 import { loadState, saveState } from './state.js'
 
 const MAX_DOCUMENT = 50 * 1024 * 1024
+const leftOut = (more) => `and ${more} more file${more === 1 ? '' : 's'} in data/out/, in the spore's workspace`
 const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
 const NOT_MODIFIED = /message is not modified/
 const TAKES_ARGUMENTS = new Set(['extend', 'wrap'])
@@ -77,7 +78,7 @@ export function createService ({ telegram, botFile, statePath, env, log, configF
     for (const part of rest) await attempt(() => telegram.say(chat, part))
   }
 
-  const hand = async (attempt, chat, ws, files) => {
+  const hand = async (attempt, chat, ws, { files, more }) => {
     for (const file of files) {
       const path = resolve(ws, file.path)
       if (!existsSync(path)) {
@@ -91,6 +92,7 @@ export function createService ({ telegram, botFile, statePath, env, log, configF
       }
       await attempt(() => telegram.document(chat, { path, mime: file.mime }, file.path))
     }
+    if (more) await attempt(() => telegram.say(chat, leftOut(more)))
   }
 
   const status = (ws) => {
@@ -316,7 +318,7 @@ export function createService ({ telegram, botFile, statePath, env, log, configF
     const turn = turnsSince(ws, entry.turnNo - 1).ended[0]
     const heard = turn.asked.filter(message => entry.answers.includes(message.inboxNo))
     const text = heard.some(message => message.replyTo) ? reply(turn) : announce({ record: turn.record, asked: heard })
-    const files = (turn.record.produced ?? []).filter(file => file.delivered)
+    const handed = { files: turn.record.deliverables ?? [], more: turn.record.deliverablesMore ?? 0 }
     try {
       await delivery.to(chat, async (attempt) => {
         if (notes.length) {
@@ -324,7 +326,7 @@ export function createService ({ telegram, botFile, statePath, env, log, configF
         } else {
           for (const part of pieces(text)) await attempt(() => telegram.say(chat, part))
         }
-        await hand(attempt, chat, ws, files)
+        await hand(attempt, chat, ws, handed)
       })
     } catch (err) {
       if (err.retryable || stopping.signal.aborted) {