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

package/src/text.js

@@ -0,0 +1,175 @@
+/**
+ * Text going between DSH and Delta Chat: the answer a turn leaves, Markdown
+ * turned into readable plain text (Delta Chat apps show messages as plain
+ * text), splitting, and the silent marker.
+ */
+import { MAX_MESSAGE_TEXT, SILENT_REPLY } from './constants.js'
+
+/**
+ * The answer one assistant message holds: the last text block of a message
+ * that called no tool. Text written between tool calls is working narration,
+ * not part of the answer; a message that called a tool is mid-chain.
+ * @param message - an assistant message (`{ content: [...] }`).
+ * @returns the answer, or '' when the message holds none.
+ */
+export function messageAnswer(message) {
+  const content = Array.isArray(message?.content) ? message.content : []
+  if (content.some((block) => block?.type === 'tool-call')) return ''
+  const texts = content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text.trim())
+    .filter((text) => text.length > 0)
+  return texts.at(-1) ?? ''
+}
+
+/**
+ * Remove the silent marker from the end of an answer.
+ * @param text - final answer.
+ * @returns `{ text, silent }`: the rest of the text and whether the marker was there.
+ */
+export function stripSilent(text) {
+  const trimmed = String(text ?? '').trim()
+  if (!trimmed.endsWith(SILENT_REPLY)) return { text: trimmed, silent: false }
+  return { text: trimmed.slice(0, -SILENT_REPLY.length).trim(), silent: true }
+}
+
+/**
+ * Local image paths a Markdown answer shows inline (`![alt](/abs/path)` or a
+ * `file://` URL), outside code. Delta Chat cannot show them inline, so they
+ * are sent as files after the text.
+ * @param markdown - answer text.
+ * @returns absolute paths, without duplicates.
+ */
+export function localImagePaths(markdown) {
+  const found = []
+  const pattern = /!\[[^\]]*\]\(\s*(?:<([^>\n]+)>|([^)\s]+))(?:\s+"[^"\n]*")?\s*\)/gu
+  let fenced = false
+  for (const line of String(markdown ?? '').split('\n')) {
+    if (/^\s*```/u.test(line)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) continue
+    for (const match of line.split(/`[^`]*`/gu).join(' ').matchAll(pattern)) {
+      let target = (match[1] ?? match[2]).trim()
+      if (/^file:\/\//iu.test(target)) {
+        try {
+          target = decodeURIComponent(new URL(target).pathname)
+        } catch {
+          continue
+        }
+      }
+      if (target.startsWith('/') && !found.includes(target)) found.push(target)
+    }
+  }
+  return found
+}
+
+/**
+ * Inline Markdown of one line as plain text.
+ * @param line - text outside code fences.
+ * @returns the line without emphasis markers, with links spelled out.
+ */
+function plainInline(line) {
+  // Keep inline code as it is, without its backticks.
+  const parts = line.split(/(`[^`\n]+`)/gu)
+  return parts.map((part, index) => {
+    if (index % 2 === 1) return part.slice(1, -1)
+    let text = part
+    // Images: local ones are sent as files, remote ones keep their address.
+    text = text.replace(/!\[([^\]]*)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/gu, (_all, alt, target) => {
+      if (target.startsWith('/') || /^file:\/\//iu.test(target)) return alt.trim().length > 0 ? `[${alt.trim()}]` : ''
+      return alt.trim().length > 0 ? `${alt.trim()} (${target})` : target
+    })
+    text = text.replace(/\[([^\]]+)\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/gu, (_all, label, target) => {
+      const shown = label.trim()
+      return shown === target || shown === target.replace(/^mailto:/u, '') ? target : `${shown} (${target})`
+    })
+    text = text.replace(/<(https?:\/\/[^>\s]+)>/gu, '$1')
+    text = text.replace(/(\*\*|__)(?=\S)([^\n]*?\S)\1/gu, '$2')
+    text = text.replace(/(^|[\s(])\*(?=[^\s*])([^*\n]*?[^\s*])\*(?=$|[\s).,!?:;])/gu, '$1$2')
+    text = text.replace(/(^|[\s(])_(?=[^\s_])([^_\n]*?[^\s_])_(?=$|[\s).,!?:;])/gu, '$1$2')
+    text = text.replace(/~~(?=\S)([^\n]*?\S)~~/gu, '$1')
+    return text
+  }).join('')
+}
+
+/**
+ * Turn a Markdown answer into plain text that reads well in Delta Chat:
+ * emphasis markers and fence lines go, headings become plain lines, bullets
+ * become dots, links show their address, tables become rows of cells. Text
+ * inside code fences is kept exactly.
+ * @param markdown - answer text.
+ * @returns plain text.
+ */
+export function toPlainText(markdown) {
+  const out = []
+  let fenced = false
+  for (const raw of String(markdown ?? '').replace(/\r\n/gu, '\n').split('\n')) {
+    if (/^\s*(```|~~~)/u.test(raw)) {
+      fenced = !fenced
+      continue
+    }
+    if (fenced) {
+      out.push(raw)
+      continue
+    }
+    let line = raw
+    if (/^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/u.test(line) && line.includes('|')) continue
+    if (/^\s*([-*_])(\s*\1){2,}\s*$/u.test(line)) {
+      out.push('—')
+      continue
+    }
+    const heading = line.match(/^\s{0,3}#{1,6}\s+(.*?)\s*#*\s*$/u)
+    if (heading !== null) {
+      out.push(plainInline(heading[1]))
+      continue
+    }
+    if (/^\s*\|.*\|\s*$/u.test(line)) {
+      const cells = line.trim().slice(1, -1).split('|').map((cell) => plainInline(cell.trim()))
+      out.push(cells.join(' · '))
+      continue
+    }
+    line = line.replace(/^(\s*)[-*+]\s+\[( |x|X)\]\s+/u, (_all, indent, mark) => `${indent}${mark === ' ' ? '☐' : '☑'} `)
+    line = line.replace(/^(\s*)[-*+]\s+/u, '$1• ')
+    out.push(plainInline(line))
+  }
+  return out.join('\n').replace(/\n{3,}/gu, '\n\n').trim()
+}
+
+/**
+ * Split text into messages no longer than the limit, preferring paragraph,
+ * then line, then word boundaries.
+ * @param text - plain text.
+ * @param limit - longest message.
+ * @returns non-empty parts.
+ */
+export function splitText(text, limit = MAX_MESSAGE_TEXT) {
+  const parts = []
+  let rest = String(text ?? '').trim()
+  while (rest.length > limit) {
+    const window = rest.slice(0, limit)
+    let cut = window.lastIndexOf('\n\n')
+    if (cut < limit / 2) cut = window.lastIndexOf('\n')
+    if (cut < limit / 2) cut = window.lastIndexOf(' ')
+    if (cut < limit / 2) cut = limit
+    parts.push(rest.slice(0, cut).trim())
+    rest = rest.slice(cut).trim()
+  }
+  if (rest.length > 0) parts.push(rest)
+  return parts
+}
+
+/**
+ * Cut a preview to a length, on a word boundary when one is near.
+ * @param text - any text.
+ * @param max - longest result.
+ * @returns the preview, with an ellipsis when cut.
+ */
+export function clip(text, max) {
+  const value = String(text ?? '').trim()
+  if (value.length <= max) return value
+  const cut = value.slice(0, max - 1)
+  const space = cut.lastIndexOf(' ')
+  return `${space > max * 0.6 ? cut.slice(0, space) : cut}…`
+}

package/src/titles.js

@@ -0,0 +1,146 @@
+/**
+ * Session titles of chat sessions: `DeltaChat-<person>-<task>`. `person` is
+ * who the chat is with (a group's name for a group), `task` the conversation
+ * title DSH generates, or the chat's name until there is one. DSH has no title
+ * hook, so a generated title is appended again with the prefix and the same
+ * source, which keeps automatic titling going.
+ */
+import { readFileSync, statSync } from 'node:fs'
+import { normalizeFingerprint } from './identity.js'
+
+/** Title source marker shared with the other chat bridges' formats. */
+export const TITLE_SOURCE = 'DeltaChat'
+
+/** Words taken from the first message when DSH's fallback title is the sender line. */
+const FALLBACK_WORDS = 8
+
+/** @returns one line of text, without the separator dashes doubling up. */
+function clean(value) {
+  return String(value ?? '').replace(/\s+/gu, ' ').trim()
+}
+
+/**
+ * The full title.
+ * @param person - who the chat is with.
+ * @param task - conversation title.
+ */
+export function chatTitle(person, task) {
+  return `${TITLE_SOURCE}-${clean(person) || 'unknown'}-${clean(task)}`
+}
+
+/**
+ * The conversation part of a title, without a `DeltaChat-<person>-` prefix.
+ * @param title - current title.
+ * @param persons - names the prefix may carry (the current one and earlier ones).
+ */
+export function taskOf(title, persons) {
+  const value = clean(title)
+  for (const person of persons) {
+    if (person === undefined || person === null) continue
+    const prefix = `${TITLE_SOURCE}-${clean(person) || 'unknown'}-`
+    if (value.startsWith(prefix)) return value.slice(prefix.length)
+  }
+  return value
+}
+
+/**
+ * A conversation title from the first message of a session, used when DSH's
+ * fallback title is the bot's sender line.
+ * @param events - session events.
+ * @returns a few words of the first message's own text, or ''.
+ */
+export function firstMessageTask(events) {
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== 'user/message' || event.data?.source?.kind !== 'user') continue
+    const text = (event.data.content ?? []).filter((block) => block?.type === 'text').map((block) => block.text).join('\n')
+    const body = text.split('\n').filter((line) => !/^\[[^\]]*\]$/u.test(line.trim())).join(' ')
+    const words = clean(body).split(' ').filter(Boolean)
+    if (words.length > 0) return words.slice(0, FALLBACK_WORDS).join(' ')
+  }
+  return ''
+}
+
+/**
+ * Names for fingerprints from a JSON file with a `deltachat_keys` object, read
+ * again when the file changes.
+ * @returns `nameOf(path, fingerprint)`.
+ */
+export function createPeopleFile() {
+  let cached = { path: '', mtime: 0, keys: {} }
+  return {
+    nameOf(path, fingerprint) {
+      if (typeof path !== 'string' || path.length === 0) return undefined
+      try {
+        const mtime = statSync(path).mtimeMs
+        if (cached.path !== path || cached.mtime !== mtime) {
+          const parsed = JSON.parse(readFileSync(path, 'utf8'))
+          const keys = {}
+          for (const [key, name] of Object.entries(parsed?.deltachat_keys ?? {})) {
+            const normalized = normalizeFingerprint(key)
+            if (normalized && typeof name === 'string') keys[normalized] = name
+          }
+          cached = { path, mtime, keys }
+        }
+      } catch {
+        return undefined
+      }
+      return cached.keys[normalizeFingerprint(fingerprint)]
+    },
+  }
+}
+
+/**
+ * Keep a bound session's title in the chat format.
+ * @param options - `{ service, session, person, earlier, placeholder, previous, warn }`:
+ *   the title service, the live session, who the chat is with, names an older
+ *   title may carry instead, the task shown before a conversation title
+ *   exists, and the placeholder title the bot set earlier (so a renamed chat
+ *   moves it).
+ * @returns the placeholder title now set by the bot, or `previous`.
+ */
+export function syncTitle({ service, session, person, earlier = [], placeholder, previous, warn }) {
+  if (service === undefined || session === undefined) return previous
+  let current
+  try {
+    current = service.get(session)
+  } catch (error) {
+    warn?.(`title not read for ${session.id}: ${error?.message ?? error}`)
+    return previous
+  }
+  const placeholderTitle = chatTitle(person, placeholder)
+  // A title someone typed stays; only the bot's own placeholder follows the chat.
+  if (current === undefined || (current.source?.kind === 'user' && current.title === previous && previous !== placeholderTitle)) {
+    service.rename(session, placeholderTitle)
+    return placeholderTitle
+  }
+  if (current.source?.kind === 'user') return previous
+  let task = taskOf(current.title, [person, ...earlier])
+  if (current.source?.kind === 'fallback' && /^\[Delta Chat message from/u.test(task)) {
+    task = firstMessageTask(typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : []) || placeholder
+  }
+  const wanted = chatTitle(person, task)
+  if (wanted !== current.title) {
+    session.append('session/title', {
+      title: wanted,
+      messageSeqs: Array.isArray(current.messageSeqs) ? [...current.messageSeqs] : [],
+      source: current.source,
+    })
+  }
+  return previous
+}
+
+/**
+ * Whether a session still shows the bot's placeholder, so its first
+ * conversation title should be generated.
+ * @param service - title service.
+ * @param session - live session.
+ * @param previous - the placeholder title the bot set.
+ */
+export function showsPlaceholder(service, session, previous) {
+  try {
+    const current = service.get(session)
+    return current?.source?.kind === 'user' && current.title === previous
+  } catch {
+    return false
+  }
+}

package/src/turns.js

@@ -0,0 +1,161 @@
+/**
+ * Turn delivery: follow every session bound to a chat, collect each turn's
+ * answer, and send it when the turn ends.
+ */
+import { basename } from 'node:path'
+import { REQUEST_PREFIX } from './constants.js'
+import { clip, localImagePaths, messageAnswer, stripSilent } from './text.js'
+
+/**
+ * Create the turn tracker.
+ * @param deps - `{ ctx, getStore, isRunning, setting, outbound, chatState, publishStatus, fireAndForget, messageOf }`.
+ * @returns `{ onSessionEvent, currentTurn }`.
+ */
+export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatState, publishStatus, fireAndForget, messageOf }) {
+  const { queueOut, notice, sendText, sendFiles, checkFiles } = outbound
+  /** Turns of bound sessions by session id: `{ current, turns: Map<turn, record>, pendingOurs }`. */
+  const sessionTurns = new Map()
+
+  /** @returns the turn bookkeeping of a session. */
+  function turnsOf(sessionId) {
+    let entry = sessionTurns.get(sessionId)
+    if (entry === undefined) {
+      entry = { current: undefined, turns: new Map(), pendingOurs: undefined }
+      sessionTurns.set(sessionId, entry)
+    }
+    return entry
+  }
+
+  /** @returns the record of a session's running turn, or undefined. */
+  function currentTurn(sessionId) {
+    const entry = sessionTurns.get(sessionId)
+    return entry?.current === undefined ? undefined : entry.turns.get(entry.current)
+  }
+
+  /**
+   * Follow every session bound to a chat: collect each turn's answer and send
+   * it when the turn ends. Turns started from Delta Chat are always delivered;
+   * turns started elsewhere (Web UI, schedules) when `mirrorTurns` is on.
+   */
+  function onSessionEvent(session, event) {
+    const store = getStore()
+    if (store === undefined || !isRunning()) return
+    const sessionId = session?.id
+    const chatId = store.chatOfSession(sessionId)
+    if (chatId === undefined) return
+    const entry = turnsOf(sessionId)
+    const mirror = setting('mirrorTurns', true) === true
+    if (event.type === 'turn/start') {
+      const record = { texts: [], ours: entry.pendingOurs !== undefined, lastPrompt: entry.pendingOurs, goal: false, mirrored: mirror, sent: false, stopped: false }
+      entry.pendingOurs = undefined
+      entry.current = event.data?.turn
+      entry.turns.set(event.data?.turn, record)
+      return
+    }
+    const record = entry.current === undefined ? undefined : entry.turns.get(entry.current)
+    if (event.type === 'user/message') {
+      const source = event.data?.source
+      const rpcId = typeof source?.rpcId === 'string' ? source.rpcId : ''
+      if (source?.kind === 'user' && rpcId.startsWith(REQUEST_PREFIX)) {
+        const messageId = Number(rpcId.slice(rpcId.lastIndexOf(':') + 1))
+        if (record === undefined) entry.pendingOurs = messageId
+        else {
+          record.ours = true
+          record.lastPrompt = messageId
+        }
+        return
+      }
+      if (rpcId.startsWith('deltachat-claim:')) return
+      if (source?.kind === 'goal' && record !== undefined) record.goal = true
+      if (!mirror) return
+      const label = source?.kind === 'schedule' ? '⏰ Scheduled task' : source?.kind !== 'user' ? undefined : rpcId.startsWith('telegram') ? '✈️ From Telegram' : '🖥 From Web'
+      if (label === undefined) return
+      const content = Array.isArray(event.data?.content) ? event.data.content : []
+      const text = content.filter((block) => block?.type === 'text').map((block) => block.text).join('\n').trim()
+      const files = content.filter((block) => block?.type === 'image' || block?.type === 'file').length
+      if (text.length === 0 && files === 0) return
+      notice(chatId, `${label}:\n${clip(text, 3000)}${files === 0 ? '' : `\n📎 ${files}`}`)
+      return
+    }
+    if (event.type === 'assistant/message') {
+      const turn = entry.turns.get(event.data?.turn) ?? record
+      const answer = messageAnswer(event.data?.message ?? event.data)
+      if (turn !== undefined && answer.length > 0) turn.texts.push(answer)
+      return
+    }
+    if (event.type === 'deliverables/presented') {
+      const turn = entry.turns.get(event.data?.turn) ?? record
+      if (turn !== undefined && !(turn.ours || turn.goal || turn.mirrored)) return
+      const paths = (Array.isArray(event.data?.files) ? event.data.files : []).map((file) => file?.path).filter((path) => typeof path === 'string')
+      if (paths.length === 0) return
+      if (turn !== undefined) turn.sent = true
+      void queueOut(chatId, () => forwardFiles(chatId, paths))
+      return
+    }
+    if (event.type === 'goal/change') {
+      fireAndForget('goal-change', () => announceGoal(chatId, sessionId))
+      return
+    }
+    if (event.type === 'turn/end') {
+      const turn = event.data?.turn
+      const finished = entry.turns.get(turn)
+      entry.turns.delete(turn)
+      if (entry.current === turn) entry.current = undefined
+      if (finished !== undefined) void queueOut(chatId, () => deliverTurn(chatId, finished, event.data?.reason))
+    }
+  }
+
+  /** Send files a session showed its user, with a note for those that cannot go. */
+  async function forwardFiles(chatId, paths, quiet = false) {
+    const failed = []
+    for (const path of paths) {
+      try {
+        await sendFiles(chatId, await checkFiles([path]))
+      } catch (error) {
+        if (!quiet) failed.push(`${basename(path)}: ${messageOf(error)}`)
+      }
+    }
+    if (failed.length > 0) await sendText(chatId, `⚠️ Could not send:\n${failed.join('\n')}`, { plain: true })
+  }
+
+  /** Send a finished turn's answer into its chat. */
+  async function deliverTurn(chatId, turn, reason) {
+    if (!(turn.ours || turn.goal || turn.mirrored)) return
+    if (turn.stopped || reason?.kind === 'aborted' || reason?.kind === 'blocked') return
+    const { text, silent } = stripSilent(turn.texts.join('\n\n'))
+    if (reason?.kind === 'error' && text.length === 0) {
+      await sendText(chatId, `❌ ${reason.error?.message ?? 'The turn failed.'}`, { plain: true })
+      return
+    }
+    if (text.length > 0) {
+      const chat = chatState(chatId)
+      // Quote the prompt when the chat moved on since it was sent.
+      const quote = turn.ours && Number.isSafeInteger(turn.lastPrompt) && chat.lastInbound !== turn.lastPrompt ? turn.lastPrompt : undefined
+      await sendText(chatId, text, { quote })
+      const images = localImagePaths(text)
+      if (images.length > 0) await forwardFiles(chatId, images, true)
+      await publishStatus({ lastReplyAt: Date.now() })
+      return
+    }
+    if (turn.ours && !silent && !turn.sent && reason?.kind !== 'error') await sendText(chatId, '✅ Done.', { plain: true })
+  }
+
+  /** Tell the chat when its session's goal changes phase. */
+  async function announceGoal(chatId, sessionId) {
+    const goals = ctx.get('goals')
+    const agent = ctx.get('agents')?.get(sessionId)
+    if (goals === undefined || agent === undefined) return
+    const view = goals.get(agent)
+    const chat = chatState(chatId)
+    const phase = view === undefined ? 'none' : view.phase
+    if (chat.goalPhase === phase) return
+    const previous = chat.goalPhase
+    chat.goalPhase = phase
+    if (previous === undefined) return
+    if (phase === 'complete') await notice(chatId, `🎯 Goal complete: ${clip(view.objective, 300)}`)
+    else if (phase === 'blocked') await notice(chatId, `🎯 Goal blocked: ${clip(view.objective, 300)}`)
+    else if (phase === 'paused') await notice(chatId, '🎯 Goal paused. /goal resume continues it.')
+  }
+
+  return { onSessionEvent, currentTurn }
+}

package/src/voice.js

@@ -0,0 +1,126 @@
+/** Voice messages and audio files: decoding and transcription. */
+import { spawn } from 'node:child_process'
+
+/**
+ * Wrap raw 16 kHz mono 16-bit PCM in the canonical 44-byte WAV header that
+ * DSH speech providers accept.
+ * @param pcm - little-endian samples.
+ * @returns WAV bytes.
+ */
+export function pcmToWave(pcm) {
+  const data = pcm.length % 2 === 0 ? pcm : pcm.subarray(0, pcm.length - 1)
+  const header = Buffer.alloc(44)
+  header.write('RIFF', 0, 'ascii')
+  header.writeUInt32LE(36 + data.length, 4)
+  header.write('WAVE', 8, 'ascii')
+  header.write('fmt ', 12, 'ascii')
+  header.writeUInt32LE(16, 16)
+  header.writeUInt16LE(1, 20)
+  header.writeUInt16LE(1, 22)
+  header.writeUInt32LE(16000, 24)
+  header.writeUInt32LE(32000, 28)
+  header.writeUInt16LE(2, 32)
+  header.writeUInt16LE(16, 34)
+  header.write('data', 36, 'ascii')
+  header.writeUInt32LE(data.length, 40)
+  return Buffer.concat([header, data])
+}
+
+/**
+ * Run one program and collect its output.
+ * @param argv - program and arguments; no shell is involved.
+ * @param signal - cancellation.
+ * @param timeoutMs - upper bound for the run.
+ * @returns stdout bytes; rejects with stderr on a non-zero exit.
+ */
+export function runProgram(argv, signal, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error('aborted'))
+      return
+    }
+    const child = spawn(argv[0], argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] })
+    const out = []
+    const err = []
+    let settled = false
+    const finish = (error, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+      if (error) reject(error)
+      else resolve(value)
+    }
+    const abort = () => {
+      child.kill('SIGKILL')
+      finish(new Error(`${argv[0]} was cancelled`))
+    }
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      finish(new Error(`${argv[0]} took longer than ${Math.round(timeoutMs / 1000)} s`))
+    }, timeoutMs)
+    signal?.addEventListener('abort', abort, { once: true })
+    child.stdout.on('data', (chunk) => out.push(chunk))
+    child.stderr.on('data', (chunk) => err.push(chunk))
+    child.on('error', (error) => finish(new Error(`${argv[0]} could not start: ${error.message}`)))
+    child.on('close', (code) => {
+      if (code === 0) finish(undefined, Buffer.concat(out))
+      else finish(new Error(`${argv[0]} exited with ${code}: ${Buffer.concat(err).toString('utf8').trim().slice(-400)}`))
+    })
+  })
+}
+
+/**
+ * Transcribe one recording.
+ * @param options - `{ mode, path, language, command, ffmpeg, speech, signal, timeoutMs }`:
+ *   `mode` is `dsh` (the DSH speech-to-text service, `speech`), `command`
+ *   (`command` argv, `{file}` replaced by `path`, transcript on stdout) or `off`.
+ * @returns `{ text, by }`; rejects when transcription fails.
+ */
+export async function transcribe(options) {
+  const { mode, path, signal } = options
+  const timeoutMs = options.timeoutMs ?? 180_000
+  if (mode === 'command') {
+    const command = Array.isArray(options.command) ? options.command.filter((part) => typeof part === 'string') : []
+    if (command.length === 0) throw new Error('no transcription command is configured')
+    const argv = command.some((part) => part.includes('{file}'))
+      ? command.map((part) => part.replaceAll('{file}', path))
+      : [...command, path]
+    const text = (await runProgram(argv, signal, timeoutMs)).toString('utf8').trim()
+    return { text, by: 'the configured transcription command' }
+  }
+  if (mode !== 'dsh') throw new Error('transcription is turned off')
+  const speech = options.speech
+  if (speech === undefined || typeof speech.resolve !== 'function') throw new Error('the DSH speech-to-text service is not enabled')
+  const pcm = await runProgram(
+    [options.ffmpeg || 'ffmpeg', '-nostdin', '-hide_banner', '-loglevel', 'error', '-i', path, '-vn', '-ac', '1', '-ar', '16000', '-f', 's16le', 'pipe:1'],
+    signal,
+    timeoutMs,
+  )
+  if (pcm.length === 0) throw new Error('the recording has no audio')
+  const spec = speech.resolve({
+    audio: pcmToWave(pcm),
+    ...(typeof options.language === 'string' && options.language.length > 0 ? { language: options.language } : {}),
+  })
+  const result = await speech.transcribe(spec, signal ?? new AbortController().signal)
+  const provider = spec.provider?.info?.name ?? spec.provider?.info?.id
+  return { text: String(result?.text ?? '').trim(), by: `DSH speech-to-text${provider ? ` (${provider})` : ''}` }
+}
+
+/**
+ * The text the agent reads next to a spoken recording.
+ * @param media - `{ kind, name, seconds }`.
+ * @param outcome - `{ path, text, by, error }`.
+ * @returns prompt text.
+ */
+export function transcriptNote(media, outcome) {
+  const length = media.seconds === undefined ? '' : `, ${Math.floor(media.seconds / 60)}:${String(media.seconds % 60).padStart(2, '0')}`
+  const where = typeof outcome.path === 'string' ? `the file is attached and saved at ${outcome.path}` : 'the file is attached'
+  if (outcome.error !== undefined) {
+    return `[Delta Chat ${media.kind} "${media.name}"${length}: not transcribed (${outcome.error}); ${where}]`
+  }
+  if (outcome.text.length === 0) {
+    return `[Delta Chat ${media.kind} "${media.name}"${length}: ${outcome.by} heard no speech; ${where}]`
+  }
+  return `[Delta Chat ${media.kind} "${media.name}"${length}, transcribed by ${outcome.by}; the transcript may contain mistakes, and ${where} to check it]\n${outcome.text}`
+}

package/tools.js

@@ -0,0 +1,60 @@
+/**
+ * Model-facing tool for the Delta Chat bot. A separate plugin entry from the
+ * bot (index.js): the bot is looked up as the `deltachatChats` service at call
+ * time, so reloading or restarting the bot never unregisters the tool.
+ */
+import z from '@deepseek-ai/schemastery'
+import { SERVICE_NAME } from './src/constants.js'
+
+export const name = 'deltachat-bot-tools'
+export const inject = ['tools']
+export const Config = z.object({})
+
+/** JSON Schema of the send tool's arguments. */
+export const SEND_SCHEMA = {
+  type: 'object',
+  properties: {
+    chat: { type: 'string', description: 'Numeric Delta Chat chat id; each message from a chat names it in its sender line, and /id in the chat shows it.' },
+    text: { type: 'string', description: 'Message text; Markdown is turned into plain text.' },
+    files: { type: 'array', items: { type: 'string' }, description: 'Absolute paths of files to send.' },
+    reply_to: { type: 'string', description: 'Message id to quote (or to react to, with reaction).' },
+    reaction: { type: 'string', description: 'An emoji to react to reply_to with instead of sending a message; an empty string removes the reaction.' },
+  },
+  required: ['chat'],
+  additionalProperties: false,
+}
+
+/**
+ * The send tool.
+ * @param getService - returns the running bot's service, or undefined.
+ * @returns a tool definition.
+ */
+export function createSendTool(getService) {
+  return {
+    name: 'deltachat_send',
+    description: 'Send a message, files or a reaction into a Delta Chat chat of the DSH Delta Chat bot, addressed by its numeric chat id. Not for answering a Delta Chat message in its own session: the final answer of the turn is delivered there by itself. Use it to reach a chat from another session or a job, to send files, or to react to a message. The message is also recorded in the session bound to that chat; no turn is started.',
+    parameters: SEND_SCHEMA,
+    output: { schema: { type: 'object' }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }] },
+    async execute(args, exec) {
+      const service = getService()
+      if (service === undefined) return { code: 'unavailable', message: 'The Delta Chat bot is not running.' }
+      const sessionId = exec?.agent?.session?.id ?? exec?.agent?.id
+      try {
+        return await service.send({
+          to: args?.chat,
+          text: typeof args?.text === 'string' ? args.text : '',
+          files: Array.isArray(args?.files) ? args.files : [],
+          ...(args?.reply_to === undefined ? {} : { replyTo: args.reply_to }),
+          ...(typeof args?.reaction === 'string' ? { reaction: args.reaction } : {}),
+          from: typeof sessionId === 'string' ? { sessionId, label: `session ${sessionId}` } : undefined,
+        })
+      } catch (error) {
+        return { code: 'failed', message: error?.message ?? String(error) }
+      }
+    },
+  }
+}
+
+export function apply(ctx) {
+  ctx.tools.register(createSendTool(() => ctx.get(SERVICE_NAME)))
+}