@soffits/dsh-deltachat-bot 0.0.0-stage → 0.1.0

package/src/models.js

@@ -0,0 +1,191 @@
+/**
+ * Model selection for chats. The session's live agent owns its model
+ * (`agent.model.current()`); the bot keeps no copy of it. Lists come from the
+ * same catalog as the Web model picker (`sessionController.modelCatalog()`),
+ * so every configured provider and model shows with its Web display name.
+ */
+
+/** How long one catalog read is reused for labels and menus. */
+const CATALOG_TTL_MS = 60_000
+
+/**
+ * Copy a selection, dropping an absent effort.
+ * @param selection - provider, model and optional effort.
+ * @returns a detached selection.
+ */
+function toSelection({ provider, model, reasoningEffort }) {
+  return { provider, model, ...(reasoningEffort === undefined ? {} : { reasoningEffort }) }
+}
+
+/**
+ * Read a session's current model: the live agent's own choice, or, for a
+ * session that is not running, its recorded selection.
+ * @param ctx - Host context.
+ * @param sessionId - DSH session id.
+ * @returns the selection, or undefined when the session has none recorded.
+ */
+export async function sessionModelOf(ctx, sessionId) {
+  if (typeof sessionId !== 'string') return undefined
+  const agent = ctx.get('agents')?.get(sessionId)
+  if (typeof agent?.model?.current === 'function') {
+    const current = agent.model.current()
+    return current === undefined ? undefined : toSelection(current)
+  }
+  const query = ctx.get('sessionQuery')
+  if (typeof query?.observeSession !== 'function') return undefined
+  let observation
+  try {
+    observation = await query.observeSession(sessionId)
+    // The modelSelection projection's view: `next` is the pending choice or
+    // the route of the last request.
+    const view = observation?.projections?.values?.modelSelection
+    const recorded = view?.next ?? view?.pending ?? view?.lastUsed
+    return typeof recorded?.provider === 'string' && typeof recorded?.model === 'string' ? toSelection(recorded) : undefined
+  } catch {
+    return undefined
+  } finally {
+    observation?.[Symbol.dispose]?.()
+  }
+}
+
+/**
+ * Read the deployment default model (the one the Web UI saves).
+ * @param ctx - Host context.
+ * @returns the selection, or undefined without a default-model service.
+ */
+export function defaultModelOf(ctx) {
+  try {
+    const selection = ctx.get('agentDefaultModel')?.currentSelection()
+    if (typeof selection?.provider === 'string' && typeof selection?.model === 'string') return toSelection(selection)
+  } catch {
+    // No default configured.
+  }
+  return undefined
+}
+
+/**
+ * Whether the catalog no longer offers a selection's provider or model, for
+ * example after a provider was removed from the profile. A provider the
+ * catalog reports as failing is not counted: its models are unknown now, not
+ * gone. Without a catalog nothing is called gone.
+ * @param catalog - loaded catalog, or undefined.
+ * @param selection - provider and model, or undefined.
+ * @returns true when the selection names something the catalog dropped.
+ */
+export function isGoneModel(catalog, selection) {
+  if (catalog === undefined || typeof selection?.provider !== 'string' || typeof selection?.model !== 'string') return false
+  if (catalog.failures.some((failure) => failure?.id === selection.provider)) return false
+  return findModel(catalog, selection) === undefined
+}
+
+/**
+ * Whether two selections name the same provider, model and effort.
+ * @param left - first selection.
+ * @param right - second selection.
+ * @returns true when they agree.
+ */
+export function sameSelection(left, right) {
+  return left?.provider === right?.provider && left?.model === right?.model && left?.reasoningEffort === right?.reasoningEffort
+}
+
+/**
+ * Cached reader for the Web model catalog.
+ * @param ctx - Host context.
+ * @returns `load()` resolving the catalog, or undefined when it is unavailable.
+ */
+export function createModelCatalog(ctx) {
+  let cached
+  let loadedAt = 0
+  let pending
+  return {
+    /**
+     * @param fresh - skip the short-lived cache (used before applying a pick).
+     * @returns `{ groups, failures }` as the Web picker gets it, or undefined.
+     */
+    async load(fresh = false) {
+      if (!fresh && cached !== undefined && Date.now() - loadedAt < CATALOG_TTL_MS) return cached
+      pending ??= (async () => {
+        const controller = ctx.get('sessionController')
+        if (typeof controller?.modelCatalog !== 'function') return undefined
+        const catalog = await controller.modelCatalog()
+        cached = { groups: Array.isArray(catalog?.groups) ? catalog.groups : [], failures: Array.isArray(catalog?.failures) ? catalog.failures : [] }
+        loadedAt = Date.now()
+        return cached
+      })().finally(() => { pending = undefined })
+      try {
+        return await pending
+      } catch {
+        return cached
+      }
+    },
+  }
+}
+
+/**
+ * Find a catalog entry for a selection.
+ * @param catalog - loaded catalog.
+ * @param selection - provider and model.
+ * @returns `{ group, model }`, or undefined.
+ */
+export function findModel(catalog, selection) {
+  const group = catalog?.groups.find((entry) => entry.id === selection?.provider)
+  const model = group?.models.find((entry) => entry.id === selection?.model)
+  return model === undefined ? undefined : { group, model }
+}
+
+/**
+ * Display name of a selection's model, as the Web picker shows it.
+ * @param catalog - loaded catalog, or undefined.
+ * @param selection - provider and model.
+ * @returns the name, or the raw model id.
+ */
+export function modelName(catalog, selection) {
+  if (selection === undefined) return '?'
+  return findModel(catalog, selection)?.model.name ?? selection.model
+}
+
+/**
+ * Effort choices for one catalog model, the same list the Web picker builds:
+ * a provider-default entry when the model has no default effort, then its
+ * efforts. A model without reasoning has none.
+ * @param model - catalog model entry.
+ * @param defaultLabel - label for the provider default.
+ * @returns `{ id, name }` entries; `id` undefined means the provider default.
+ */
+export function effortChoices(model, defaultLabel) {
+  const reasoning = model?.reasoning
+  if (reasoning === undefined) return []
+  return [
+    ...(reasoning.defaultEffort === undefined ? [{ id: undefined, name: defaultLabel }] : []),
+    ...reasoning.efforts.map((effort) => ({ id: effort.id, name: effort.name })),
+  ]
+}
+
+/**
+ * Display name of a selection's effective effort.
+ * @param catalog - loaded catalog, or undefined.
+ * @param selection - current selection.
+ * @param defaultLabel - label for the provider default.
+ * @returns the name.
+ */
+export function effortName(catalog, selection, defaultLabel) {
+  const reasoning = findModel(catalog, selection)?.model.reasoning
+  const effective = selection?.reasoningEffort ?? reasoning?.defaultEffort
+  if (effective === undefined) return defaultLabel
+  return reasoning?.efforts.find((effort) => effort.id === effective)?.name ?? effective
+}
+
+/**
+ * The selection a model pick makes, by the Web picker's rule: the same model
+ * keeps its effort, another model starts at its default effort.
+ * @param current - the session's current selection.
+ * @param provider - picked provider id.
+ * @param model - picked catalog model entry.
+ * @returns the selection to apply.
+ */
+export function pickedSelection(current, provider, model) {
+  const same = current?.provider === provider && current?.model === model.id
+  const reasoningEffort = same ? current.reasoningEffort ?? model.reasoning?.defaultEffort : model.reasoning?.defaultEffort
+  return toSelection({ provider, model: model.id, reasoningEffort })
+}
+

package/src/operations.js

@@ -0,0 +1,174 @@
+/**
+ * What the bot offers outside chats: the send service, the chat list, the
+ * invite, joining someone's invite, allowing a key, and its status.
+ */
+import { randomUUID } from 'node:crypto'
+import { dataDir, POST_SOURCE_KIND } from './constants.js'
+import { allowedEntry, normalizeFingerprint } from './identity.js'
+import { finalError } from './outbound.js'
+import { recordMessage, resolveAgent } from './sessions.js'
+import { clip } from './text.js'
+
+/**
+ * The address an invite link names as the profile's primary relay address.
+ * @param link - invite link.
+ * @returns the address, or undefined.
+ */
+export function primaryAddress(link) {
+  const match = String(link ?? '').match(/[#&]a=([^&]+)/u)
+  return match === null ? undefined : decodeURIComponent(match[1].replace(/\+/gu, ' '))
+}
+
+/**
+ * Create the operations.
+ * @param deps - `{ ctx, getStore, storeReady, requireRuntime, getRuntime, getStatus, setting, outbound, currentTurn, writeInvite, info, reportError, messageOf }`.
+ */
+export function createOperations({ ctx, getStore, storeReady, requireRuntime, getRuntime, getStatus, setting, outbound, currentTurn, writeInvite, info, reportError, messageOf }) {
+  const { queueOut, sendText, sendFiles, checkFiles } = outbound
+
+  /**
+   * Send text, files or a reaction into a chat on behalf of a job, a session
+   * or a command, and record it in the session bound to that chat.
+   * @param request - `{ to, text, files, from, replyTo, reaction }`: `to` is
+   *   the chat id; `from` `{ job, sessionId, label }` names the sender;
+   *   `replyTo` quotes a message; `reaction` reacts to `replyTo` instead of
+   *   sending text.
+   * @returns where it went and whether the session recorded it.
+   */
+  async function sendToChat(request) {
+    await storeReady
+    const store = getStore()
+    const { dc, accountId } = requireRuntime()
+    const chatId = Number(request?.to)
+    if (!Number.isSafeInteger(chatId) || chatId <= 9) throw finalError(`Unknown chat ${request?.to}; /id in a chat shows its id.`)
+    const chatInfo = await dc.rpc.getBasicChatInfo(accountId, chatId).catch(() => undefined)
+    if (chatInfo === undefined || chatInfo.isDeviceChat) throw finalError(`Unknown chat ${chatId}; /id in a chat shows its id.`)
+    const replyTo = request?.replyTo === undefined || request?.replyTo === null ? undefined : Number(request.replyTo)
+    if (typeof request?.reaction === 'string') {
+      if (!Number.isSafeInteger(replyTo)) throw finalError('A reaction needs replyTo: the message id to react to.')
+      await dc.rpc.sendReaction(accountId, replyTo, request.reaction.length === 0 ? [] : [request.reaction])
+      return { chatId, reacted: replyTo }
+    }
+    const text = typeof request?.text === 'string' ? request.text.trim() : ''
+    const paths = Array.isArray(request?.files) ? request.files.map(String) : []
+    if (text.length === 0 && paths.length === 0) throw finalError('Nothing to send: give text or files.')
+    const files = await checkFiles(paths)
+    const messageIds = await queueOut(chatId, async () => {
+      const ids = text.length > 0 ? await sendText(chatId, text, { quote: replyTo }) : []
+      ids.push(...await sendFiles(chatId, files))
+      return ids
+    })
+    const from = request?.from ?? {}
+    const sessionId = store.chat(chatId)?.sessionId
+    const ownTurn = typeof from.sessionId === 'string' && from.sessionId === sessionId ? currentTurn(sessionId) : undefined
+    if (ownTurn !== undefined) ownTurn.sent = true
+    await store.noteSent({
+      chatId,
+      messageIds,
+      text,
+      files: files.map((file) => file.name),
+      job: typeof from.job === 'string' && from.job.trim() ? from.job.trim() : null,
+      fromSession: typeof from.sessionId === 'string' ? from.sessionId : null,
+      label: typeof from.label === 'string' ? from.label : null,
+    })
+    let recorded = false
+    let recordError
+    if (typeof sessionId === 'string') {
+      try {
+        const agent = await resolveAgent(ctx, sessionId)
+        const self = sessionId === from.sessionId
+        const by = self ? ' by this session' : from.job ? ` by job "${from.job}"` : from.sessionId ? ` by session ${from.sessionId}` : from.label ? ` by ${from.label}` : ''
+        const header = `Sent to Delta Chat chat "${chatInfo.name}"${by}`
+        const content = [{ type: 'text', text: `[${header}]${text ? `\n${text}` : ''}${files.length > 0 ? `\n[Files: ${files.map((file) => file.name).join(', ')}]` : ''}` }]
+        recordMessage(agent, { id: randomUUID(), role: 'user', content, source: { kind: POST_SOURCE_KIND, form: 'notice', summary: clip(header, 120), chatId, self } })
+        recorded = true
+      } catch (error) {
+        recordError = messageOf(error)
+        reportError('send-record', error)
+      }
+    }
+    return { chatId, chat: chatInfo.name, messageIds, sessionId: sessionId ?? null, recorded, ...(recordError ? { recordError } : {}) }
+  }
+
+  /** Known chats: every chat bound to a session, with its name. */
+  async function listChats() {
+    await storeReady
+    const store = getStore()
+    const { dc, accountId } = requireRuntime()
+    const result = []
+    for (const [chatId, record] of Object.entries(store.data.chats)) {
+      const chatInfo = await dc.rpc.getBasicChatInfo(accountId, Number(chatId)).catch(() => undefined)
+      if (chatInfo === undefined) continue
+      result.push({ chatId: Number(chatId), name: chatInfo.name, type: chatInfo.chatType, sessionId: record.sessionId ?? null })
+    }
+    return result
+  }
+
+  /** The bot's invite link and QR code file. */
+  async function invite() {
+    const { dc, accountId } = requireRuntime()
+    return writeInvite(dc, accountId, dataDir())
+  }
+
+  /** Secure-join someone's invite link (a contact or a group). */
+  async function joinInvite(link) {
+    const { dc, accountId } = requireRuntime()
+    const checked = await dc.rpc.checkQr(accountId, link)
+    if (!['askVerifyContact', 'askVerifyGroup', 'askJoinBroadcast'].includes(checked?.kind)) {
+      throw finalError(`Not an invite link (${checked?.kind ?? 'unknown'}).`)
+    }
+    const fingerprint = normalizeFingerprint(checked.fingerprint)
+    const allowed = allowedEntry(setting('allowedUsers', []), fingerprint)
+    if (allowed === undefined) {
+      throw finalError(`The invite belongs to key ${fingerprint || 'unknown'}, which is not in allowedUsers. Add it first.`)
+    }
+    const chatId = await dc.rpc.secureJoin(accountId, link)
+    info(`joining ${allowed.name || fingerprint} through their invite (chat ${chatId})`)
+    return { chatId, name: allowed.name, fingerprint }
+  }
+
+  /**
+   * Add someone to `allowedUsers` through the Host's config editor, which
+   * writes the profile's patch the same way the settings page does.
+   * @param fingerprint - their key fingerprint.
+   * @param label - how their messages are labelled.
+   */
+  async function allowUser(fingerprint, label) {
+    const normalized = normalizeFingerprint(fingerprint)
+    if (normalized === '') throw finalError('A key fingerprint has 40 hex characters.')
+    const entry = ctx.fiber?.entry
+    const editor = ctx.get('configEditor')
+    if (entry === undefined || editor === undefined) throw new Error('This profile cannot save the bot\'s configuration; add the fingerprint to allowedUsers by hand.')
+    await editor.edit(entry, (current) => {
+      const list = Array.isArray(current?.allowedUsers) ? current.allowedUsers.filter((item) => normalizeFingerprint(item?.fingerprint) !== normalized) : []
+      return { ...current, allowedUsers: [...list, { fingerprint: normalized, name: String(label ?? '').trim() }] }
+    })
+    await storeReady
+    await getStore().clearPending([normalized])
+    return { fingerprint: normalized, name: String(label ?? '').trim() }
+  }
+
+  /** Runtime facts for `/status` and the command line. */
+  async function describe() {
+    await storeReady
+    const store = getStore()
+    const runtime = getRuntime()
+    if (runtime === undefined) return { running: false, state: getStatus().state, detail: getStatus().detail ?? '' }
+    const { dc, accountId, startedAt } = runtime
+    const transports = await dc.rpc.listTransports(accountId).catch(() => [])
+    const connectivity = await dc.rpc.getConnectivity(accountId).catch(() => undefined)
+    const selfAddr = primaryAddress(await dc.rpc.getChatSecurejoinQrCode(accountId, null).catch(() => '')) ?? transports[0]?.addr ?? null
+    return {
+      running: true,
+      uptimeSeconds: Math.round((Date.now() - startedAt) / 1000),
+      primary: selfAddr,
+      relays: transports.map((transport) => transport.addr),
+      connectivity,
+      allowedUsers: setting('allowedUsers', []).length,
+      pending: Object.values(store.data.pending).map((entry) => ({ fingerprint: entry.fingerprint, displayName: entry.displayName, lastSeen: new Date(entry.lastSeen).toISOString(), count: entry.count })),
+      chats: Object.keys(store.data.chats).length,
+    }
+  }
+
+  return { sendToChat, listChats, invite, joinInvite, allowUser, describe }
+}

package/src/outbound.js

@@ -0,0 +1,79 @@
+/** Sending into chats: text made plain and split, files, notices, in order per chat. */
+import { stat } from 'node:fs/promises'
+import { basename, isAbsolute } from 'node:path'
+import { MAX_FILE_BYTES } from './constants.js'
+import { messageData, viewTypeOf } from './core.js'
+import { splitText, toPlainText } from './text.js'
+
+/** An error that a retry will not fix. */
+export function finalError(message) {
+  return Object.assign(new Error(message), { retryable: false })
+}
+
+/**
+ * Create the sender.
+ * @param deps - `{ requireRuntime, chatState, reportError, messageOf }`.
+ * @returns `{ queueOut, sendText, checkFiles, sendFiles, notice }`.
+ */
+export function createOutbound({ requireRuntime, chatState, reportError, messageOf }) {
+/** Run output for a chat in order. */
+  function queueOut(chatId, task) {
+    const chat = chatState(chatId)
+    const run = chat.out.catch(() => {}).then(task)
+    chat.out = run.catch((error) => reportError('send', error))
+    return run
+  }
+
+  // ---------------------------------------------------------------- outbound
+
+  /**
+   * Send text (Markdown is made plain) into a chat.
+   * @param chatId - chat id.
+   * @param text - Markdown text.
+   * @param options - `{ quote, plain }`: message id to quote on the first part;
+   *   `plain` skips the Markdown conversion.
+   * @returns the sent message ids.
+   */
+  async function sendText(chatId, text, { quote, plain = false } = {}) {
+    const { dc, accountId } = requireRuntime()
+    const ids = []
+    for (const [index, part] of splitText(plain ? text : toPlainText(text)).entries()) {
+      ids.push(await dc.rpc.sendMsg(accountId, chatId, messageData({ text: part, ...(index === 0 && Number.isSafeInteger(quote) ? { quotedMessageId: quote } : {}) })))
+    }
+    return ids
+  }
+
+  /**
+   * Check files before anything is sent.
+   * @param paths - absolute paths.
+   * @returns `{ path, name, size }` entries; throws on the first bad one.
+   */
+  async function checkFiles(paths) {
+    const files = []
+    for (const path of paths) {
+      if (!isAbsolute(path)) throw finalError(`File paths must be absolute: ${path}`)
+      const info = await stat(path).catch((error) => { throw finalError(`${path}: ${messageOf(error)}`) })
+      if (!info.isFile()) throw finalError(`${path} is not a file`)
+      if (info.size > MAX_FILE_BYTES) throw finalError(`${path} is larger than ${MAX_FILE_BYTES / 1024 / 1024} MB`)
+      files.push({ path, name: basename(path), size: info.size })
+    }
+    return files
+  }
+
+  /** Send checked files; the core copies each into its blob directory. */
+  async function sendFiles(chatId, files) {
+    const { dc, accountId } = requireRuntime()
+    const ids = []
+    for (const file of files) {
+      ids.push(await dc.rpc.sendMsg(accountId, chatId, messageData({ file: file.path, filename: file.name, viewtype: viewTypeOf(file.path) })))
+    }
+    return ids
+  }
+
+  /** A short bot notice (already plain text) into a chat. */
+  function notice(chatId, text) {
+    return queueOut(chatId, () => sendText(chatId, text, { plain: true }))
+  }
+
+  return { queueOut, sendText, checkFiles, sendFiles, notice }
+}

package/src/prompts.js

@@ -0,0 +1,179 @@
+/**
+ * Approval requests and agent questions for turns started from Delta Chat.
+ * Delta Chat has no buttons, so a question lists its options as numbers and
+ * the next message answers it; an approval waits for /allow or /deny.
+ */
+import { randomUUID } from 'node:crypto'
+
+/**
+ * Parse a reply to a question with options.
+ * @param text - the reply.
+ * @param question - `{ options, multiSelect }`.
+ * @returns `{ selected, custom }`: option labels picked by number, or the
+ *   whole reply as a free answer.
+ */
+export function parseAnswer(text, question) {
+  const options = Array.isArray(question?.options) ? question.options : []
+  const trimmed = String(text ?? '').trim()
+  if (options.length > 0 && /^\d+(?:[\s,]+\d+)*$/u.test(trimmed)) {
+    const numbers = trimmed.split(/[\s,]+/u).map(Number)
+    if (numbers.every((number) => number >= 1 && number <= options.length)) {
+      const picked = [...new Set(numbers)].map((number) => options[number - 1].label)
+      return { selected: question.multiSelect === true ? picked : picked.slice(0, 1), custom: undefined }
+    }
+  }
+  return { selected: [], custom: trimmed }
+}
+
+/**
+ * Text of one question.
+ * @param question - user question.
+ * @param index - its position.
+ * @param total - questions in the batch.
+ */
+export function questionText(question, index, total) {
+  const lines = []
+  if (question.header) lines.push(question.header)
+  lines.push(`❓ ${question.question}`)
+  if (question.detail) lines.push('', String(question.detail).slice(0, 3000))
+  const options = Array.isArray(question.options) ? question.options : []
+  if (options.length > 0) {
+    lines.push('')
+    for (const [number, option] of options.entries()) {
+      lines.push(`${number + 1}. ${option.label}${option.description ? ` — ${option.description}` : ''}`)
+    }
+    lines.push('', question.multiSelect === true
+      ? 'Reply with one or more numbers (like "1 3"), or write your own answer.'
+      : 'Reply with a number, or write your own answer.')
+  } else {
+    lines.push('', 'Reply with your answer.')
+  }
+  if (total > 1) lines.push(`(Question ${index + 1} of ${total}; /stop cancels.)`)
+  return lines.join('\n')
+}
+
+/**
+ * Create the prompt broker.
+ * @param options - `{ chatOfAgent, send, warn }`: `chatOfAgent(agent)` gives
+ *   the chat that should answer for a turn, or undefined to leave it to DSH.
+ * @returns `{ attach, consumeReply, settleApproval, cancelChat, cancelAll, pending }`.
+ */
+export function createPrompts({ chatOfAgent, send, warn }) {
+  const attached = new WeakSet()
+  /** Pending question batches by chat id. */
+  const questions = new Map()
+  /** Pending approvals by chat id (a list, oldest first). */
+  const approvals = new Map()
+
+  function finishQuestion(chatId, batch, error) {
+    if (questions.get(chatId) !== batch) return
+    questions.delete(chatId)
+    batch.signal?.removeEventListener('abort', batch.onAbort)
+    if (error === undefined) batch.resolve({ answers: batch.answers })
+    else batch.reject(error)
+  }
+
+  async function askQuestions(chatId, req, next) {
+    const list = Array.isArray(req.questions) ? req.questions : []
+    if (list.length === 0 || questions.has(chatId)) return next()
+    const signal = req.signal
+    if (signal?.aborted) return next()
+    return new Promise((resolve, reject) => {
+      const batch = { id: randomUUID(), questions: list, index: 0, answers: [], resolve, reject, signal, onAbort: undefined }
+      batch.onAbort = () => {
+        finishQuestion(chatId, batch, signal.reason ?? new Error('question cancelled'))
+        void send(chatId, '⏹ Question cancelled.')
+      }
+      signal?.addEventListener('abort', batch.onAbort, { once: true })
+      questions.set(chatId, batch)
+      Promise.resolve(send(chatId, questionText(list[0], 0, list.length))).catch((error) => {
+        warn(`question not sent: ${error?.message ?? error}`)
+        finishQuestion(chatId, batch, error)
+      })
+    })
+  }
+
+  async function askApproval(chatId, req) {
+    if (req.signal?.aborted) return 'cancelled'
+    const reason = req.displayReason?.en ?? req.reason ?? 'The tool asked for approval.'
+    return new Promise((resolve) => {
+      const entry = { resolve, toolName: req.toolName, signal: req.signal, onAbort: undefined }
+      entry.onAbort = () => settle(chatId, entry, 'cancelled')
+      req.signal?.addEventListener('abort', entry.onAbort, { once: true })
+      const list = approvals.get(chatId) ?? []
+      list.push(entry)
+      approvals.set(chatId, list)
+      Promise.resolve(send(chatId, `🔐 Approval needed for ${req.toolName}:\n${reason}\n\nReply /allow or /deny.`)).catch(() => settle(chatId, entry, 'unavailable'))
+    })
+  }
+
+  function settle(chatId, entry, outcome) {
+    const list = approvals.get(chatId) ?? []
+    const index = list.indexOf(entry)
+    if (index === -1) return false
+    list.splice(index, 1)
+    if (list.length === 0) approvals.delete(chatId)
+    entry.signal?.removeEventListener('abort', entry.onAbort)
+    entry.resolve(outcome)
+    return true
+  }
+
+  return {
+    /** Answer approval and question requests of an agent while its turn belongs to a chat. */
+    attach(agent) {
+      if (attached.has(agent) || typeof agent?.ctx?.on !== 'function') return
+      attached.add(agent)
+      agent.ctx.on('approval/request', (req, next) => {
+        const chatId = chatOfAgent(agent)
+        if (chatId === undefined) return next()
+        return askApproval(chatId, req)
+      }, { prepend: true })
+      agent.ctx.on('user-questions/request', (req, next) => {
+        const chatId = chatOfAgent(agent)
+        if (chatId === undefined) return next()
+        return askQuestions(chatId, req, next)
+      }, { prepend: true })
+    },
+    /**
+     * Take a message as the answer to the chat's open question.
+     * @returns true when the message answered a question.
+     */
+    consumeReply(chatId, text) {
+      const batch = questions.get(chatId)
+      if (batch === undefined || text.length === 0 || text.startsWith('/')) return false
+      const question = batch.questions[batch.index]
+      const { selected, custom } = parseAnswer(text, question)
+      batch.answers.push({ id: question.id, selected, ...(custom ? { custom } : {}) })
+      batch.index += 1
+      if (batch.index < batch.questions.length) {
+        void send(chatId, questionText(batch.questions[batch.index], batch.index, batch.questions.length))
+      } else {
+        finishQuestion(chatId, batch)
+      }
+      return true
+    },
+    /**
+     * Resolve the oldest approval of a chat.
+     * @returns the tool name, or undefined when none was waiting.
+     */
+    settleApproval(chatId, allowed) {
+      const entry = approvals.get(chatId)?.[0]
+      if (entry === undefined) return undefined
+      settle(chatId, entry, allowed ? 'allowed-once' : 'rejected')
+      return entry.toolName
+    },
+    /** Cancel what a chat was asked (on /stop). */
+    cancelChat(chatId) {
+      const batch = questions.get(chatId)
+      if (batch !== undefined) finishQuestion(chatId, batch, new Error('Question cancelled by /stop'))
+      for (const entry of [...(approvals.get(chatId) ?? [])]) settle(chatId, entry, 'cancelled')
+    },
+    cancelAll() {
+      for (const chatId of [...questions.keys(), ...approvals.keys()]) this.cancelChat(chatId)
+    },
+    /** @returns what a chat is being asked: `{ question, approvals }`. */
+    pending(chatId) {
+      return { question: questions.has(chatId), approvals: approvals.get(chatId)?.length ?? 0 }
+    },
+  }
+}