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

package/src/controls.js

@@ -0,0 +1,214 @@
+/**
+ * Session controls from a chat: model, reasoning effort, access mode and
+ * context use, picked from numbered lists.
+ */
+import { defaultModelOf, effortChoices, effortName, findModel, modelName, pickedSelection, sessionModelOf } from './models.js'
+import { controllerOf, currentPermission, permissionOptions, setPermission } from './sessions.js'
+
+/** @returns `n` as a 1-based list index into `items`, or undefined. */
+export function pick(items, value) {
+  const number = Number(value)
+  return Number.isSafeInteger(number) && number >= 1 && number <= items.length ? items[number - 1] : undefined
+}
+
+/** The chat's session id, or undefined. */
+export function sessionOf(bridge, chatId) {
+  const id = bridge.store().chat(chatId)?.sessionId
+  return typeof id === 'string' ? id : undefined
+}
+
+/** The chat session's live agent when it is loaded, or undefined. */
+export function liveAgent(bridge, chatId) {
+  const sessionId = sessionOf(bridge, chatId)
+  return sessionId === undefined ? undefined : bridge.ctx.get('agents')?.get(sessionId)
+}
+
+/** @returns a compact token count, such as 1M or 12.3k. */
+function formatTokens(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return '?'
+  if (value >= 1_000_000) return `${Math.round(value / 100_000) / 10}M`
+  if (value >= 1000) return `${Math.round(value / 100) / 10}k`
+  return String(value)
+}
+
+/** @returns context use, such as "16.8k of 1M" or "16.8k used". */
+function contextLabel({ used, windowSize }) {
+  if (used === undefined) return windowSize === undefined ? 'unknown' : `${formatTokens(windowSize)} window`
+  return windowSize === undefined ? `${formatTokens(used)} used` : `${formatTokens(used)} of ${formatTokens(windowSize)}`
+}
+
+/** Model, effort and access mode of a chat's session. */
+async function controls(bridge, chatId) {
+  const catalog = await bridge.modelCatalog.load()
+  const sessionId = sessionOf(bridge, chatId)
+  const current = await sessionModelOf(bridge.ctx, sessionId) ?? defaultModelOf(bridge.ctx)
+  const agent = liveAgent(bridge, chatId)
+  const mode = currentPermission(bridge.ctx, agent)
+  const modeName = permissionOptions(bridge.ctx).find((option) => option.value === mode)?.name ?? mode ?? '?'
+  return { catalog, current, mode, modeName }
+}
+
+/** Context window and last request size of a chat's session. */
+async function contextUse(bridge, chatId, current) {
+  let windowSize
+  try {
+    const llm = bridge.ctx.get('llm')
+    const resolve = llm?.resolveModelInfo ?? llm?.resolveModel
+    const info = current === undefined || resolve === undefined ? undefined : await resolve.call(llm, current.provider, current.model)
+    windowSize = info?.context?.contextWindow
+  } catch {
+    // Unknown.
+  }
+  if (windowSize === undefined) {
+    const catalog = await bridge.modelCatalog.load()
+    windowSize = findModel(catalog, current)?.model?.contextWindow
+  }
+  let used
+  const sessionId = sessionOf(bridge, chatId)
+  if (sessionId !== undefined) {
+    try {
+      const events = (await bridge.ctx.get('sessionQuery')?.readSurface(sessionId))?.events ?? []
+      for (let index = events.length - 1; index >= 0; index -= 1) {
+        const usage = events[index]?.type === 'assistant/message' ? (events[index].data?.usage ?? events[index].data?.message?.usage) : undefined
+        if (usage === undefined) continue
+        used = (usage.inputTokens ?? 0) + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+        break
+      }
+    } catch {
+      // Unknown.
+    }
+  }
+  return { windowSize, used }
+}
+
+/** Apply a model selection the way the Web picker does, and remember it for /new. */
+async function selectModel(bridge, chatId, selection) {
+  const store = bridge.store()
+  store.data.picks[String(chatId)] = selection
+  await store.save()
+  const agent = await bridge.ensureAgent(chatId, { claim: true })
+  const controller = controllerOf(bridge.ctx)
+  if (typeof controller?.selectModel === 'function') {
+    await controller.selectModel({ sessionId: agent.session?.id ?? agent.id, ...selection })
+    return
+  }
+  agent.model.select(selection)
+}
+
+/** Handlers of the control commands, merged into the command table. */
+export const CONTROL_HANDLERS = {
+  async menu(bridge, { chatId }) {
+    const { catalog, current, modeName } = await controls(bridge, chatId)
+    const context = await contextUse(bridge, chatId, current)
+    await bridge.notice(chatId, [
+      'Session controls:',
+      `🤖 Model: ${modelName(catalog, current)} — /model`,
+      `🧠 Effort: ${effortName(catalog, current, 'Default')} — /effort`,
+      `🛡 Access: ${modeName} — /mode`,
+      `📚 Context: ${contextLabel(context)} — /context`,
+    ].join('\n'))
+  },
+
+  async model(bridge, { chatId }, args) {
+    const { catalog, current } = await controls(bridge, chatId)
+    if (catalog === undefined || catalog.groups.length === 0) {
+      await bridge.notice(chatId, 'No models are available right now.')
+      return
+    }
+    const [first, second] = args.split(/\s+/u).filter(Boolean)
+    if (first === undefined) {
+      await bridge.notice(chatId, [
+        `Model now: ${modelName(catalog, current)}`,
+        '',
+        ...catalog.groups.map((group, index) => `${index + 1}. ${group.name ?? group.id} (${group.models.length})${group.id === current?.provider ? ' ✅' : ''}`),
+        ...(catalog.failures.length > 0 ? ['', `Unavailable: ${catalog.failures.map((failure) => failure.name ?? failure.id).join(', ')}`] : []),
+        '',
+        '/model <n> lists the models of provider n.',
+      ].join('\n'))
+      return
+    }
+    const group = pick(catalog.groups, first)
+    if (group === undefined) {
+      await bridge.notice(chatId, `No provider ${first}; /model lists them.`)
+      return
+    }
+    if (second === undefined) {
+      await bridge.notice(chatId, [
+        `${group.name ?? group.id}:`,
+        ...group.models.map((model, index) => `${index + 1}. ${model.name ?? model.id}${group.id === current?.provider && model.id === current?.model ? ' ✅' : ''}`),
+        '',
+        `/model ${first} <n> switches this chat's session to model n.`,
+      ].join('\n'))
+      return
+    }
+    const model = pick(group.models, second)
+    if (model === undefined) {
+      await bridge.notice(chatId, `No model ${second}; /model ${first} lists them.`)
+      return
+    }
+    await selectModel(bridge, chatId, pickedSelection(current, group.id, model))
+    await bridge.notice(chatId, `🤖 Model: ${model.name ?? model.id}`)
+  },
+
+  async effort(bridge, { chatId }, args) {
+    const { catalog, current } = await controls(bridge, chatId)
+    const model = findModel(catalog, current)?.model
+    const choices = effortChoices(model, 'Default')
+    if (choices.length === 0) {
+      await bridge.notice(chatId, 'This model has no effort setting.')
+      return
+    }
+    const effective = current?.reasoningEffort ?? model?.reasoning?.defaultEffort
+    if (args.length === 0) {
+      await bridge.notice(chatId, [
+        'Reasoning effort:',
+        ...choices.map((choice, index) => `${index + 1}. ${choice.name}${choice.id === effective ? ' ✅' : ''}`),
+        '',
+        '/effort <n> picks one.',
+      ].join('\n'))
+      return
+    }
+    const choice = pick(choices, args.split(/\s+/u)[0])
+    if (choice === undefined || current === undefined) {
+      await bridge.notice(chatId, `No effort ${args}; /effort lists them.`)
+      return
+    }
+    await selectModel(bridge, chatId, { provider: current.provider, model: current.model, ...(choice.id === undefined ? {} : { reasoningEffort: choice.id }) })
+    await bridge.notice(chatId, `🧠 Effort: ${choice.name}`)
+  },
+
+  async mode(bridge, { chatId }, args) {
+    const options = permissionOptions(bridge.ctx)
+    const { mode } = await controls(bridge, chatId)
+    if (args.length === 0) {
+      await bridge.notice(chatId, [
+        'Access mode of this session:',
+        ...options.map((option, index) => `${index + 1}. ${option.name}${option.value === mode ? ' ✅' : ''}`),
+        '',
+        '/mode <n> picks one.',
+      ].join('\n'))
+      return
+    }
+    const option = pick(options, args.split(/\s+/u)[0])
+    if (option === undefined) {
+      await bridge.notice(chatId, `No mode ${args}; /mode lists them.`)
+      return
+    }
+    setPermission(bridge.ctx, await bridge.ensureAgent(chatId, { claim: true }), option.value)
+    await bridge.notice(chatId, `🛡 Access: ${option.name}`)
+  },
+
+  async context(bridge, { chatId }) {
+    const { catalog, current, modeName } = await controls(bridge, chatId)
+    const context = await contextUse(bridge, chatId, current)
+    await bridge.notice(chatId, [
+      'Context:',
+      `Model: ${modelName(catalog, current)}${current === undefined ? '' : ` (${current.provider}/${current.model})`}`,
+      `Window: ${formatTokens(context.windowSize)}`,
+      `Last request: ${context.used === undefined ? 'unknown' : formatTokens(context.used)}`,
+      `Effort: ${effortName(catalog, current, 'Default')}`,
+      `Access: ${modeName}`,
+    ].join('\n'))
+  },
+
+}

package/src/core.js

@@ -0,0 +1,236 @@
+/**
+ * The Delta Chat side: one chatmail profile driven through the official
+ * `deltachat-rpc-server` (JSON-RPC over stdio).
+ *
+ * The server is spawned here rather than with `startDeltaChat` from
+ * `@deltachat/stdio-rpc-server`, because that helper throws from the child's
+ * `exit` and `error` handlers, which would take the whole Host process down
+ * when the server quits. Here an unexpected exit resolves `exited`.
+ */
+import { spawn } from 'node:child_process'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { extname, join } from 'node:path'
+import { getRPCServerPath } from '@deltachat/stdio-rpc-server'
+import { StdioDeltaChat } from '@deltachat/jsonrpc-client'
+import { vcardFingerprint } from './identity.js'
+
+/** Connectivity at or above this value means connected (DC_CONNECTIVITY_CONNECTED is 4000). */
+const CONNECTED = 4000
+/** Connectivity at or above this value is at least trying (connecting, working). */
+const CONNECTING = 3000
+
+/**
+ * A complete `MessageData` object; the RPC server wants every field.
+ * @param data - fields to set.
+ * @returns the message data.
+ */
+export function messageData(data) {
+  return {
+    text: null,
+    html: null,
+    viewtype: null,
+    file: null,
+    filename: null,
+    location: null,
+    overrideSenderName: null,
+    quotedMessageId: null,
+    quotedText: null,
+    ...data,
+  }
+}
+
+/** File extensions and the Delta Chat view type they are sent as. */
+const VIEW_TYPES = new Map([
+  ['.jpg', 'Image'], ['.jpeg', 'Image'], ['.png', 'Image'], ['.webp', 'Image'], ['.heic', 'Image'],
+  ['.gif', 'Gif'],
+  ['.mp4', 'Video'], ['.mov', 'Video'], ['.webm', 'Video'], ['.mkv', 'Video'],
+  ['.mp3', 'Audio'], ['.m4a', 'Audio'], ['.ogg', 'Audio'], ['.opus', 'Audio'], ['.wav', 'Audio'], ['.flac', 'Audio'],
+])
+
+/**
+ * How a file is shown in Delta Chat, by its extension.
+ * @param path - file path.
+ * @returns a Delta Chat view type.
+ */
+export function viewTypeOf(path) {
+  return VIEW_TYPES.get(extname(String(path)).toLowerCase()) ?? 'File'
+}
+
+/**
+ * Start the RPC server on an accounts directory.
+ * @param options - `{ dir, log }`.
+ * @returns `{ dc, close, exited }`; `dc` is a `StdioDeltaChat` with its event
+ *   loop running; `exited` resolves with an error when the server quits
+ *   without `close` (requests in flight then never settle, so callers race
+ *   their work against it).
+ */
+export async function startServer({ dir, log }) {
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const binary = getRPCServerPath()
+  const child = spawn(binary, [], {
+    env: {
+      ...(process.env.RUST_LOG === undefined ? {} : { RUST_LOG: process.env.RUST_LOG }),
+      DC_ACCOUNTS_PATH: dir,
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+  let closing = false
+  let stderr = ''
+  let reportExit
+  const exited = new Promise((resolve) => { reportExit = resolve })
+  child.stderr.on('data', (chunk) => {
+    stderr = (stderr + chunk.toString('utf8')).slice(-2000)
+  })
+  child.on('error', (error) => {
+    if (!closing) reportExit(new Error(`deltachat-rpc-server could not run: ${error.message}`))
+  })
+  child.on('exit', (code, signal) => {
+    if (closing) return
+    const tail = stderr.trim().split('\n').slice(-3).join(' | ')
+    reportExit(new Error(`deltachat-rpc-server quit (${signal ?? `code ${code}`})${tail ? `: ${tail}` : ''}`))
+  })
+  // Writes after the server died must not become uncaught errors.
+  child.stdin.on('error', (error) => log?.(`rpc stdin: ${error.message}`))
+  const dc = new StdioDeltaChat(child.stdin, child.stdout, true)
+  dc.eventTask?.catch?.((error) => {
+    if (!closing) log?.(`event loop stopped: ${error?.message ?? error}`)
+  })
+  return {
+    dc,
+    exited,
+    close() {
+      closing = true
+      child.kill()
+    },
+  }
+}
+
+/**
+ * Create the bot profile on the first start, or bring an existing one up to
+ * the configured relays and look.
+ * @param dc - client.
+ * @param options - `{ relays, displayName, avatar, log }`.
+ * @returns the account id.
+ */
+export async function ensureAccount(dc, { relays, displayName, avatar, log }) {
+  const ids = await dc.rpc.getAllAccountIds()
+  const accountId = ids[0] ?? await dc.rpc.addAccount()
+  await dc.rpc.batchSetConfig(accountId, { bot: '1', displayname: displayName || 'DSH' })
+  if (typeof avatar === 'string' && avatar.length > 0) {
+    try {
+      await dc.rpc.setConfig(accountId, 'selfavatar', avatar)
+    } catch (error) {
+      log?.(`avatar ${avatar} not set: ${error?.message ?? error}`)
+    }
+  }
+  const wanted = relays.map((relay) => String(relay).trim().toLowerCase()).filter((relay) => relay.length > 0)
+  const present = new Set((await dc.rpc.listTransports(accountId).catch(() => []))
+    .map((transport) => String(transport.addr).split('@')[1]?.toLowerCase())
+    .filter(Boolean))
+  const failures = []
+  for (const relay of wanted) {
+    if (present.has(relay)) continue
+    try {
+      await dc.rpc.addTransportFromQr(accountId, `dcaccount:${relay}`)
+      present.add(relay)
+      log?.(`added relay ${relay}`)
+    } catch (error) {
+      failures.push(`${relay}: ${error?.message ?? error}`)
+    }
+  }
+  if (!await dc.rpc.isConfigured(accountId)) {
+    throw new Error(`no relay could create the Delta Chat profile (${failures.join('; ') || 'no relays configured'})`)
+  }
+  for (const failure of failures) log?.(`relay not added: ${failure}`)
+  return accountId
+}
+
+/**
+ * Write the bot's invite link and its QR code next to the profile.
+ * @param dc - client.
+ * @param accountId - account.
+ * @param dir - directory for `invite.txt` and `invite.svg`.
+ * @returns `{ link, svgPath }`.
+ */
+export async function writeInvite(dc, accountId, dir) {
+  const link = await dc.rpc.getChatSecurejoinQrCode(accountId, null)
+  const svg = await dc.rpc.createQrSvg(link)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  const svgPath = join(dir, 'invite.svg')
+  await writeFile(join(dir, 'invite.txt'), `${link}\n`, { mode: 0o600 })
+  await writeFile(svgPath, svg, { mode: 0o600 })
+  return { link, svgPath }
+}
+
+/**
+ * Fingerprints of contacts, cached by contact id. A contact's key never
+ * changes in Delta Chat (a new key is a new contact), so entries stay valid.
+ * @param dc - client.
+ * @param accountId - account.
+ * @returns `get(contactId)` resolving to the fingerprint or ''.
+ */
+export function createFingerprints(dc, accountId) {
+  const cache = new Map()
+  return {
+    async get(contactId) {
+      if (cache.has(contactId)) return cache.get(contactId)
+      let fingerprint = ''
+      try {
+        fingerprint = vcardFingerprint(await dc.rpc.makeVcard(accountId, [contactId]))
+      } catch {
+        fingerprint = ''
+      }
+      if (fingerprint !== '') cache.set(contactId, fingerprint)
+      return fingerprint
+    },
+  }
+}
+
+/**
+ * Keep IO healthy: restart it when connectivity stays down or the inbox has
+ * been quiet for too long, and nudge the network now and then. Delta Chat
+ * recovers by itself in most cases; this covers long sleeps and dead sockets.
+ * @param dc - client.
+ * @param accountId - account.
+ * @param log - logger for restarts.
+ * @returns a stop function.
+ */
+export function startWatchdog(dc, accountId, log) {
+  let bad = 0
+  let lastIdle = Date.now()
+  const onIdle = (contextId) => {
+    if (contextId === accountId) lastIdle = Date.now()
+  }
+  dc.on('ImapInboxIdle', onIdle)
+  const restart = async (reason) => {
+    log(`restarting IO: ${reason}`)
+    try {
+      await dc.rpc.stopIo(accountId)
+      await dc.rpc.startIo(accountId)
+      lastIdle = Date.now()
+      bad = 0
+    } catch (error) {
+      log(`IO restart failed: ${error?.message ?? error}`)
+    }
+  }
+  const check = setInterval(async () => {
+    try {
+      const connectivity = await dc.rpc.getConnectivity(accountId)
+      bad = connectivity < CONNECTING ? bad + 1 : 0
+      if (bad >= 2) await restart(`connectivity ${connectivity} on two checks`)
+      else if (Date.now() - lastIdle > 20 * 60_000 && connectivity < CONNECTED) await restart('no inbox idle for 20 minutes')
+    } catch (error) {
+      log(`watchdog: ${error?.message ?? error}`)
+    }
+  }, 5 * 60_000)
+  const nudge = setInterval(() => {
+    dc.rpc.maybeNetwork().catch(() => {})
+  }, 10 * 60_000)
+  check.unref?.()
+  nudge.unref?.()
+  return () => {
+    clearInterval(check)
+    clearInterval(nudge)
+    dc.off?.('ImapInboxIdle', onIdle)
+  }
+}

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 }
+}