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

package/src/state.js

@@ -0,0 +1,162 @@
+/**
+ * Durable bot state: which DSH session each Delta Chat chat is bound to,
+ * contacts that wrote without being allowed, and what was sent on behalf of
+ * jobs and sessions (so a quoted reply can say where a message came from),
+ * and messages that carry the bot's working reaction.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { dataDir } from './constants.js'
+
+/** Sent-message records kept for quoted replies. */
+const SENT_LIMIT = 500
+/** Unknown contacts remembered for the pending list. */
+const PENDING_LIMIT = 50
+
+/** @returns an empty state document. */
+function emptyState() {
+  return { version: 1, chats: {}, pending: {}, sent: [], picks: {}, reactions: {} }
+}
+
+/**
+ * Read a JSON object, or undefined when the file is missing or broken.
+ * @param path - file path.
+ */
+async function readJson(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'))
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Open the state file.
+ * @param path - defaults to `<data dir>/state.json`.
+ * @returns the store.
+ */
+export async function openState(path = join(dataDir(), 'state.json')) {
+  const loaded = await readJson(path)
+  const state = { ...emptyState(), ...(loaded ?? {}) }
+  for (const key of ['chats', 'pending', 'picks', 'reactions']) {
+    if (state[key] === null || typeof state[key] !== 'object' || Array.isArray(state[key])) state[key] = {}
+  }
+  if (!Array.isArray(state.sent)) state.sent = []
+  let writing = Promise.resolve()
+
+  const store = {
+    path,
+    /** The raw document; mutate through the methods below. */
+    get data() {
+      return state
+    },
+    /** Write the document atomically; writes are serialized. */
+    save() {
+      writing = writing.then(async () => {
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+        const temporary = `${path}.${process.pid}.tmp`
+        await writeFile(temporary, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 })
+        await rename(temporary, path)
+      })
+      return writing
+    },
+    /** @returns the binding of a chat, or undefined. */
+    chat(chatId) {
+      return state.chats[String(chatId)]
+    },
+    /** @returns the chat id bound to a session, or undefined. */
+    chatOfSession(sessionId) {
+      for (const [chatId, record] of Object.entries(state.chats)) {
+        if (record?.sessionId === sessionId) return Number(chatId)
+      }
+      return undefined
+    },
+    /**
+     * Bind a chat to a session; a session is shown in one chat at a time, so
+     * another chat bound to it loses the binding.
+     */
+    async bind(chatId, record) {
+      for (const [other, entry] of Object.entries(state.chats)) {
+        if (other !== String(chatId) && entry?.sessionId === record.sessionId) delete entry.sessionId
+      }
+      state.chats[String(chatId)] = { ...(state.chats[String(chatId)] ?? {}), ...record, updatedAt: Date.now() }
+      await store.save()
+    },
+    /**
+     * Merge fields into a chat's record, saving only when something changed.
+     * @returns true when the record changed.
+     */
+    async describeChat(chatId, fields) {
+      const record = state.chats[String(chatId)] ?? {}
+      if (Object.entries(fields).every(([key, value]) => record[key] === value)) return false
+      state.chats[String(chatId)] = { ...record, ...fields }
+      await store.save()
+      return true
+    },
+    /** Forget a chat's session (the chat keeps its other settings). */
+    async release(chatId) {
+      const record = state.chats[String(chatId)]
+      if (record === undefined) return undefined
+      const previous = record.sessionId
+      delete record.sessionId
+      await store.save()
+      return previous
+    },
+    /** Forget a chat entirely (it was deleted or left). */
+    async forget(chatId) {
+      delete state.chats[String(chatId)]
+      await store.save()
+    },
+    /** Remember a contact that wrote without being allowed. */
+    async notePending(entry) {
+      const known = state.pending[entry.fingerprint]
+      state.pending[entry.fingerprint] = { ...entry, firstSeen: known?.firstSeen ?? Date.now(), lastSeen: Date.now(), count: (known?.count ?? 0) + 1 }
+      const keys = Object.keys(state.pending)
+      if (keys.length > PENDING_LIMIT) {
+        keys.sort((left, right) => state.pending[left].lastSeen - state.pending[right].lastSeen)
+        for (const key of keys.slice(0, keys.length - PENDING_LIMIT)) delete state.pending[key]
+      }
+      await store.save()
+      return known === undefined
+    },
+    /** Drop pending entries that are allowed now. */
+    async clearPending(fingerprints) {
+      let changed = false
+      for (const fingerprint of fingerprints) {
+        if (state.pending[fingerprint] === undefined) continue
+        delete state.pending[fingerprint]
+        changed = true
+      }
+      if (changed) await store.save()
+    },
+    /** Record messages sent on someone's behalf. */
+    async noteSent(record) {
+      state.sent.push({ ...record, at: Date.now() })
+      if (state.sent.length > SENT_LIMIT) state.sent.splice(0, state.sent.length - SENT_LIMIT)
+      await store.save()
+    },
+    /** @returns message id → chat id of messages with the bot's working reaction. */
+    reactions() {
+      return { ...state.reactions }
+    },
+    /** Remember a message that got the working reaction. */
+    async noteReaction(msgId, chatId) {
+      state.reactions[String(msgId)] = chatId
+      await store.save()
+    },
+    /** Forget messages whose working reaction was removed. */
+    async dropReactions(msgIds) {
+      for (const msgId of msgIds) delete state.reactions[String(msgId)]
+      await store.save()
+    },
+    /** @returns the send record holding a Delta Chat message id, or undefined. */
+    sentRecord(messageId) {
+      for (let index = state.sent.length - 1; index >= 0; index -= 1) {
+        if (state.sent[index].messageIds?.includes(messageId)) return state.sent[index]
+      }
+      return undefined
+    },
+  }
+  return store
+}

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,197 @@
+/**
+ * Turn delivery: follow every session bound to a chat, collect each turn's
+ * answer, send it when the turn ends, then clear the working reactions of
+ * its messages.
+ */
+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, reactions, chatState, publishStatus, fireAndForget, messageOf }`.
+ * @returns `{ onSessionEvent, currentTurn }`.
+ */
+export function createTurns({ ctx, getStore, isRunning, setting, outbound, reactions, chatState, publishStatus, fireAndForget, messageOf }) {
+  const { queueOut, notice, sendText, sendFiles, checkFiles } = outbound
+  /**
+   * Turns of bound sessions by session id: `{ current, turns: Map<turn, record>,
+   * pendingOurs, pendingIds, lastOurs }`; `pendingIds` are Delta Chat messages
+   * taken before their turn started, `lastOurs` whether the last turn that
+   * ended was started from Delta Chat.
+   */
+  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, pendingIds: [], lastOurs: false }
+      sessionTurns.set(sessionId, entry)
+    }
+    return entry
+  }
+
+  /** @returns the key that ties a turn's messages to it. */
+  function turnKey(sessionId, turn) {
+    return `${sessionId}\u0000${turn}`
+  }
+
+  /** @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: [], sentTexts: [], 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)
+      for (const messageId of entry.pendingIds) reactions.attach(messageId, turnKey(sessionId, event.data?.turn))
+      entry.pendingIds = []
+      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
+          entry.pendingIds.push(messageId)
+        } else {
+          record.ours = true
+          record.lastPrompt = messageId
+          reactions.attach(messageId, turnKey(sessionId, entry.current))
+        }
+        return
+      }
+      if (rpcId.startsWith('deltachat-claim:')) return
+      // A helper's report wakes its parent: that turn answers the chat the delegating turn came from.
+      if ((source?.kind === 'subagent-settled' || source?.kind === 'agent-message') && record !== undefined) {
+        if (entry.lastOurs) record.ours = true
+        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)
+      if (finished !== undefined) entry.lastOurs = finished.ours
+      entry.turns.delete(turn)
+      if (entry.current === turn) entry.current = undefined
+      // The reactions go once the answer is out, also when the turn failed or was stopped.
+      void queueOut(chatId, async () => {
+        try {
+          if (finished !== undefined) await deliverTurn(chatId, finished, event.data?.reason)
+        } finally {
+          await reactions.finishTurn(chatId, turnKey(sessionId, turn))
+        }
+      })
+    }
+  }
+
+  /** 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
+    // Text the session already sent here with its files is not repeated.
+    const sent = new Set(turn.sentTexts.map(sameText))
+    const { text, silent } = stripSilent(turn.texts.filter((part) => !sent.has(sameText(part))).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 })
+  }
+
+  /** @returns text reduced to its words, for comparing an answer with a send. */
+  function sameText(text) {
+    return String(text).replace(/\s+/gu, ' ').trim()
+  }
+
+  /** 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 }
+}