@rhizogrip/spore-plugin-telegram 0.2.0 → 0.4.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
@@ -29,37 +28,40 @@ passed to a spore's runner.
 ## What it guarantees
 
 - **A message reaches its spore once.** An update is confirmed to Telegram only after
-  `send` has taken it, and it goes to `send` under `telegram:<update_id>` as its
-  `requestId`, so an update Telegram hands over again is not said twice.
+  `send` has taken it, and it goes to `send` under `telegram:<bot>:<update_id>` as its
+  `requestId`, so an update Telegram hands over again is not said twice, and two bots' updates
+  are never taken for one another.
 - **A finished turn reaches its chat at least once.** What it owes a chat is an entry in the
   spore's outbox, settled only after Telegram accepted it; a crash between the two repeats a
   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 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.
+- **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 is still answered, as a
+  reply to the message it answers; 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
   Telegram will not take is logged with its chat and turn.
 
 ## A turn in a chat
 
-Write to the bot and the message goes to the spore the chat is mapped to. The bot posts
-`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.
-
-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
+Write to the bot and the message goes to the spore the chat is mapped to, which is told who
+wrote it and where — your name and username, the private chat or the group. The bot posts
+`working…` and shows which tools run as they run. When the turn ends, the answer arrives as a new
+message replying to yours, so it notifies you however long the turn took, and `working…` is
+removed; one Telegram will no longer let the bot remove, past 48 hours, says `answered below`. 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, 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, 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.
 
 A turn that ends without reading your message — one that failed before it got there —
-says so in your `working…` message, and the next turn answers it there.
+says so in your `working…` message, and the next turn answers it.
 
 ```
 /status    what the spore is doing, its turns and what they cost, and the running turn's limits
@@ -68,7 +70,8 @@ says so in your `working…` message, and the next turn answers it there.
 /extend wall 30m   give it more — wall, cost or rounds — up to the extend.<limit> its spore.cmk grants
 ```
 
-Only text reaches a spore for now.
+Only text reaches a spore for now: a photo's or a document's caption goes to it, and you are told
+the file did not; a message with nothing written in it is told only text reaches a spore.
 
 ## Turns nobody in a chat started
 
@@ -84,18 +87,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 +121,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.
+`$XDG_STATE_HOME/spore/telegram/<bot>/state.json`, one per bot, mode 0600, 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 its `working…` message. 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 +143,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/bin/spore-telegram.js

@@ -2,82 +2,18 @@
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { loadEnvironment, recordStarted } from '@rhizogrip/spore'
+import { runService } from '@rhizogrip/spore/relay'
 
 import { createTelegram } from '../src/api.js'
-import { allowed, botNames, botPath, botsDir, botToken } from '../src/bots.js'
-import { createService } from '../src/service.js'
-import { statePath } from '../src/state.js'
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-
-const REFUSED = 2
-
-const log = (line) => console.error(`${new Date().toISOString()} ${line}`)
-
-const refuse = (err, hint) => {
-  console.error(`spore-telegram: ${err.message}`)
-  if (err.detail) console.error(`  ${err.detail}`)
-  if (hint) console.error(`  ${hint}`)
-  process.exit(REFUSED)
-}
-
-const bot = process.argv.slice(2).find(arg => !arg.startsWith('--'))
-if (!bot) {
-  refuse(new Error('which bot?'), `spore-telegram <bot> runs ${botsDir()}/<bot>.json${botNames().length ? ` — here: ${botNames().join(', ')}` : ''}`)
-}
-
-const launched = { ...process.env }
-try {
-  loadEnvironment()
-} catch (err) {
-  refuse(err)
-}
-
-let file
-let telegram
-try {
-  file = botPath(bot)
-  allowed(file)
-  telegram = createTelegram(botToken(file, process.env))
-} catch (err) {
-  const variable = `${bot.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BOT_TOKEN`
-  refuse(err, err.type === 'TELEGRAM_NO_BOT'
-    ? `mkdir -p ${botsDir()} && echo '{"token": "$\{${variable}}", "chats": {}}' > ${file}\n  with chats {}, start the bot and message it — the log names every chat it refuses, with its id`
-    : null)
-}
-
-let me
-try {
-  me = await telegram.me()
-} catch (err) {
-  refuse(err, `the token comes from @BotFather, in the variable ${file} names`)
-}
-
-const state = statePath(bot)
-let service
-try {
-  service = createService({ telegram, botFile: file, statePath: state, env: launched, log })
-} catch (err) {
-  refuse(err)
-}
-
-if (process.argv.includes('--check')) {
-  console.log(`spore-telegram ${bot} · @${me.username} · ${file} · state ${state} · ready`)
-  process.exit(0)
-}
-
-const controller = new AbortController()
-for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => controller.abort())
-
-recordStarted(`telegram@${bot}`, { root: ROOT })
-log(`spore-telegram ${bot} · @${me.username} · ${file} · state ${state}`)
-try {
-  await service.run(controller.signal)
-} catch (err) {
-  if (err.type === 'TELEGRAM_CONFLICT') refuse(err, 'one bot token is read by one process — stop the other one, or remove its webhook')
-  log(`stopped — ${err.message}${err.detail ? ` — ${err.detail}` : ''}`)
-  process.exit(1)
-}
-log('stopped')
-process.exit(0)
+import { TELEGRAM, createAdapter } from '../src/adapter.js'
+
+await runService({
+  spec: TELEGRAM,
+  program: 'spore-telegram',
+  root: resolve(dirname(fileURLToPath(import.meta.url)), '..'),
+  open: async ({ bot, credentials }) => {
+    const telegram = createTelegram(credentials.token)
+    const me = await telegram.me()
+    return { adapter: createAdapter({ telegram, bot }), who: `@${me.username}` }
+  }
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizogrip/spore-plugin-telegram",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -28,13 +28,13 @@
     "NOTICE"
   ],
   "peerDependencies": {
-    "@rhizogrip/spore": "^1"
+    "@rhizogrip/spore": "^1.15.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1",
+    "works": "^1.15.0",
     "services": {
       "telegram": {
         "what": "a bot of yours in Telegram chats, each chat reaching its spore",

package/src/adapter.js

@@ -0,0 +1,141 @@
+/**
+ * Telegram for the relay (`@rhizogrip/spore/relay`): the bot file it reads, the long poll that
+ * hears chats, and the Bot API calls that answer them. A chat is a conversation, keyed by its id;
+ * the bot file maps each to the spore it reaches.
+ */
+
+import { SporeError } from '@rhizogrip/spore'
+
+const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
+const NOT_MODIFIED = /message is not modified/
+const SHAPE = '{ "token": "${TRIAGE_BOT_TOKEN}", "chats": { "<chat id>": "<spore>" } }' // eslint-disable-line no-template-curly-in-string
+
+const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
+
+const invalid = (path, problem, detail) => new SporeError(`${path} ${problem}`, { type: 'TELEGRAM_BOT_INVALID', detail })
+
+/**
+ * `{ "<chat id>": "<spore>" }`, or `{ "<chat id>": { "spore": "<spore>", "details": true } }` for a
+ * chat shown what each call does — its command or path — rather than only what kind of call it
+ * is: a Telegram message leaves the machine, so that is a choice made per chat.
+ */
+function routes (raw, path) {
+  if (typeof raw.chats !== 'object' || raw.chats === null || Array.isArray(raw.chats)) {
+    throw invalid(path, 'has no chats', 'chats is { "<chatId>": "<spore>" } — {} while you learn your chat id: the log names every chat it refuses')
+  }
+  const table = new Map()
+  for (const [chat, entry] of Object.entries(raw.chats)) {
+    const spore = typeof entry === 'string' ? entry : entry?.spore
+    const extra = typeof entry === 'object' && entry !== null ? Object.keys(entry).filter(key => !['spore', 'details'].includes(key)) : []
+    if (typeof spore !== 'string' || !spore || extra.length || (typeof entry === 'object' && entry.details !== undefined && typeof entry.details !== 'boolean')) {
+      throw invalid(path, `maps ${chat} to something that is not a spore`, 'each chat is a chat id against the name of a spore it may reach, or { "spore": "<name>", "details": true }')
+    }
+    table.set(chat, { spores: [spore], details: typeof entry === 'object' && entry.details === true })
+  }
+  return table
+}
+
+const HELP = 'Anything you write here goes to the spore. /status says what it is doing; /stop ends the turn it is running; /wrap [10m] asks it to wrap up; /extend wall 30m gives it more, as far as its spore.cmk allows.'
+
+export const TELEGRAM = {
+  kind: 'telegram',
+  label: 'Telegram',
+  noun: 'chat',
+  fields: ['token', 'chats'],
+  credentials: ['token'],
+  stateFields: [],
+  sourceVariables: [],
+  refusals: ['TELEGRAM_CONFLICT'],
+  example: SHAPE,
+  routes,
+  usage: { help: HELP, extend: '/extend wall 30m, /extend cost 1.50 or /extend rounds 20' },
+  limits: { message: 4096, file: 50 * 1024 * 1024, editEveryMs: 2500 },
+  can: { upload: true, remove: true },
+  hint (err, { file, bot }) {
+    if (err.type === 'TELEGRAM_NO_BOT') {
+      const variable = `${bot.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_BOT_TOKEN`
+      return `mkdir -p ${file.slice(0, file.lastIndexOf('/'))} && echo '{"token": "$\{${variable}}", "chats": {}}' > ${file}\n  with chats {}, start the bot and message it — the log names every chat it refuses, with its id`
+    }
+    if (err.type === 'TELEGRAM_FAILED') return `the token comes from @BotFather, in the variable ${file} names`
+    if (err.type === 'TELEGRAM_CONFLICT') return 'one bot token is read by one process — stop the other one, or remove its webhook'
+    return null
+  },
+  refusal: (message, botFile) =>
+    `refused chat ${message.conversation}${message.person.username ? ` (@${message.person.username})` : ''} — to allow it, add "${message.conversation}": "<a spore>" to the chats of ${botFile}`
+}
+
+const FILES = ['photo', 'document', 'video', 'audio', 'voice', 'video_note', 'animation', 'sticker']
+
+export function normalize (update, bot) {
+  const message = update.message
+  if (message?.chat?.id === undefined) return null
+  const text = (message.text ?? message.caption ?? '').trim() || null
+  const command = text?.match(COMMAND)
+  const { first_name: first, last_name: last, username } = message.from
+  return {
+    id: `${bot}:${update.update_id}`,
+    conversation: String(message.chat.id),
+    message: message.message_id,
+    person: { id: String(message.from.id), name: `${[first, last].filter(Boolean).join(' ')}${username ? ` (@${username})` : ''}`, username },
+    where: message.chat.type === 'private' ? 'a private chat on Telegram' : `the Telegram group "${message.chat.title}"`,
+    text,
+    command: command ? { verb: command[1].toLowerCase(), args: command[3] ?? '' } : null,
+    addresses: null,
+    files: FILES.filter(kind => message[kind]).length
+  }
+}
+
+export function createAdapter ({ telegram, bot }) {
+  return {
+    ...TELEGRAM,
+
+    /**
+     * One long poll after another until `signal` aborts. An update is handed to `onMessage` and
+     * awaited before the offset moves past it, since moving it is what confirms the update to
+     * Telegram: a message is confirmed only once the spore has it.
+     */
+    async listen ({ onMessage, signal, log, sleep }) {
+      let offset
+      let backoff = 1000
+      while (!signal.aborted) {
+        let updates
+        try {
+          updates = await telegram.updates(offset, { signal })
+          backoff = 1000
+        } catch (err) {
+          if (signal.aborted) break
+          if (err.context?.status === 409) {
+            throw new SporeError('another process is taking this bot\'s updates', { type: 'TELEGRAM_CONFLICT', detail: err.detail })
+          }
+          if (!err.retryable) throw err
+          log(`poll failed — ${said(err)}`)
+          await sleep(err.context?.retryAfter ? err.context.retryAfter * 1000 : backoff)
+          backoff = Math.min(backoff * 2, 60_000)
+          continue
+        }
+        for (const update of updates) {
+          const message = normalize(update, bot)
+          if (message) await onMessage(message)
+          offset = update.update_id + 1
+        }
+      }
+      if (offset !== undefined) {
+        await telegram.updates(offset, { seconds: 0 }).catch(err => log(`could not confirm the last updates — ${said(err)}`))
+      }
+    },
+
+    post: async (conversation, text, { answering = null } = {}) => (await telegram.say(Number(conversation), text, { answering })).message_id,
+
+    edit: async (conversation, note, text) => {
+      try {
+        await telegram.revise(Number(conversation), note, text)
+      } catch (err) {
+        if (!NOT_MODIFIED.test(err.detail ?? '')) throw err
+      }
+    },
+
+    remove: (conversation, note) => telegram.remove(Number(conversation), note),
+
+    upload: (conversation, file, caption) => telegram.document(Number(conversation), file, caption)
+  }
+}

package/src/api.js

@@ -51,11 +51,18 @@ export function createTelegram (token, { fetchImpl = fetch, base = BASE } = {})
     updates: (offset, { seconds = 30, signal } = {}) =>
       call('getUpdates', { offset, timeout: seconds, allowed_updates: ['message'] }, { timeoutMs: (seconds + 15) * 1000, signal }),
 
-    say: (chat, text) => call('sendMessage', { chat_id: chat, text, link_preview_options: { is_disabled: true } }),
+    say: (chat, text, { answering = null } = {}) => call('sendMessage', {
+      chat_id: chat,
+      text,
+      link_preview_options: { is_disabled: true },
+      ...(answering === null ? {} : { reply_parameters: { message_id: answering, allow_sending_without_reply: true } })
+    }),
 
     revise: (chat, message, text) =>
       call('editMessageText', { chat_id: chat, message_id: message, text, link_preview_options: { is_disabled: true } }),
 
+    remove: (chat, message) => call('deleteMessage', { chat_id: chat, message_id: message }),
+
     document: (chat, { path, mime }, caption) => {
       const form = new FormData()
       form.append('chat_id', String(chat))

package/src/bots.js

@@ -1,116 +0,0 @@
-/**
- * The bots: for each, its token and who may talk to it, and to which spore.
- *
- * One file per bot, `telegram/<bot>.json` beside `config.json`, because a bot is a face a spore
- * shows on Telegram and each runs as a service instance of its own. The routing is in the same
- * file because a bot needs it anyway: a chat absent from it is refused. Beside `config.json` and
- * `sources.json`, for the same reason — it says who reaches what, and nothing a confined agent can
- * read may say that. The token is `${VAR}`, from the environment, never kept in the file.
- *
- * Spores keep the names a person gave them. Deriving one per chat would forbid what the routing
- * allows: two chats on one spore, a spore reached through two bots, or a chat moved to another
- * spore by editing a line. Restricting any of it is policy, and policy about chats lives above
- * spore.
- */
-
-import { existsSync, readFileSync, readdirSync } from 'node:fs'
-import { basename, dirname, join, resolve } from 'node:path'
-
-import { CONFIG_FILE, SporeError } from '@rhizogrip/spore'
-
-export const BOTS_DIR = 'telegram'
-const NAME = /^[a-z0-9][a-z0-9._-]*$/i
-const VARIABLE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/
-
-export const botsDir = (configFile = CONFIG_FILE) => resolve(dirname(configFile), BOTS_DIR)
-
-export function botPath (name, configFile = CONFIG_FILE) {
-  if (!NAME.test(name)) {
-    throw new SporeError(`"${name}" cannot be a bot's name`, { type: 'TELEGRAM_BOT_INVALID', detail: 'letters, digits, ., - and _' })
-  }
-  return join(botsDir(configFile), `${name}.json`)
-}
-
-export function botNames (configFile = CONFIG_FILE) {
-  const dir = botsDir(configFile)
-  if (!existsSync(dir)) return []
-  return readdirSync(dir).filter(file => file.endsWith('.json')).map(file => basename(file, '.json')).sort()
-}
-
-function read (path) {
-  if (!existsSync(path)) {
-    throw new SporeError(`no ${path}`, {
-      type: 'TELEGRAM_NO_BOT',
-      detail: 'it names the bot\'s token and which chats may talk to it, as { "token": "${VAR}", "chats": { "<chatId>": "<spore>" } } — a bot with no chats is an open door to something that spends money' // eslint-disable-line no-template-curly-in-string
-    })
-  }
-  let raw
-  try {
-    raw = JSON.parse(readFileSync(path, 'utf8'))
-  } catch (err) {
-    throw new SporeError(`${path} is not readable JSON`, { type: 'TELEGRAM_BOT_INVALID', detail: err.message })
-  }
-  const unknown = Object.keys(raw ?? {}).filter(key => !['token', 'chats'].includes(key))
-  if (unknown.length) throw new SporeError(`${path} has a field spore does not know — ${unknown.join(', ')}`, { type: 'TELEGRAM_BOT_INVALID', detail: 'a bot has a token and chats' })
-  if (typeof raw.token !== 'string' || !VARIABLE.test(raw.token)) {
-    throw new SporeError(`${path} has no token spore can read`, {
-      type: 'TELEGRAM_BOT_INVALID',
-      detail: 'token names the variable holding the token from @BotFather, as "${REVIEWER_BOT_TOKEN}", set in environment beside config.json' // eslint-disable-line no-template-curly-in-string
-    })
-  }
-  if (typeof raw.chats !== 'object' || raw.chats === null || Array.isArray(raw.chats)) {
-    throw new SporeError(`${path} has no chats`, {
-      type: 'TELEGRAM_BOT_INVALID',
-      detail: 'chats is { "<chatId>": "<spore>" } — {} while you learn your chat id: the log names every chat it refuses'
-    })
-  }
-  return raw
-}
-
-/**
- * `{ "<chatId>": "<spore>" }`, or `{ "<chatId>": { "spore": "<spore>", "details": true } }` for a
- * chat shown what each call does — its command or path — rather than only what kind of call it
- * is: a Telegram message leaves the machine, so that is a choice made per chat. Read on every
- * update rather than held: adding a chat should not need a restart.
- */
-function entries (path) {
-  return Object.entries(read(path).chats).map(([chat, entry]) => {
-    const spore = typeof entry === 'string' ? entry : entry?.spore
-    const extra = typeof entry === 'object' && entry !== null ? Object.keys(entry).filter(key => !['spore', 'details'].includes(key)) : []
-    if (typeof spore !== 'string' || !spore || extra.length || (typeof entry === 'object' && entry.details !== undefined && typeof entry.details !== 'boolean')) {
-      throw new SporeError(`${path} maps ${chat} to something that is not a spore`, {
-        type: 'TELEGRAM_BOT_INVALID',
-        detail: 'each chat is a chat id against the name of a spore it may reach, or { "spore": "<name>", "details": true }'
-      })
-    }
-    return { chat, spore, details: typeof entry === 'object' && entry.details === true }
-  })
-}
-
-export function allowed (path) {
-  return Object.fromEntries(entries(path).map(({ chat, spore }) => [chat, spore]))
-}
-
-/** The chats shown each call's command or path, by id. */
-export function detailedChats (path) {
-  return new Set(entries(path).filter(entry => entry.details).map(entry => Number(entry.chat)))
-}
-
-export const tokenVariable = (path) => VARIABLE.exec(read(path).token)[1]
-
-export function botToken (path, env) {
-  const variable = tokenVariable(path)
-  if (!env[variable]) {
-    throw new SporeError(`${path} wants $${variable}, which is not set`, {
-      type: 'TELEGRAM_NO_TOKEN',
-      detail: 'the token from @BotFather goes in environment beside config.json; it never reaches a spore'
-    })
-  }
-  return env[variable]
-}
-
-/**
- * Every variable a bot here keeps its token in: none of them is passed to a spore's runner. A bot
- * file that cannot be read is refused rather than skipped, since its token would pass unnoticed.
- */
-export const tokenVariables = (configFile = CONFIG_FILE) => botNames(configFile).map(name => tokenVariable(botPath(name, configFile)))

package/src/delivery.js

@@ -1,28 +0,0 @@
-export function createDelivery ({ sleep, signal, now = Date.now, giveUpMs = 10 * 60_000 }) {
-  const chains = new Map()
-
-  const attempt = async (step) => {
-    const started = now()
-    let backoff = 1000
-    for (;;) {
-      try {
-        return await step()
-      } catch (err) {
-        if (!err.retryable || signal.aborted || now() - started > giveUpMs) throw err
-        const after = err.context?.retryAfter
-        await sleep(after ? after * 1000 : backoff)
-        backoff = Math.min(backoff * 2, 60_000)
-      }
-    }
-  }
-
-  const to = (chat, work) => {
-    const next = (chains.get(chat) ?? Promise.resolve()).then(() => work(attempt))
-    const settled = next.catch(() => {})
-    chains.set(chat, settled)
-    settled.then(() => { if (chains.get(chat) === settled) chains.delete(chat) })
-    return next
-  }
-
-  return { to, attempt }
-}

package/src/forward.js

@@ -1,136 +0,0 @@
-/**
- * What a chat is told while a turn works: what kind of call ran — reading a file, running a
- * command, asking a source by the name its host gave it — and never what it was given or what
- * came back. A Telegram message leaves the machine, and a command line or a path is the
- * operator's. A chat whose allow-list entry says `details` is shown the command or the path as
- * well: that is a choice made per chat. The answer and the stop reason cross in full.
- */
-
-export const MAX_MESSAGE = 4096
-
-const PLAIN_ENDINGS = new Set(['answer', 'question'])
-
-const LONGEST = 70
-const SLOW_MS = 5000
-
-// Spore's own programs, by the variable an agent runs them through, and what each is called.
-const PROGRAMS = [
-  [/^node\s+"?\$SPORE_SOURCE"?\s*/, 'source '],
-  [/^node\s+"?\$SPORE_FANOUT"?\s*/, 'fanout '],
-  [/^"?\$SPORE_BROWSER"?\s*/, 'browser '],
-  [/^"?\$SPORE_BRAVE"?\s*/, 'search '],
-  [/^"?\$SPORE_SPAWN"?\s*/, 'spawn '],
-  [/^"?\$SPORE_SQL"?\s*/, 'sql ']
-]
-
-const firstLine = (text) => String(text ?? '').split('\n')[0].replace(/\s+/g, ' ').trim()
-const cut = (text) => (text.length > LONGEST ? `${text.slice(0, LONGEST - 1)}…` : text)
-
-function kind (line) {
-  const source = /^node\s+"?\$SPORE_SOURCE"?\s+([\w.-]+)/.exec(line)
-  if (source) return `asking ${source[1]}`
-  if (/^"?\$SPORE_BROWSER/.test(line)) return 'using the browser'
-  if (/^"?\$SPORE_BRAVE/.test(line)) return 'searching the web'
-  if (/^(node\s+"?\$SPORE_FANOUT|"?\$SPORE_SPAWN)/.test(line)) return 'starting sub-agents'
-  if (/^"?\$SPORE_SQL/.test(line)) return 'reading its records'
-  return 'running a command'
-}
-
-function command (text) {
-  const line = firstLine(text)
-  const plain = kind(line)
-  const program = PROGRAMS.find(([pattern]) => pattern.test(line))
-  const detailed = program ? cut(line.replace(program[0], program[1]).trim()) : `running ${cut(line)}`
-  return { plain, detailed }
-}
-
-/** A call as a chat is told it, plainly and in detail, or null for one it has no use for. */
-export function describe (event) {
-  const { name, args = {} } = event
-  const file = (verb, noun) => ({ plain: `${verb} a ${noun}`, detailed: `${verb} ${cut(firstLine(args.path))}` })
-  if (name === 'read') return file('reading', 'file')
-  if (name === 'write') return file('writing', 'file')
-  if (name === 'edit') return file('editing', 'file')
-  if (name === 'exec' || name === 'wsexec') return command(args.command)
-  if (name === 'ask' || name === 'quiet') return null
-  return { plain: name, detailed: name }
-}
-
-/**
- * A turn's events folded into what a chat is shown: a call when it starts, its time once it
- * ends slow, and that it failed. Returns whether anything changed.
- */
-export function track (items, event) {
-  if (event.event === 'tool_start') {
-    const told = describe(event)
-    if (!told) return false
-    items.push({ callId: event.callId, ...told })
-    return true
-  }
-  if (event.event === 'tool_end') {
-    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
-  }
-  const note = (text) => {
-    items.push({ plain: text, detailed: text })
-    return true
-  }
-  if (event.event === 'wrap') return note(`wrapping up — reached its ${event.dimension} limit`)
-  if (event.event === 'interject') return note('heard you')
-  return false
-}
-
-/** The lines a chat sees, the last few, a run of the same call counted rather than repeated. */
-export function render (items, { detailed = false, last = 6 } = {}) {
-  const lines = []
-  for (const item of items) {
-    const text = (detailed ? item.detailed : item.plain) +
-      (item.failed ? ' — failed' : '') +
-      (item.durationMs >= SLOW_MS ? ` — ${Math.round(item.durationMs / 1000)} s` : '')
-    const previous = lines.at(-1)
-    if (previous?.text === text) previous.count++
-    else lines.push({ text, count: 1 })
-  }
-  return lines.slice(-last).map(({ text, count }) => `· ${text}${count > 1 ? ` ×${count}` : ''}`)
-}
-
-const ending = (record) => [record.stopReason, record.error].filter(Boolean).join(' · ')
-
-export function reply ({ record }) {
-  const { output } = record
-  if (output) return PLAIN_ENDINGS.has(record.stopReason) ? output : `${output}\n\n— ${ending(record)}`
-  if (record.stopReason === 'quiet') return 'nothing to say'
-  return `no answer · ${ending(record)}`
-}
-
-/** What a chat is told of a turn that answered `asked`, none of it said in a chat: who said it, then the answer. */
-export function announce ({ record, asked }) {
-  const named = (field) => [...new Set(asked.filter(entry => entry[field]).map(entry => `"${entry[field]}"`))]
-  const origins = [
-    named('schedule').length ? `schedule ${named('schedule').join(', ')}` : null,
-    named('hook').length ? `webhook ${named('hook').join(', ')}` : null,
-    named('job').length ? `job ${named('job').join(', ')}` : null
-  ].filter(Boolean)
-  return `${origins.length ? origins.join(' · ') : 'sent from elsewhere'}\n\n${reply({ record })}`
-}
-
-/** A turn ended without reading this chat's message, and nothing is running to read it. */
-export function waiting ({ record }) {
-  return `no answer yet · ${ending(record)} — your message waits for the next turn`
-}
-
-export function pieces (text, limit = MAX_MESSAGE) {
-  const out = []
-  let rest = String(text)
-  while (rest.length > limit) {
-    const cut = rest.lastIndexOf('\n', limit)
-    const at = cut > limit / 2 ? cut : limit
-    out.push(rest.slice(0, at))
-    rest = rest.slice(at).replace(/^\n/, '')
-  }
-  if (rest) out.push(rest)
-  return out
-}

package/src/service.js

@@ -1,409 +0,0 @@
-import { existsSync, statSync } from 'node:fs'
-import { basename, resolve } from 'node:path'
-
-import { CONFIG_FILE, changeText, databaseOf, durationText, extendTurn, isWorkspace, lastEventSeq, loadEnvironment, outbox, readConfig, RUNNING, runningLines, send, settleOutbox, show, SporeError, stateOf, stop, turnsSince, watchAll, workspaceFor, wrapTurn } from '@rhizogrip/spore'
-import { allowed, detailedChats, tokenVariables } from './bots.js'
-import { createDelivery } from './delivery.js'
-import { announce, pieces, render, reply, track, waiting } from './forward.js'
-import { loadState, saveState } from './state.js'
-
-const MAX_DOCUMENT = 50 * 1024 * 1024
-const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
-const NOT_MODIFIED = /message is not modified/
-const TAKES_ARGUMENTS = new Set(['extend', 'wrap'])
-const HELP = 'Anything you write here goes to the spore. /status says what it is doing; /stop ends the turn it is running; /wrap [10m] asks it to wrap up; /extend wall 30m gives it more, as far as its spore.cmk allows.'
-
-const pause = (ms, signal) => new Promise(resolve => {
-  const timer = setTimeout(resolve, ms)
-  signal.addEventListener('abort', () => { clearTimeout(timer); resolve() }, { once: true })
-})
-
-const said = (err) => [err.message, err.detail].filter(Boolean).join(' — ')
-
-/**
- * One bot, routed by `botFile`. `env` is the environment the service was started with, before
- * `environment` beside `config.json` was read: that file is read again for every turn, so a key
- * added to it reaches the next turn without a restart, and a variable the service was started with
- * still wins. No bot's token is passed on.
- */
-export function createService ({ telegram, botFile, statePath, env, log, configFile = CONFIG_FILE, sleep = pause, editEveryMs = 2500, followEveryMs = 1000 }) {
-  const sendEnv = () => {
-    const fresh = { ...env }
-    loadEnvironment(configFile, fresh)
-    for (const variable of tokenVariables(configFile)) delete fresh[variable]
-    return fresh
-  }
-  const replyTo = `telegram:${basename(botFile, '.json')}/`
-  const state = loadState(statePath)
-  const stopping = new AbortController()
-  const delivery = createDelivery({ sleep: (ms) => sleep(ms, stopping.signal), signal: stopping.signal })
-  const notes = new WeakMap()
-  const shown = new Map()
-  let chatsOf = new Map()
-  let detailed = new Set()
-  let routeFailure = null
-
-  const save = () => saveState(statePath, state)
-  const noteOf = (entry) => notes.get(entry) ?? Promise.resolve(entry.message)
-
-  const route = () => {
-    const config = readConfig(configFile)
-    return { config, table: allowed(botFile), detailed: detailedChats(botFile) }
-  }
-  const sporeOf = (name, config) => {
-    const ws = workspaceFor(name, { config }).path
-    return isWorkspace(ws) ? ws : null
-  }
-
-  const tell = (chat, text) => delivery.to(chat, async (attempt) => {
-    for (const part of pieces(text)) await attempt(() => telegram.say(chat, part))
-  }).catch(err => log(`chat ${chat}: not delivered — ${said(err)}`))
-
-  const edit = async (attempt, chat, message, text) => {
-    const [first, ...rest] = pieces(text)
-    if (message === null) {
-      await attempt(() => telegram.say(chat, first))
-    } else {
-      try {
-        await attempt(() => telegram.revise(chat, message, first))
-      } catch (err) {
-        if (!NOT_MODIFIED.test(err.detail ?? '')) {
-          if (err.retryable) throw err
-          log(`chat ${chat}: message ${message} cannot be edited (${err.detail}), sending the text anew`)
-          await attempt(() => telegram.say(chat, first))
-        }
-      }
-    }
-    for (const part of rest) await attempt(() => telegram.say(chat, part))
-  }
-
-  const hand = async (attempt, chat, ws, files) => {
-    for (const file of files) {
-      const path = resolve(ws, file.path)
-      if (!existsSync(path)) {
-        await attempt(() => telegram.say(chat, `${file.path} is no longer there`))
-        continue
-      }
-      const bytes = statSync(path).size
-      if (bytes > MAX_DOCUMENT) {
-        await attempt(() => telegram.say(chat, `${file.path} is ${(bytes / 1024 / 1024).toFixed(0)} MB, more than Telegram takes; it is in the spore's workspace`))
-        continue
-      }
-      await attempt(() => telegram.document(chat, { path, mime: file.mime }, file.path))
-    }
-  }
-
-  const status = (ws) => {
-    const one = show({ ws, configFile })
-    return [
-      `${one.name} · ${one.model}`,
-      `${one.state}${one.draining ? ', finishing' : ''} · ${one.lastTurnNo} turns · ${one.billing !== null && one.billing.kind !== 'metered' ? `not metered · ${one.billing.label}` : `$${one.treeUsd.toFixed(4)}`}`,
-      ...(one.turnLimits ? runningLines(one.turnLimits, one.extend) : []),
-      one.last ? `last: ${[one.last.stopReason, one.last.error].filter(Boolean).join(' · ')}` : null,
-      one.waiting ? `${one.waiting} waiting` : null,
-      one.paused ? `paused${one.paused.at ? ` since ${one.paused.at}` : ''}${one.paused.why ? ` (${one.paused.why})` : ''}` : null,
-      one.held.length ? `${one.held.length} routed to wait` : null,
-      ...one.jobs.running.map(job => `job ${job.name}: ${durationText(Date.now() - Date.parse(job.startedAt))} of ${durationText(job.wallMs)}${job.progress ? ` · ${job.progress}` : ''}`)
-    ].filter(Boolean).join('\n')
-  }
-
-  const change = (chat, ws, act) => {
-    let answer
-    try {
-      answer = act()
-    } catch (err) {
-      return tell(chat, said(err))
-    }
-    return tell(chat, changeText(answer))
-  }
-
-  const obey = (chat, ws, command, args = '') => {
-    if (command === 'stop') return tell(chat, stop(ws).stopped ? 'stopping it' : 'nothing is running')
-    if (command === 'status') return tell(chat, status(ws))
-    if (command === 'wrap') return change(chat, ws, () => wrapTurn(ws, args.trim() || undefined))
-    if (command === 'extend') {
-      const [dimension, amount] = args.trim().split(/\s+/)
-      if (!dimension) return tell(chat, '/extend wall 30m, /extend cost 1.50 or /extend rounds 20')
-      return change(chat, ws, () => extendTurn(ws, dimension, amount))
-    }
-    return tell(chat, HELP)
-  }
-
-  const follows = (ws) => {
-    if (state.cursors[ws]) return false
-    state.cursors[ws] = { seq: lastEventSeq(ws), turn: stateOf(ws).lastTurnNo, database: databaseOf(ws) }
-    return true
-  }
-
-  const pass = (chat, ws, text, update) => {
-    if (follows(ws)) save()
-    let sent
-    try {
-      sent = send(ws, text, { requestId: `telegram:${update}`, replyTo: `${replyTo}${chat}`, env: sendEnv() })
-    } catch (err) {
-      log(`chat ${chat}: send refused — ${err.type} ${said(err)}`)
-      return tell(chat, err.type === 'ADMISSION_FULL' ? `busy — ${said(err)}` : `not delivered — ${said(err)}`)
-    }
-    if (sent.repeated) return log(`chat ${chat}: update ${update} was already delivered, as inbox ${sent.inbox}`)
-
-    const entry = { inbox: sent.inbox, chat, message: null }
-    ;(state.pending[ws] ??= []).push(entry)
-    save()
-    notes.set(entry, delivery.to(chat, attempt => attempt(() => telegram.say(chat, sent.started ? 'working…' : 'heard you — still working…')))
-      .then(note => note.message_id, err => {
-        log(`chat ${chat}: no working message — ${said(err)}`)
-        return null
-      })
-      .then(message => {
-        entry.message = message
-        save()
-        return message
-      }))
-  }
-
-  const handle = async (update) => {
-    const message = update.message
-    const chat = message?.chat?.id
-    if (chat === undefined) return
-
-    let read
-    try {
-      read = route()
-    } catch (err) {
-      return log(`refused chat ${chat}: the allow-list is unreadable — ${said(err)}`)
-    }
-    const name = read.table[String(chat)]
-    if (!name) {
-      const who = message.from?.username ? ` (@${message.from.username})` : ''
-      return log(`refused chat ${chat}${who} — to allow it, add "${chat}": "<a spore>" to the chats of ${botFile}`)
-    }
-    let ws
-    try {
-      ws = sporeOf(name, read.config)
-    } catch (err) {
-      log(`chat ${chat}: "${name}" — ${said(err)}`)
-      return tell(chat, `this chat points at "${name}", which is not a spore name — tell whoever runs me`)
-    }
-    if (!ws) {
-      log(`chat ${chat}: no spore "${name}"`)
-      return tell(chat, `there is no spore called "${name}" — tell whoever runs me`)
-    }
-
-    const text = message.text?.trim()
-    if (!text) return tell(chat, 'only text reaches a spore for now')
-    const command = text.match(COMMAND)
-    const asked = command?.[1].toLowerCase()
-    if (command && (!command[3] || TAKES_ARGUMENTS.has(asked))) return obey(chat, ws, asked, command[3])
-    pass(chat, ws, text, update.update_id)
-  }
-
-  const listen = async () => {
-    const { signal } = stopping
-    let offset
-    let backoff = 1000
-    while (!signal.aborted) {
-      let updates
-      try {
-        updates = await telegram.updates(offset, { signal })
-        backoff = 1000
-      } catch (err) {
-        if (signal.aborted) break
-        if (err.context?.status === 409) {
-          throw new SporeError('another process is taking this bot\'s updates', { type: 'TELEGRAM_CONFLICT', detail: err.detail })
-        }
-        if (!err.retryable) throw err
-        log(`poll failed — ${said(err)}`)
-        await sleep(err.context?.retryAfter ? err.context.retryAfter * 1000 : backoff, signal)
-        backoff = Math.min(backoff * 2, 60_000)
-        continue
-      }
-      for (const update of updates) {
-        try {
-          await handle(update)
-        } catch (err) {
-          log(`update ${update.update_id}: ${said(err)}`)
-          const chat = update.message?.chat?.id
-          if (chat !== undefined) tell(chat, `that failed — ${err.message}`)
-        }
-        offset = update.update_id + 1
-      }
-    }
-    if (offset !== undefined) {
-      await telegram.updates(offset, { seconds: 0 }).catch(err => log(`could not confirm the last updates — ${said(err)}`))
-    }
-  }
-
-  const spores = () => {
-    let read
-    try {
-      read = route()
-      routeFailure = null
-    } catch (err) {
-      if (routeFailure !== err.message) log(`allow-list: ${said(err)} — following the spores it last named`)
-      routeFailure = err.message
-      return [...chatsOf.keys()]
-    }
-    detailed = read.detailed
-    const next = new Map()
-    for (const [chat, name] of Object.entries(read.table)) {
-      let ws
-      try {
-        ws = sporeOf(name, read.config)
-      } catch {
-        // Told to the chat, and logged, when it next speaks.
-        continue
-      }
-      if (ws) next.set(ws, [...(next.get(ws) ?? []), Number(chat)])
-    }
-    let moved = false
-    for (const ws of Object.keys(state.cursors)) {
-      if (next.has(ws)) continue
-      delete state.cursors[ws]
-      delete state.pending[ws]
-      moved = true
-    }
-    for (const ws of next.keys()) moved = follows(ws) || moved
-    if (moved) save()
-    chatsOf = next
-    return [...next.keys()]
-  }
-
-  const repaint = (ws) => {
-    const lines = shown.get(ws)
-    lines.timer = null
-    lines.at = Date.now()
-    for (const entry of state.pending[ws] ?? []) {
-      const text = ['working…', ...render(lines.items, { detailed: detailed.has(entry.chat) })].join('\n')
-      delivery.to(entry.chat, async (attempt) => {
-        const message = await noteOf(entry)
-        if (message === null || !state.pending[ws]?.includes(entry)) return
-        await attempt(() => telegram.revise(entry.chat, message, text))
-      }).catch(err => { if (!NOT_MODIFIED.test(err.detail ?? '')) log(`chat ${entry.chat}: progress not shown — ${said(err)}`) })
-    }
-  }
-
-  const onEvent = (ws, event) => {
-    if (!state.pending[ws]?.length) return
-    const lines = shown.get(ws) ?? { items: [], timer: null, at: 0 }
-    shown.set(ws, lines)
-    if (!track(lines.items, event)) return
-    if (!lines.timer) lines.timer = setTimeout(() => repaint(ws), Math.max(0, editEveryMs - (Date.now() - lines.at)))
-  }
-
-  const forget = (ws, notes) => {
-    const kept = (state.pending[ws] ?? []).filter(note => !notes.includes(note))
-    if (kept.length) state.pending[ws] = kept
-    else delete state.pending[ws]
-    save()
-  }
-
-  /**
-   * One outbox entry of this bot's posted to its chat — into the `working…` messages of what it
-   * answers when the chat has them — and settled: delivered once Telegram took it, refused when
-   * the chat does not reach this spore or Telegram will not take it. One Telegram still did not
-   * take when its retries ran out stays pending for the next pass. True when it is settled.
-   */
-  const deliver = async (ws, entry) => {
-    const chat = Number(entry.recipient.slice(replyTo.length))
-    const notes = (state.pending[ws] ?? []).filter(note => note.chat === chat && entry.answers.includes(note.inbox))
-    if (!(chatsOf.get(ws) ?? []).includes(chat)) {
-      const reason = `chat ${entry.recipient.slice(replyTo.length)} does not reach this spore through ${botFile}`
-      settleOutbox(ws, entry.outboxNo, { refused: reason })
-      log(`turn ${entry.turnNo} of ${ws}: refused — ${reason}`)
-      forget(ws, notes)
-      return true
-    }
-    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)
-    try {
-      await delivery.to(chat, async (attempt) => {
-        if (notes.length) {
-          for (const note of notes) await edit(attempt, chat, await noteOf(note), text)
-        } else {
-          for (const part of pieces(text)) await attempt(() => telegram.say(chat, part))
-        }
-        await hand(attempt, chat, ws, files)
-      })
-    } catch (err) {
-      if (err.retryable || stopping.signal.aborted) {
-        log(`turn ${entry.turnNo} of ${ws}: not delivered to chat ${chat} yet — ${said(err)}`)
-        return false
-      }
-      settleOutbox(ws, entry.outboxNo, { refused: said(err) })
-      log(`turn ${entry.turnNo} of ${ws}: chat ${chat} refused it — ${said(err)}`)
-      forget(ws, notes)
-      return true
-    }
-    settleOutbox(ws, entry.outboxNo)
-    forget(ws, notes)
-    return true
-  }
-
-  /**
-   * This bot's pending outbox entries of `ws`, delivered in order: the messages still owed an
-   * answer, or null when the spore's database could not be read or written — a busy one — and
-   * what it holds waits for the next pass.
-   */
-  const drain = async (ws) => {
-    const owed = new Set()
-    try {
-      for (const entry of outbox(ws, { kind: 'telegram', state: 'pending' })) {
-        if (!entry.recipient.startsWith(replyTo)) continue
-        if (!(await deliver(ws, entry))) entry.answers.forEach(inboxNo => owed.add(inboxNo))
-      }
-    } catch (err) {
-      log(`${ws}: its outbox could not be read or settled — ${said(err)}`)
-      return null
-    }
-    return owed
-  }
-
-  const onTurn = async (ws, turn) => {
-    clearTimeout(shown.get(ws)?.timer)
-    shown.delete(ws)
-
-    const read = new Set(turn.asked.map(entry => entry.inboxNo))
-    const left = (state.pending[ws] ?? []).filter(entry => !read.has(entry.inbox))
-    if (left.length && stateOf(ws).state !== RUNNING) {
-      const work = left.map(entry => delivery.to(entry.chat, async (attempt) => edit(attempt, entry.chat, await noteOf(entry), waiting(turn))))
-      for (const outcome of await Promise.allSettled(work)) {
-        if (outcome.status === 'rejected') log(`turn ${turn.record.turnNo} of ${ws}: not told it is waiting — ${said(outcome.reason)}`)
-      }
-    }
-
-    const owed = await drain(ws)
-    if (owed) forget(ws, (state.pending[ws] ?? []).filter(note => read.has(note.inbox) && !owed.has(note.inbox)))
-  }
-
-  const follow = async () => {
-    const { signal } = stopping
-    for (const ws of spores()) await drain(ws)
-    for await (const item of watchAll(spores, { cursors: state.cursors, tick: followEveryMs, signal })) {
-      if (item.event) {
-        onEvent(item.ws, item.event)
-        continue
-      }
-      await onTurn(item.ws, item.turn)
-      if (signal.aborted) break
-      state.cursors[item.ws] = item.cursor
-      save()
-    }
-  }
-
-  const run = async (signal) => {
-    signal.addEventListener('abort', () => stopping.abort(), { once: true })
-    const failed = []
-    const halt = (err) => {
-      failed.push(err)
-      stopping.abort()
-    }
-    await Promise.all([listen().catch(halt), follow().catch(halt)])
-    for (const lines of shown.values()) clearTimeout(lines.timer)
-    save()
-    if (failed.length) throw failed[0]
-  }
-
-  return { run }
-}

package/src/state.js

@@ -1,33 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-
-import { SporeError } from '@rhizogrip/spore'
-
-export const statePath = (bot, env = process.env) =>
-  join(env.XDG_STATE_HOME || join(homedir(), '.local', 'state'), 'spore', 'telegram', bot, 'state.json')
-
-/**
- * `cursors` is `watchAll`'s, per workspace. `pending` is, per workspace, every message a chat
- * sent that no turn has answered yet: its `inbox` number, the chat, and the `working…`
- * message the answer is edited into.
- */
-export function loadState (path) {
-  if (!existsSync(path)) return { cursors: {}, pending: {} }
-  try {
-    const { cursors, pending } = JSON.parse(readFileSync(path, 'utf8'))
-    return { cursors, pending }
-  } catch (err) {
-    throw new SporeError(`${path} is not readable`, {
-      type: 'TELEGRAM_STATE_INVALID',
-      detail: `${err.message} — it holds where the bot stood; move it aside to start from now`
-    })
-  }
-}
-
-export function saveState (path, { cursors, pending }) {
-  mkdirSync(dirname(path), { recursive: true })
-  const written = `${path}.${process.pid}`
-  writeFileSync(written, JSON.stringify({ cursors, pending }, null, 2))
-  renameSync(written, path)
-}