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

package/src/identity.js

@@ -0,0 +1,134 @@
+/**
+ * Who a Delta Chat contact is. Delta Chat contacts are identified by their
+ * OpenPGP key (addresses can change when someone moves or adds relays), so
+ * the allowlist and the sender label use the key fingerprint.
+ */
+import { createHash } from 'node:crypto'
+
+/**
+ * Normalize a fingerprint as typed or shown by Delta Chat ("3C1F 9E0A ...").
+ * @param value - fingerprint text.
+ * @returns 40 (v4) or 64 (v6) upper-case hex characters, or '' when invalid.
+ */
+export function normalizeFingerprint(value) {
+  const hex = String(value ?? '').replace(/[\s:]/gu, '').toUpperCase()
+  return /^(?:[0-9A-F]{40}|[0-9A-F]{64})$/u.test(hex) ? hex : ''
+}
+
+/**
+ * Read the first OpenPGP packet (the primary public key) of a key block.
+ * @param key - binary transferable public key.
+ * @returns `{ tag, body }`, or undefined when the data is not a packet.
+ */
+function firstPacket(key) {
+  if (key.length < 2 || (key[0] & 0x80) === 0) return undefined
+  const header = key[0]
+  let offset = 1
+  let length
+  let tag
+  if ((header & 0x40) !== 0) {
+    tag = header & 0x3f
+    const first = key[offset++]
+    if (first < 192) length = first
+    else if (first < 224) length = ((first - 192) << 8) + key[offset++] + 192
+    else if (first === 255) {
+      length = key.readUInt32BE(offset)
+      offset += 4
+    } else return undefined
+  } else {
+    tag = (header >> 2) & 0x0f
+    const type = header & 0x03
+    if (type === 0) length = key[offset++]
+    else if (type === 1) {
+      length = key.readUInt16BE(offset)
+      offset += 2
+    } else if (type === 2) {
+      length = key.readUInt32BE(offset)
+      offset += 4
+    } else return undefined
+  }
+  if (offset + length > key.length) return undefined
+  return { tag, body: key.subarray(offset, offset + length) }
+}
+
+/**
+ * Fingerprint of an OpenPGP public key (RFC 4880 v4: SHA-1 over 0x99, a
+ * two-byte length and the key packet; RFC 9580 v6: SHA-256 over 0x9B, a
+ * four-byte length and the packet).
+ * @param key - binary transferable public key.
+ * @returns the fingerprint in upper-case hex, or '' when it cannot be read.
+ */
+export function keyFingerprint(key) {
+  const packet = firstPacket(key)
+  if (packet === undefined || packet.tag !== 6 || packet.body.length === 0) return ''
+  const version = packet.body[0]
+  if (version === 4) {
+    const head = Buffer.from([0x99, (packet.body.length >> 8) & 0xff, packet.body.length & 0xff])
+    return createHash('sha1').update(head).update(packet.body).digest('hex').toUpperCase()
+  }
+  if (version === 6) {
+    const head = Buffer.alloc(5)
+    head[0] = 0x9b
+    head.writeUInt32BE(packet.body.length, 1)
+    return createHash('sha256').update(head).update(packet.body).digest('hex').toUpperCase()
+  }
+  return ''
+}
+
+/**
+ * Fingerprint of the key a vCard (from `makeVcard`) carries.
+ * @param vcard - vCard text.
+ * @returns the fingerprint, or '' when the card has no readable key.
+ */
+export function vcardFingerprint(vcard) {
+  const unfolded = String(vcard ?? '').replace(/\r?\n[ \t]/gu, '')
+  const match = unfolded.match(/^KEY[^:\n]*:data:application\/pgp-keys;base64\\?,([A-Za-z0-9+/=]+)\s*$/mu)
+  if (match === null) return ''
+  return keyFingerprint(Buffer.from(match[1], 'base64'))
+}
+
+/**
+ * Short form of a fingerprint for display: the first and last four groups.
+ * @param fingerprint - normalized fingerprint.
+ * @returns e.g. `3C1F 9E0A … 8ACE 1357`.
+ */
+export function shortFingerprint(fingerprint) {
+  const groups = String(fingerprint).match(/.{1,4}/gu) ?? []
+  if (groups.length <= 4) return groups.join(' ')
+  return `${groups.slice(0, 2).join(' ')} … ${groups.slice(-2).join(' ')}`
+}
+
+/**
+ * Find a fingerprint on the allowlist.
+ * @param allowed - configured `{ fingerprint, name }` entries.
+ * @param fingerprint - the contact's fingerprint.
+ * @returns the entry with its fingerprint normalized, or undefined.
+ */
+export function allowedEntry(allowed, fingerprint) {
+  const wanted = normalizeFingerprint(fingerprint)
+  if (wanted === '' || !Array.isArray(allowed)) return undefined
+  for (const entry of allowed) {
+    if (normalizeFingerprint(entry?.fingerprint) !== wanted) continue
+    const name = typeof entry.name === 'string' ? entry.name.trim() : ''
+    return { fingerprint: wanted, name }
+  }
+  return undefined
+}
+
+/**
+ * The line that tells the agent who wrote a message. The bot adds it from the
+ * sender's verified key, so text inside a message cannot fake it.
+ * @param sender - `{ name, fingerprint, displayName, chatId, messageId }`.
+ * @returns one bracketed line.
+ */
+export function senderLine({ name, fingerprint, displayName, chatId, messageId }) {
+  // The display name is chosen by the contact; keep it from shaping the line.
+  const shown = String(displayName ?? '').replace(/[\[\]"\r\n]/gu, ' ').replace(/\s+/gu, ' ').trim().slice(0, 64)
+  const who = name || shown || 'unknown'
+  const details = []
+  if (shown && shown !== name) details.push(`Delta Chat name "${shown}"`)
+  details.push(`key ${fingerprint}`)
+  if (Number.isSafeInteger(chatId)) details.push(`chat ${chatId}`)
+  if (Number.isSafeInteger(messageId)) details.push(`message ${messageId}`)
+  return `[Delta Chat message from ${who} (${details.join(', ')})]`
+}

package/src/inbound.js

@@ -0,0 +1,100 @@
+/**
+ * Turn one incoming Delta Chat message into a DSH prompt: the sender line,
+ * what it quotes, its text, and its file as an attachment (pictures as
+ * images, recordings transcribed).
+ */
+import { readFile, stat } from 'node:fs/promises'
+import { basename } from 'node:path'
+import { MAX_FILE_BYTES } from './constants.js'
+import { senderLine } from './identity.js'
+import { clip } from './text.js'
+import { transcribe, transcriptNote } from './voice.js'
+
+/** Longest quoted text passed to the agent. */
+const QUOTE_LIMIT = 2000
+/** Longest text of a message sent on someone's behalf passed to the agent. */
+const SENT_TEXT_LIMIT = 8000
+/** Image types the DSH attachment store takes as pictures. */
+const IMAGE_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif'])
+
+/**
+ * Describe what a message quotes.
+ * @param quote - `msg.quote`.
+ * @param context - `{ quotedOwn, sentRecord }`: whether the quoted message is
+ *   the bot's own and the send record it belongs to.
+ * @returns a context block, or undefined.
+ */
+export function describeQuote(quote, { quotedOwn, sentRecord } = {}) {
+  if (quote === null || quote === undefined) return undefined
+  const text = clip(quote.text ?? '', QUOTE_LIMIT)
+  if (quote.kind !== 'WithMessage') return `[Quoting:]\n${text}`
+  if (quotedOwn) {
+    if (sentRecord !== undefined) {
+      const by = sentRecord.job ? `job "${sentRecord.job}"` : sentRecord.fromSession ? `session ${sentRecord.fromSession}` : sentRecord.label || 'another sender'
+      const full = typeof sentRecord.text === 'string' && sentRecord.text.length > 0 ? clip(sentRecord.text, SENT_TEXT_LIMIT) : text
+      return `[Replying to a message ${by} sent here:]\n${full}`
+    }
+    return `[Replying to your earlier message:]\n${text}`
+  }
+  const author = quote.overrideSenderName || quote.authorDisplayName || 'someone'
+  return `[Replying to ${author}:]\n${text}`
+}
+
+/** Delta Chat view types that carry speech. */
+const SPOKEN = { Voice: 'voice message', Audio: 'audio file' }
+
+/**
+ * Build the prompt for one message.
+ * @param msg - Delta Chat message (`getMessage`).
+ * @param options - `{ sender, chatId, quotedOwn, sentRecord, attachments, voice, signal, warn }`:
+ *   `sender` is `{ name, fingerprint, displayName }`; `attachments` the DSH
+ *   attachment store; `voice` `{ mode, language, command, ffmpeg, speech }`.
+ * @returns `{ text, attachments }`.
+ */
+export async function composePrompt(msg, options) {
+  const { sender, chatId, attachments: store, voice, signal, warn } = options
+  const lines = [senderLine({ ...sender, chatId, messageId: msg.id })]
+  if (msg.isForwarded) lines.push('[Forwarded message]')
+  const quote = describeQuote(msg.quote, options)
+  if (quote !== undefined) lines.push(quote)
+  const blocks = []
+  if (typeof msg.file === 'string' && msg.file.length > 0) {
+    const name = msg.fileName || basename(msg.file)
+    const size = msg.fileBytes ?? (await stat(msg.file).catch(() => undefined))?.size ?? 0
+    const spoken = SPOKEN[msg.viewType]
+    if (spoken !== undefined && voice.mode !== 'off') {
+      const media = { kind: spoken, name, seconds: msg.duration > 0 ? Math.round(msg.duration / 1000) : undefined }
+      try {
+        const result = await transcribe({ ...voice, path: msg.file, signal })
+        lines.push(transcriptNote(media, { ...result, path: msg.file }))
+      } catch (error) {
+        lines.push(transcriptNote(media, { path: msg.file, error: error?.message ?? String(error) }))
+      }
+    } else if (size > MAX_FILE_BYTES) {
+      lines.push(`[File "${name}" (${size} bytes) is too large to attach; it is saved at ${msg.file}]`)
+    } else {
+      lines.push(`[${msg.viewType === 'Image' || msg.viewType === 'Gif' || msg.viewType === 'Sticker' ? 'Picture' : 'File'} "${name}", saved at ${msg.file}]`)
+    }
+    if (size <= MAX_FILE_BYTES && store !== undefined) {
+      try {
+        const data = await readFile(msg.file)
+        const mediaType = String(msg.fileMime ?? '').toLowerCase()
+        let block
+        if (IMAGE_TYPES.has(mediaType)) {
+          try {
+            block = { type: 'image', attachment: await store.saveImage({ data, mediaType, name }) }
+          } catch (error) {
+            warn?.(`${name} kept as a file, not an image: ${error?.message ?? error}`)
+          }
+        }
+        block ??= { type: 'file', attachment: await store.saveFile({ data, name }) }
+        blocks.push(block)
+      } catch (error) {
+        warn?.(`${name} not attached: ${error?.message ?? error}`)
+      }
+    }
+  }
+  const body = String(msg.text ?? '').trim()
+  if (body.length > 0) lines.push(body)
+  return { text: lines.join('\n'), attachments: blocks }
+}

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,183 @@
+/**
+ * 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 from = request?.from ?? {}
+    const sessionId = store.chat(chatId)?.sessionId
+    const ownTurn = typeof from.sessionId === 'string' && from.sessionId === sessionId ? currentTurn(sessionId) : undefined
+    // The answer of a turn this chat receives is delivered by itself, so text
+    // a session sends into its own chat would arrive twice.
+    const delivered = ownTurn !== undefined && (ownTurn.ours || ownTurn.goal || ownTurn.mirrored)
+    if (delivered && paths.length === 0) {
+      throw finalError('This session is bound to that chat and its answer is delivered there when the turn ends: write the text in your answer instead of sending it.')
+    }
+    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
+    })
+    if (ownTurn !== undefined) {
+      ownTurn.sent = true
+      if (text.length > 0) ownTurn.sentTexts.push(text)
+    }
+    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 }
+}