@rhizogrip/spore-plugin-telegram 0.3.0 → 0.5.0

package/README.md

@@ -28,8 +28,9 @@ 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
@@ -37,19 +38,24 @@ passed to a spore's runner.
   after the spore's next turn or the service's next start.
 - **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.
+- **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, up to the 50 a turn hands back, then a line
-counting the rest; a file over Telegram's 50 MB is named instead.
+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`. The
+answer's Markdown is shown as Telegram formats it — bold, italic, code, code blocks, links, quotes;
+a heading as a bold line, a table in a monospace block — and as plain text if Telegram refuses it. 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
@@ -57,7 +63,7 @@ question, and the reply answers it. The conversation is the spore's transcript;
 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
@@ -66,7 +72,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
 
@@ -118,9 +125,9 @@ group's id is negative, and it is the group you add rather than the people in it
 
 ## 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. A spore added later is followed from its
+`$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.
 

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.3.0",
+  "version": "0.5.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",
@@ -27,14 +27,17 @@
     "README.md",
     "NOTICE"
   ],
+  "dependencies": {
+    "marked": "^18.0.11"
+  },
   "peerDependencies": {
-    "@rhizogrip/spore": "^1"
+    "@rhizogrip/spore": "^1.16.0"
   },
   "scripts": {
     "test": "vitest run"
   },
   "spore": {
-    "works": "^1",
+    "works": "^1.16.0",
     "services": {
       "telegram": {
         "what": "a bot of yours in Telegram chats, each chat reaching its spore",

package/src/adapter.js

@@ -0,0 +1,151 @@
+/**
+ * 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'
+
+import { toHtml } from './format.js'
+
+const COMMAND = /^\/([a-z]+)(@\w+)?(?:\s+(.+))?$/is
+const NOT_MODIFIED = /message is not modified/
+const CANNOT_PARSE = /can't parse entities/i
+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, markdown = false } = {}) => {
+      try {
+        return (await telegram.say(Number(conversation), markdown ? toHtml(text) : text, { answering, html: markdown })).message_id
+      } catch (err) {
+        if (!markdown || !CANNOT_PARSE.test(err.detail ?? '')) throw err
+        throw new SporeError('Telegram refused the formatting', { type: 'TELEGRAM_FORMAT_REFUSED', detail: err.detail, context: { formatRefused: true } })
+      }
+    },
+
+    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,19 @@ 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, html = false } = {}) => call('sendMessage', {
+      chat_id: chat,
+      text,
+      link_preview_options: { is_disabled: true },
+      ...(html ? { parse_mode: 'HTML' } : {}),
+      ...(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/format.js

@@ -0,0 +1,76 @@
+/**
+ * Markdown, as a model writes it, in the HTML Telegram renders. Bold, italic, strikethrough, code,
+ * code blocks with their language, links and quotes are Telegram's own; a heading becomes a bold
+ * line, a list keeps its bullets as text, a table becomes a monospace block. Telegram refuses a
+ * message holding any tag outside its small set, so everything else is escaped and shown as written.
+ */
+
+import { Lexer } from 'marked'
+
+const LINKABLE = /^(https?:|mailto:|tg:)/i
+
+const escape = (text) => String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+const attribute = (text) => escape(text).replace(/"/g, '&quot;')
+
+const plain = (tokens) => tokens.map(token => (token.tokens ? plain(token.tokens) : token.text ?? '')).join('')
+
+function inline (tokens) {
+  return tokens.map((token) => {
+    if (token.type === 'strong') return `<b>${inline(token.tokens)}</b>`
+    if (token.type === 'em') return `<i>${inline(token.tokens)}</i>`
+    if (token.type === 'del') return `<s>${inline(token.tokens)}</s>`
+    if (token.type === 'codespan') return `<code>${escape(token.text)}</code>`
+    if (token.type === 'br') return '\n'
+    if (token.type === 'link') return LINKABLE.test(token.href) ? `<a href="${attribute(token.href)}">${inline(token.tokens)}</a>` : inline(token.tokens)
+    if (token.type === 'image') return LINKABLE.test(token.href) ? `<a href="${attribute(token.href)}">${escape(token.text || token.href)}</a>` : escape(token.text)
+    if (token.type === 'text') return token.tokens ? inline(token.tokens) : escape(token.text)
+    if (token.type === 'escape') return escape(token.text)
+    if (token.type === 'checkbox') return token.checked ? '☑ ' : '☐ '
+    return escape(token.raw)
+  }).join('')
+}
+
+function list (token, depth) {
+  const indent = '  '.repeat(depth)
+  return token.items.map((item, i) => {
+    const mark = token.ordered ? `${Number(token.start) + i}.` : '•'
+    const box = item.tokens.filter(child => child.type === 'checkbox').map(child => inline([child])).join('')
+    const parts = item.tokens.filter(child => child.type !== 'checkbox').map(child => (child.type === 'list' ? list(child, depth + 1) : block([child], depth + 1)))
+    return `${indent}${mark} ${box}${parts.join('\n')}`
+  }).join('\n')
+}
+
+function table (token) {
+  const rows = [token.header, ...token.rows].map(row => row.map(cell => plain(cell.tokens)))
+  const widths = rows[0].map((_, column) => Math.max(...rows.map(row => row[column].length)))
+  const line = (row) => row.map((cell, column) => cell.padEnd(widths[column])).join(' | ').trimEnd()
+  return `<pre>${escape([line(rows[0]), widths.map(width => '-'.repeat(width)).join('-+-'), ...rows.slice(1).map(line)].join('\n'))}</pre>`
+}
+
+function block (tokens, depth = 0) {
+  const out = []
+  for (const token of tokens) {
+    if (token.type === 'space') continue
+    if (token.type === 'code') {
+      const language = token.lang?.split(/\s/)[0]
+      out.push(`<pre><code${language ? ` class="language-${attribute(language)}"` : ''}>${escape(token.text)}</code></pre>`)
+    } else if (token.type === 'heading') {
+      out.push(`<b>${inline(token.tokens)}</b>`)
+    } else if (token.type === 'paragraph' || token.type === 'text') {
+      out.push(inline(token.tokens ?? [token]))
+    } else if (token.type === 'blockquote') {
+      out.push(`<blockquote>${block(token.tokens, depth)}</blockquote>`)
+    } else if (token.type === 'list') {
+      out.push(list(token, depth))
+    } else if (token.type === 'table') {
+      out.push(table(token))
+    } else if (token.type === 'hr') {
+      out.push('──────────')
+    } else {
+      out.push(escape(token.raw.trimEnd()))
+    }
+  }
+  return out.join('\n\n')
+}
+
+export const toHtml = (markdown) => block(Lexer.lex(String(markdown)))

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,138 +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.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 })
-    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.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++
-    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,411 +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 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'])
-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, more }) => {
-    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))
-    }
-    if (more) await attempt(() => telegram.say(chat, leftOut(more)))
-  }
-
-  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 handed = { files: turn.record.deliverables ?? [], more: turn.record.deliverablesMore ?? 0 }
-    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, handed)
-      })
-    } 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)
-}