@soffits/dsh-telegram-bot 0.0.0-stage → 0.4.1

package/src/outbox.js

@@ -0,0 +1,160 @@
+/**
+ * File spool for sending to topics from outside the Host process.
+ *
+ * A sender writes one request file into the outbox directory; the running
+ * plugin picks it up, sends it, and writes a result file next to it. Requests
+ * wait in the spool while the bot is stopped, and senders need no bot token
+ * or network access to the Host: only write access to the DSH home.
+ */
+import { randomUUID } from 'node:crypto'
+import { watch } from 'node:fs'
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { STATUS_DIR } from './constants.js'
+
+/** Default spool directory. */
+export const OUTBOX_DIR = join(STATUS_DIR, 'outbox')
+/** Result files older than this are removed by the plugin. */
+const RESULT_TTL_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Write one send request atomically.
+ * @param request - `{ to, text, files, from }`, as for the `telegramTopics` service's `send`.
+ * @param dir - spool directory.
+ * @returns the request id.
+ */
+export async function enqueue(request, dir = OUTBOX_DIR) {
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const id = `${Date.now()}-${randomUUID().slice(0, 8)}`
+  const temporary = join(dir, `${id}.tmp`)
+  await writeFile(temporary, JSON.stringify({ ...request, id, createdAt: Date.now() }) + '\n', { mode: 0o600 })
+  await rename(temporary, join(dir, `${id}.json`))
+  return id
+}
+
+/**
+ * Wait for the plugin's result for one request.
+ * @param id - request id from {@link enqueue}.
+ * @param timeoutMs - how long to wait.
+ * @param dir - spool directory.
+ * @returns the result document, or undefined after the timeout.
+ */
+export async function waitForResult(id, timeoutMs, dir = OUTBOX_DIR) {
+  const path = join(dir, `${id}.result.json`)
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      const result = JSON.parse(await readFile(path, 'utf8'))
+      await rm(path, { force: true })
+      return result
+    } catch {
+      // Not written yet.
+    }
+    if (Date.now() >= deadline) return undefined
+    await new Promise((resolve) => setTimeout(resolve, 200))
+  }
+}
+
+/**
+ * Plugin side: process spooled requests one at a time.
+ * @param options.handle - async function sending one request; its value is the result.
+ * @param options.ready - whether requests can be sent now (the bot is running).
+ * @param options.onError - reports unexpected spool failures.
+ * @param options.dir - spool directory.
+ * @param options.intervalMs - rescan period; file watching only speeds it up.
+ * @returns `{ start, stop, drain }`.
+ */
+export function createOutbox({ handle, ready, onError, dir = OUTBOX_DIR, intervalMs = 1000 }) {
+  let timer
+  let watcher
+  let draining
+  let again = false
+
+  /** Put requests that were being sent when the Host stopped back in line. */
+  async function recover() {
+    for (const name of await readdir(dir).catch(() => [])) {
+      if (name.endsWith('.processing')) {
+        await rename(join(dir, name), join(dir, name.replace(/\.processing$/u, '.json'))).catch(() => {})
+      }
+    }
+  }
+
+  /** Remove result files nobody collected. */
+  async function sweep(names) {
+    for (const name of names) {
+      if (!name.endsWith('.result.json')) continue
+      const path = join(dir, name)
+      const info = await stat(path).catch(() => undefined)
+      if (info !== undefined && Date.now() - info.mtimeMs > RESULT_TTL_MS) await rm(path, { force: true })
+    }
+  }
+
+  /** Send every waiting request, oldest first. */
+  async function drainOnce() {
+    if (!ready()) return
+    const names = (await readdir(dir).catch(() => [])).sort()
+    await sweep(names)
+    for (const name of names) {
+      if (!name.endsWith('.json') || name.endsWith('.result.json')) continue
+      if (!ready()) return
+      const id = name.slice(0, -'.json'.length)
+      const claimed = join(dir, `${id}.processing`)
+      try {
+        await rename(join(dir, name), claimed)
+      } catch {
+        continue
+      }
+      let outcome
+      try {
+        const request = JSON.parse(await readFile(claimed, 'utf8'))
+        outcome = { ok: true, result: await handle(request) }
+      } catch (error) {
+        outcome = { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+      try {
+        await writeFile(join(dir, `${id}.result.json`), JSON.stringify(outcome) + '\n', { mode: 0o600 })
+        await rm(claimed, { force: true })
+      } catch (error) {
+        onError(error)
+      }
+    }
+  }
+
+  /** Run one drain, coalescing triggers that arrive while it runs. */
+  function drain() {
+    if (draining !== undefined) {
+      again = true
+      return draining
+    }
+    draining = (async () => {
+      do {
+        again = false
+        await drainOnce()
+      } while (again)
+    })().catch(onError).finally(() => { draining = undefined })
+    return draining
+  }
+
+  async function start() {
+    await mkdir(dir, { recursive: true, mode: 0o700 })
+    await recover()
+    try {
+      watcher = watch(dir, () => { void drain() })
+      watcher.on('error', () => {})
+    } catch {
+      // The interval still picks requests up.
+    }
+    timer = setInterval(() => { void drain() }, intervalMs)
+    timer.unref?.()
+    void drain()
+  }
+
+  function stop() {
+    if (timer !== undefined) clearInterval(timer)
+    timer = undefined
+    watcher?.close()
+    watcher = undefined
+  }
+
+  return { start, stop, drain }
+}

package/src/sent-log.js

@@ -0,0 +1,112 @@
+/**
+ * Remember messages sent into topics through the plugin (the Host service,
+ * the `telegram_send` tool and the `dsh-telegram-send` spool), so a later
+ * reply to one of them can tell the agent what was sent, when and by whom,
+ * even when the topic's session has changed since.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { STATUS_DIR } from './constants.js'
+
+/** Default file of the log. */
+export const SENT_LOG_PATH = join(STATUS_DIR, 'sent-messages.json')
+/** Most sends kept; older ones are dropped first. */
+export const SENT_LOG_MAX_ENTRIES = 1000
+/** Sends older than this are dropped. */
+export const SENT_LOG_MAX_AGE_MS = 180 * 24 * 60 * 60 * 1000
+/** Longest text kept per send, in characters. */
+export const SENT_LOG_MAX_TEXT = 20_000
+
+/**
+ * Open the log. Reading happens once, on first use; a missing or broken file
+ * starts an empty log.
+ * @param options.path - log file.
+ * @param options.now - clock, for tests.
+ * @param options.onError - reports a failed write.
+ * @returns `{ record, find }`.
+ */
+export function createSentLog({ path = SENT_LOG_PATH, now = Date.now, onError = () => {} } = {}) {
+  let entries
+  let loading
+  let writing = Promise.resolve()
+
+  async function load() {
+    if (entries !== undefined) return entries
+    loading ??= (async () => {
+      try {
+        const data = JSON.parse(await readFile(path, 'utf8'))
+        entries = Array.isArray(data?.entries) ? data.entries.filter((entry) => entry !== null && typeof entry === 'object') : []
+      } catch {
+        entries = []
+      }
+      return entries
+    })()
+    return loading
+  }
+
+  function prune() {
+    const oldest = now() - SENT_LOG_MAX_AGE_MS
+    entries = entries.filter((entry) => Date.parse(entry.sentAt ?? '') >= oldest)
+    if (entries.length > SENT_LOG_MAX_ENTRIES) entries = entries.slice(-SENT_LOG_MAX_ENTRIES)
+  }
+
+  function save() {
+    const snapshot = JSON.stringify({ version: 1, entries }) + '\n'
+    writing = writing.then(async () => {
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+      const temporary = `${path}.tmp`
+      await writeFile(temporary, snapshot, { mode: 0o600 })
+      await rename(temporary, path)
+    }).catch(onError)
+    return writing
+  }
+
+  return {
+    /**
+     * Remember one send.
+     * @param entry - `{ chatId, threadId, topic, messageIds, text, files,
+     *   sticker, fromSession, job, label, boundSession, recorded }`;
+     *   `sticker` is `{ id, emoji, setName }` when one was sent.
+     */
+    async record(entry) {
+      await load()
+      const text = typeof entry.text === 'string' ? entry.text : ''
+      entries.push({
+        chatId: entry.chatId,
+        threadId: entry.threadId ?? null,
+        topic: entry.topic ?? null,
+        messageIds: Array.isArray(entry.messageIds) ? entry.messageIds : [],
+        sentAt: new Date(now()).toISOString(),
+        text: text.length > SENT_LOG_MAX_TEXT ? text.slice(0, SENT_LOG_MAX_TEXT) : text,
+        textCut: text.length > SENT_LOG_MAX_TEXT ? text.length - SENT_LOG_MAX_TEXT : 0,
+        files: Array.isArray(entry.files) ? entry.files : [],
+        ...(entry.sticker === undefined || entry.sticker === null ? {} : { sticker: entry.sticker }),
+        fromSession: entry.fromSession ?? null,
+        job: entry.job ?? null,
+        label: entry.label ?? null,
+        boundSession: entry.boundSession ?? null,
+        recorded: entry.recorded === true,
+      })
+      prune()
+      await save()
+    },
+    /**
+     * Find the send one Telegram message belongs to.
+     * @param chatId - chat of the message.
+     * @param messageId - its id.
+     * @returns the entry, or undefined.
+     */
+    async find(chatId, messageId) {
+      if (chatId === undefined || chatId === null || !Number.isSafeInteger(messageId)) return undefined
+      await load()
+      const chat = String(chatId)
+      for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index]
+        if (String(entry.chatId) === chat && entry.messageIds.includes(messageId)) return entry
+      }
+      return undefined
+    },
+    /** Wait for pending writes (tests and shutdown). */
+    flush: () => writing,
+  }
+}

package/src/state.js

@@ -0,0 +1,49 @@
+/** Durable Telegram state file. */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { STATUS_DIR } from './constants.js'
+
+/** Durable Telegram chat → DSH session mapping. */
+const STATE_PATH = join(STATUS_DIR, 'state.json')
+
+/**
+ * Drop the model copies older versions kept on session records. The session
+ * itself records its model; a copy here went stale and was read back as truth.
+ * @param sessions - session records by id.
+ * @returns the records without `provider`, `model` and `effort`.
+ */
+function withoutModelCopies(sessions) {
+  return Object.fromEntries(Object.entries(sessions).map(([id, record]) => {
+    if (record === null || typeof record !== 'object') return [id, record]
+    const { provider: _provider, model: _model, effort: _effort, ...rest } = record
+    return [id, rest]
+  }))
+}
+
+/**
+ * Read the chat/session mapping. A missing or malformed file starts empty.
+ * @returns the mapping document.
+ */
+async function loadState() {
+  try {
+    const parsed = JSON.parse(await readFile(STATE_PATH, 'utf8'))
+    if (parsed !== null && typeof parsed === 'object') {
+      return {
+        version: 2,
+        sessions: parsed.sessions !== null && typeof parsed.sessions === 'object' ? withoutModelCopies(parsed.sessions) : {},
+        threads: parsed.threads !== null && typeof parsed.threads === 'object' ? parsed.threads : {},
+        updateLedger: parsed.updateLedger !== null && typeof parsed.updateLedger === 'object' && !Array.isArray(parsed.updateLedger) ? parsed.updateLedger : {},
+        updateOffset: Number.isSafeInteger(parsed.updateOffset) && parsed.updateOffset >= 0 ? parsed.updateOffset : 0,
+        topicNames: parsed.topicNames !== null && typeof parsed.topicNames === 'object' && !Array.isArray(parsed.topicNames) ? parsed.topicNames : {},
+        directChats: parsed.directChats !== null && typeof parsed.directChats === 'object' && !Array.isArray(parsed.directChats) ? parsed.directChats : {},
+        directTopics: parsed.directTopics !== null && typeof parsed.directTopics === 'object' && !Array.isArray(parsed.directTopics) ? parsed.directTopics : {},
+        goalPanels: parsed.goalPanels !== null && typeof parsed.goalPanels === 'object' && !Array.isArray(parsed.goalPanels) ? parsed.goalPanels : (parsed.goalPins !== null && typeof parsed.goalPins === 'object' && !Array.isArray(parsed.goalPins) ? parsed.goalPins : {}),
+      }
+    }
+  } catch {
+    // Missing or corrupt state is nonfatal; the next session creates a mapping.
+  }
+  return { version: 2, sessions: {}, threads: {}, updateLedger: {}, updateOffset: 0, topicNames: {}, directChats: {}, directTopics: {}, goalPanels: {} }
+}
+
+export { STATE_PATH, loadState }

package/src/status.js

@@ -0,0 +1,43 @@
+/** Local runtime diagnostics snapshot. */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { STATUS_DIR } from './constants.js'
+
+/** Last published runtime snapshot, mirrored to a local diagnostics file. */
+let runtimeStatus = {
+  state: 'starting',
+  detail: '',
+  username: '',
+  updatedAt: new Date().toISOString(),
+  transport: 'https-ipv4',
+  version: '0.3.0',
+  agentBridge: 'v1',
+  codeRevision: 'upstream-0.3.0-merge',
+  lastPollAt: 0,
+  lastMessageAt: 0,
+  lastChatId: null,
+  lastFromId: null,
+  lastUpdateType: null,
+  lastUpdateAt: 0,
+  lastOutcome: null,
+}
+
+/**
+ * Persist a local runtime snapshot for diagnostics. This file is intentionally
+ * separate from the user settings: status changes must never rewrite the
+ * profile patch or trigger a configuration reload.
+ * @param patch - fields to merge into the current snapshot.
+ * @returns resolves after the best-effort write.
+ */
+async function publishStatus(patch) {
+  runtimeStatus = { ...runtimeStatus, ...patch, updatedAt: new Date().toISOString() }
+  try {
+    await mkdir(STATUS_DIR, { recursive: true })
+    await writeFile(join(STATUS_DIR, 'status.json'), JSON.stringify(runtimeStatus, null, 2) + '\n', { mode: 0o600 })
+  } catch {
+    // Diagnostics must never take the runtime down.
+  }
+}
+
+
+export { runtimeStatus, publishStatus }

package/src/steer.js

@@ -0,0 +1,104 @@
+/**
+ * Steering: a Telegram message sent while the bound session's turn runs goes
+ * into that turn, the way the DSH Web UI sends a message during a turn. DSH
+ * delivers it at the agent's next step; if the turn has already ended, DSH
+ * opens a new turn for it. Fork-only code, kept out of `app.js`.
+ */
+import { randomUUID } from 'node:crypto'
+import { promptRequestId } from './admission.js'
+
+/** Reaction that tells the sender a message reached the running turn. */
+export const STEER_REACTION = '👀'
+
+/**
+ * How Telegram messages that arrive during a running turn are handled.
+ * @param value - the `busyMessages` setting.
+ * @returns `queue` (the bot holds them until the turn ends) or `steer`.
+ */
+export function busyMode(value) {
+  return value === 'queue' ? 'queue' : 'steer'
+}
+
+/**
+ * The durable request id of a Telegram prompt. With a Telegram message id it is
+ * the same id the native text path uses, so a redelivered update is not
+ * admitted twice.
+ * @param chatId - Telegram chat.
+ * @param messageId - Telegram message id, when known.
+ * @returns the request id recorded on the user message.
+ */
+export function steerRequestId(chatId, messageId) {
+  return Number.isSafeInteger(chatId) && Number.isSafeInteger(messageId)
+    ? promptRequestId(chatId, messageId)
+    : `telegram-steer:${randomUUID()}`
+}
+
+/** @returns whether a pending or recorded message carries this request id. */
+function hasRequest(agent, requestId) {
+  const matches = (message) => message?.source?.kind === 'user' && message.source.rpcId === requestId
+  const inbox = agent?.inbox
+  if (inbox?.nextTurn?.some?.(matches) || inbox?.nextStep?.some?.(matches)) return true
+  if (typeof agent?.session?.snapshotEvents !== 'function') return false
+  return agent.session.snapshotEvents().some((event) => event?.type === 'user/message' && matches(event.data))
+}
+
+/**
+ * Send one prompt into the session's running turn. Text goes through the
+ * Session controller's `steer` mode, the Web UI's own path; attachments are
+ * already stored, so a message with them goes straight to `agent.steer`, the
+ * method that mode calls. Either way DSH puts the message in the next-step
+ * inbox and wakes the agent: a running turn takes it at its next step, and a
+ * turn that ended meanwhile is followed by a new one, so the message is never
+ * dropped. A request id already admitted is skipped, so it is never sent twice.
+ * @param ctx - plugin context.
+ * @param agent - the session's live agent.
+ * @param prompt - `{ sessionId, chatId, messageId, text, attachments }`.
+ * @param signal - request lifetime.
+ * @returns the request id, or `undefined` when this DSH cannot steer.
+ */
+export async function steerPrompt(ctx, agent, { sessionId, chatId, messageId, text, attachments = [] }, signal) {
+  const requestId = steerRequestId(chatId, messageId)
+  const content = [...(text.trim().length === 0 ? [] : [{ type: 'text', text }]), ...attachments]
+  const controller = ctx.get('sessionController')
+  if (attachments.length === 0 && content.length > 0 && typeof controller?.prompt === 'function') {
+    await controller.prompt({ sessionId, requestId, mode: 'steer', content }, signal)
+    return requestId
+  }
+  if (hasRequest(agent, requestId)) return requestId
+  const message = { id: randomUUID(), role: 'user', content, source: { kind: 'user', rpcId: requestId } }
+  if (typeof agent?.steer === 'function') agent.steer(message)
+  else if (typeof agent?.send === 'function') agent.send(message, 'next-step', true)
+  else return undefined
+  return requestId
+}
+
+/**
+ * Remove Telegram messages from one chat that the agent has not taken yet,
+ * from both the next-step and the next-turn inbox.
+ * @param agent - the session's live agent.
+ * @param chatId - Telegram chat whose messages are removed.
+ * @returns how many were removed.
+ */
+export function clearTelegramInbox(agent, chatId) {
+  const inbox = agent?.inbox
+  if (typeof inbox?.remove !== 'function') return 0
+  const prefix = `telegram:${chatId}:`
+  const ours = (message) => message?.source?.kind === 'user'
+    && typeof message.source.rpcId === 'string'
+    && (message.source.rpcId.startsWith(prefix) || message.source.rpcId.startsWith('telegram-steer:'))
+  const pending = [...(inbox.nextStep ?? []), ...(inbox.nextTurn ?? [])].filter(ours)
+  for (const message of pending) inbox.remove(message.id)
+  return pending.length
+}
+
+/**
+ * Whether the agent still holds input it has not taken. DSH starts another
+ * turn for it right after the current one ends.
+ * @param agent - live agent.
+ */
+export function hasPendingInput(agent) {
+  const inbox = agent?.inbox
+  if (inbox === undefined) return false
+  if (typeof inbox.hasPending === 'boolean') return inbox.hasPending
+  return (inbox.nextStep?.length ?? 0) > 0 || (inbox.nextTurn?.length ?? 0) > 0
+}

package/src/stickers.js

@@ -0,0 +1,185 @@
+/**
+ * Sticker library: stickers the bot has seen or loaded from a set, keyed by
+ * Telegram's `file_unique_id`, with the `file_id` needed to send them again
+ * and a meaning note the agent writes, so it can pick a sticker by what it
+ * says rather than by id.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { STATUS_DIR } from './constants.js'
+
+/** Default library file. */
+export const STICKER_LIBRARY_PATH = join(STATUS_DIR, 'stickers.json')
+/** Folder for cached preview images. */
+export const STICKER_PREVIEW_DIR = join(STATUS_DIR, 'sticker-previews')
+/** Longest meaning note kept, in characters. */
+export const STICKER_MEANING_MAX = 1000
+
+/**
+ * The kind of a Telegram sticker.
+ * @param sticker - Bot API Sticker.
+ * @returns `static`, `animated` (.tgs) or `video` (.webm).
+ */
+export function stickerKind(sticker) {
+  if (sticker?.is_video === true) return 'video'
+  if (sticker?.is_animated === true) return 'animated'
+  return 'static'
+}
+
+/**
+ * One line that names a sticker for the agent.
+ * @param entry - library entry.
+ * @returns e.g. `😀 from set "cats" (sticker AgAD..., animated)`.
+ */
+export function describeSticker(entry) {
+  const parts = []
+  if (typeof entry?.emoji === 'string' && entry.emoji.length > 0) parts.push(entry.emoji)
+  if (typeof entry?.setName === 'string' && entry.setName.length > 0) {
+    parts.push(`from set "${entry.setName}"${typeof entry.setTitle === 'string' && entry.setTitle.length > 0 && entry.setTitle !== entry.setName ? ` (${entry.setTitle})` : ''}`)
+  }
+  parts.push(`(sticker ${entry?.id}${entry?.kind === 'static' || entry?.kind === undefined ? '' : `, ${entry.kind}`})`)
+  return parts.join(' ')
+}
+
+/**
+ * Open the library. Reading happens once, on first use; a missing or broken
+ * file starts an empty library.
+ * @param options.path - library file.
+ * @param options.now - clock, for tests.
+ * @param options.onError - reports a failed write.
+ * @returns the library API.
+ */
+export function createStickerLibrary({ path = STICKER_LIBRARY_PATH, now = Date.now, onError = () => {} } = {}) {
+  let stickers
+  let loading
+  let writing = Promise.resolve()
+
+  async function load() {
+    if (stickers !== undefined) return stickers
+    loading ??= (async () => {
+      try {
+        const data = JSON.parse(await readFile(path, 'utf8'))
+        stickers = data?.stickers !== null && typeof data?.stickers === 'object' ? data.stickers : {}
+      } catch {
+        stickers = {}
+      }
+      return stickers
+    })()
+    return loading
+  }
+
+  function save() {
+    const snapshot = JSON.stringify({ version: 1, stickers }, null, 1) + '\n'
+    writing = writing.then(async () => {
+      await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+      const temporary = `${path}.tmp`
+      await writeFile(temporary, snapshot, { mode: 0o600 })
+      await rename(temporary, path)
+    }).catch(onError)
+    return writing
+  }
+
+  /**
+   * Add or refresh stickers without saving.
+   * @returns the stored entries.
+   */
+  function upsert(list, { setTitle, source }) {
+    const time = new Date(now()).toISOString()
+    const stored = []
+    for (const sticker of list) {
+      const id = sticker?.file_unique_id
+      if (typeof id !== 'string' || id.length === 0 || typeof sticker.file_id !== 'string') continue
+      const old = stickers[id]
+      const entry = {
+        id,
+        fileId: sticker.file_id,
+        setName: typeof sticker.set_name === 'string' ? sticker.set_name : (old?.setName ?? null),
+        setTitle: typeof setTitle === 'string' ? setTitle : (old?.setTitle ?? null),
+        emoji: typeof sticker.emoji === 'string' ? sticker.emoji : (old?.emoji ?? null),
+        kind: stickerKind(sticker),
+        thumbnailId: sticker.thumbnail?.file_id ?? sticker.thumb?.file_id ?? old?.thumbnailId ?? null,
+        meaning: old?.meaning ?? '',
+        source: old?.source ?? source ?? 'received',
+        addedAt: old?.addedAt ?? time,
+        updatedAt: time,
+      }
+      stickers[id] = entry
+      stored.push(entry)
+    }
+    return stored
+  }
+
+  return {
+    /**
+     * Add or refresh stickers (a received one, or a whole set). The meaning
+     * already written for a sticker is kept.
+     * @param list - Bot API Sticker objects.
+     * @param options - `{ setTitle, source }`: set title, and `received` or `set`.
+     * @returns the stored entries.
+     */
+    async remember(list, options = {}) {
+      await load()
+      const stored = upsert(Array.isArray(list) ? list : [list], options)
+      if (stored.length > 0) await save()
+      return stored
+    },
+    /**
+     * @param id - `file_unique_id`.
+     * @returns the entry, or undefined.
+     */
+    async get(id) {
+      await load()
+      return typeof id === 'string' ? stickers[id] : undefined
+    },
+    /**
+     * Write what a sticker means and when to use it.
+     * @param id - `file_unique_id`.
+     * @param meaning - free text; empty clears it.
+     * @returns the entry.
+     * @throws when the sticker is not in the library.
+     */
+    async setMeaning(id, meaning) {
+      await load()
+      const entry = typeof id === 'string' ? stickers[id] : undefined
+      if (entry === undefined) throw new Error(`Sticker ${id} is not in the library.`)
+      entry.meaning = String(meaning ?? '').trim().slice(0, STICKER_MEANING_MAX)
+      entry.updatedAt = new Date(now()).toISOString()
+      await save()
+      return entry
+    },
+    /**
+     * Find stickers. Every given filter must match; `query` matches any of its
+     * words in the meaning, emoji, set name or title, and better matches come
+     * first. Without filters, the latest stickers come first.
+     * @param filters - `{ query, emoji, set, limit }`.
+     * @returns `{ total, stickers }`.
+     */
+    async find({ query, emoji, set, limit = 20 } = {}) {
+      await load()
+      const words = String(query ?? '').toLowerCase().split(/\s+/u).filter((word) => word.length > 0)
+      const wantedEmoji = typeof emoji === 'string' && emoji.trim().length > 0 ? emoji.trim() : undefined
+      const wantedSet = typeof set === 'string' && set.trim().length > 0 ? set.trim().toLowerCase() : undefined
+      const scored = []
+      for (const entry of Object.values(stickers)) {
+        if (wantedEmoji !== undefined && !String(entry.emoji ?? '').includes(wantedEmoji)) continue
+        if (wantedSet !== undefined && String(entry.setName ?? '').toLowerCase() !== wantedSet && String(entry.setTitle ?? '').toLowerCase() !== wantedSet) continue
+        let score = 0
+        if (words.length > 0) {
+          const meaning = String(entry.meaning ?? '').toLowerCase()
+          const other = [entry.emoji, entry.setName, entry.setTitle].map((value) => String(value ?? '').toLowerCase()).join(' ')
+          for (const word of words) {
+            if (meaning.includes(word)) score += 2
+            else if (other.includes(word)) score += 1
+          }
+          if (score === 0) continue
+        }
+        scored.push({ entry, score })
+      }
+      scored.sort((left, right) => right.score - left.score || String(right.entry.updatedAt).localeCompare(String(left.entry.updatedAt)))
+      const count = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, 100) : 20
+      return { total: scored.length, stickers: scored.slice(0, count).map(({ entry }) => entry) }
+    },
+    /** Wait for pending writes (tests and shutdown). */
+    flush: () => writing,
+  }
+}