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

package/src/outbound.js

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

package/src/prompts.js

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

package/src/reactions.js

@@ -0,0 +1,125 @@
+/**
+ * Working signs: Delta Chat has no typing indicator, so a message the bot
+ * works on carries a reaction from the bot (⏳ for a new or queued turn, 👀
+ * when it went into the running turn) until the turn that took it has ended
+ * and its answer was sent. Reacted messages are kept in `state.json`, so a
+ * sign left by a turn that a Host restart cut off is removed at the next start.
+ */
+import { REQUEST_PREFIX, STEER_REACTION } from './constants.js'
+import { inInbox } from './sessions.js'
+
+/** Reaction on a message that starts a turn or waits for one. */
+export const WORKING_REACTION = '⏳'
+
+/**
+ * Create the working-sign tracker.
+ * @param deps - `{ ctx, getStore, getRuntime, reportError }`.
+ * @returns `{ emojiFor, mark, admitted, attach, finishTurn, sweep, resume, release }`.
+ */
+export function createReactions({ ctx, getStore, getRuntime, reportError }) {
+  /** Reacted messages by message id: `{ chatId, admitted, turn }`. */
+  const tracked = new Map()
+  let loaded = false
+
+  /** Take over the messages a previous run left reacted. */
+  function load() {
+    if (loaded) return
+    const store = getStore()
+    if (store === undefined) return
+    loaded = true
+    for (const [msgId, chatId] of Object.entries(store.reactions())) {
+      if (!tracked.has(Number(msgId))) tracked.set(Number(msgId), { chatId, admitted: true, turn: undefined })
+    }
+  }
+
+  /** @returns the live agent of a chat's session, or undefined. */
+  function agentOf(chatId) {
+    const sessionId = getStore()?.chat(chatId)?.sessionId
+    return typeof sessionId === 'string' ? ctx.get('agents')?.get(sessionId) : undefined
+  }
+
+  /**
+   * The sign for a message about to go to a session.
+   * @param running - whether the session runs a turn.
+   * @param steer - whether a message during a turn goes into it.
+   */
+  function emojiFor(running, steer) {
+    return running && steer ? STEER_REACTION : WORKING_REACTION
+  }
+
+  /** React to a message and remember it. */
+  async function mark(chatId, msgId, emoji) {
+    load()
+    const runtime = getRuntime()
+    if (runtime === undefined) return
+    tracked.set(msgId, { chatId, admitted: false, turn: undefined })
+    await getStore()?.noteReaction(msgId, chatId)
+    await runtime.dc.rpc.sendReaction(runtime.accountId, msgId, [emoji]).catch((error) => reportError(`reaction on ${msgId}`, error))
+  }
+
+  /** The message reached the session, so a sweep may judge it. */
+  function admitted(msgId) {
+    const entry = tracked.get(msgId)
+    if (entry !== undefined) entry.admitted = true
+  }
+
+  /**
+   * The message is part of a turn now.
+   * @param msgId - Delta Chat message id.
+   * @param turn - key of the turn (session id and turn number).
+   */
+  function attach(msgId, turn) {
+    const entry = tracked.get(msgId)
+    if (entry !== undefined) entry.turn = turn
+  }
+
+  /** Remove the bot's reaction from messages. */
+  async function release(msgIds) {
+    const runtime = getRuntime()
+    if (msgIds.length === 0 || runtime === undefined) return
+    for (const msgId of msgIds) tracked.delete(msgId)
+    await getStore()?.dropReactions(msgIds)
+    for (const msgId of msgIds) {
+      await runtime.dc.rpc.sendReaction(runtime.accountId, msgId, []).catch((error) => reportError(`reaction on ${msgId}`, error))
+    }
+  }
+
+  /**
+   * Messages of a chat that will get no turn: admitted, not taken into a
+   * turn, and no longer waiting in the agent's inbox (dropped by /stop or
+   * /clear, or a duplicate).
+   */
+  function dropped(chatId, { ignoreTurn = false } = {}) {
+    const agent = agentOf(chatId)
+    return [...tracked].filter(([msgId, entry]) => entry.chatId === chatId && entry.admitted
+      && (ignoreTurn || entry.turn === undefined) && !inInbox(agent, `${REQUEST_PREFIX}${chatId}:${msgId}`)).map(([msgId]) => msgId)
+  }
+
+  /**
+   * A turn ended and its answer went out: clear its messages (whatever chat
+   * the session is bound to now) and the chat's dropped ones.
+   */
+  async function finishTurn(chatId, turn) {
+    load()
+    const own = [...tracked].filter(([, entry]) => entry.turn === turn).map(([msgId]) => msgId)
+    await release([...own, ...dropped(chatId)])
+  }
+
+  /** Clear the signs of a chat's dropped messages. */
+  async function sweep(chatId) {
+    load()
+    await release(dropped(chatId))
+  }
+
+  /** Clear signs whose session runs no turn, e.g. after a restart. */
+  async function resume() {
+    load()
+    const idle = new Set([...tracked.values()].map((entry) => entry.chatId).filter((chatId) => {
+      const agent = agentOf(chatId)
+      return agent === undefined || agent.status === undefined || agent.status === 'idle'
+    }))
+    for (const chatId of idle) await release(dropped(chatId, { ignoreTurn: true }))
+  }
+
+  return { emojiFor, mark, admitted, attach, finishTurn, sweep, resume, release }
+}