@soffits/dsh-deltachat-bot 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- Working signs: each message the bot takes gets a ⏳ reaction (👀 when it joins a running turn), removed once the answer is sent, also after a failure, `/stop`, `/clear` or a restart.
+- Helper activity: subagents a chat's turn starts are listed in one status message, edited in place as they start and finish; `/agents` lists the session's helpers with their last reports.
+- A turn woken by a helper's report answers the chat whose turn started the helper, also with `mirrorTurns` off.
+- A session's text-only `deltachat_send` into its own chat is refused, so answers no longer arrive twice; text sent there with files is not repeated in the answer.
+
 ## 0.1.0
 
 First release: a Delta Chat bot for DSH on several chatmail relays, with a key-fingerprint allowlist, one session per chat (groups included), steering, mirrored turns, pictures, files, voice transcription, quotes, reactions, agent questions and tool approvals, Telegram-style commands, `DeltaChat-<person>-<task>` session titles, the `deltachatChats` send service, the `deltachat_send` tool and the `dsh-deltachat` command.

package/README.md

@@ -57,10 +57,12 @@ Every message the agent receives starts with a line the bot adds from the sender
 
 - The first message in a chat starts a new session in `cwd`. Each group you create with the bot gets its own session, much like a separate topic.
 - Session titles use `DeltaChat-<person>-<task>`: the other party in the chat (a group's name, for a group) plus either the conversation title DSH produces or the chat's name until that title exists. A person's name comes from `peopleFile` when configured, else from `allowedUsers`, else from their Delta Chat profile.
-- If a message arrives while a turn is running, it joins that turn, as in the Web UI (`busyMessages: steer`; the message gets a 👀 reaction). With `busyMessages: queue`, it waits for the turn to finish.
+- Delta Chat has no typing indicator, so the bot reacts ⏳ to your message as soon as it takes it and removes the reaction once the answer is sent (also when the turn fails or is stopped, and after a restart).
+- If a message arrives while a turn is running, it joins that turn, as in the Web UI (`busyMessages: steer`), and shows 👀 until that turn ends. With `busyMessages: queue`, it waits for the turn to finish and keeps ⏳ until its own turn is answered.
 - Turns started elsewhere (scheduled tasks, the Web UI) also show up in the chat unless `mirrorTurns` is off.
 - When the turn ends, replies arrive as plain text: Delta Chat apps do not render Markdown, so the bot turns it into readable text. Files the agent presents, and local images inside an answer, are sent as files. An answer that is exactly `[SILENT]` sends nothing.
 - The model receives images you send as images; other files come through as attachments. Voice messages are transcribed by DSH's speech-to-text service (or by a command you choose; see `transcriber`) and attached.
+- When the agent starts helpers (subagents) during a turn the chat receives, one status message lists them with their model and running time, and is edited as each one starts and finishes; `/agents` lists the session's helpers with their last reports.
 - Quoting a message tells the agent what you are replying to. A reaction to the bot's message is saved in the session but does not begin a turn.
 - When the agent asks a question, the options show as a numbered list: answer with a number or in your own words. A tool that needs approval waits for `/allow` or `/deny`.
 
@@ -77,6 +79,7 @@ Send these as messages; Delta Chat apps make them tappable.
 | `/status` | Bot, relay and session status |
 | `/current` | Show this chat's session |
 | `/last [1-5]` | Show the latest answers |
+| `/agents` | List the session's helpers and their last reports |
 | `/sessions` | List workspaces; `/sessions 2` displays workspace 2's sessions; `/sessions 2 3` brings session 3 into this chat (`0` opens a new one) |
 | `/workspace <n>` | Open a fresh session in workspace n |
 | `/fork [name]` | Make a new group with the same people and fork the session there |
@@ -110,7 +113,7 @@ await ctx.get('deltachatChats').send({
 
 Errors a retry cannot solve carry `retryable: false`. The message is also recorded in the session tied to that chat, without starting a turn, so the agent knows it went out; if the person quotes it later, the agent can tell which job or session sent it. `chats()` lists chats bound to sessions, and `invite()` returns the invite link.
 
-Agents can use the `deltachat_send` tool, which offers the same options (plus `reaction` to react to a message). From a shell:
+Agents can use the `deltachat_send` tool, which offers the same options (plus `reaction` to react to a message). A session's answer already goes to its own chat, so the tool refuses text-only sends from a session into the chat it is bound to, and text it sent there with files is not repeated in the answer. From a shell:
 
 ```sh
 dsh-deltachat send --chat 10 --job backup "Backup done"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soffits/dsh-deltachat-bot",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Delta Chat bot for DeepSeek Harness: an end-to-end encrypted chatmail bot on several relays, one DSH session per chat, commands, files, voice messages and a send service for other plugins.",
   "type": "module",
   "main": "./index.js",

package/src/app.js

@@ -3,15 +3,17 @@ import { randomUUID } from 'node:crypto'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { parseCommand, runCommand } from './commands.js'
-import { accountsDir, dataDir, name, POST_SOURCE_KIND, REQUEST_PREFIX, SERVICE_NAME, STEER_REACTION } from './constants.js'
+import { accountsDir, dataDir, name, POST_SOURCE_KIND, REQUEST_PREFIX, SERVICE_NAME } from './constants.js'
 import * as realCore from './core.js'
+import { createHelpers } from './helpers.js'
 import { allowedEntry, normalizeFingerprint, shortFingerprint } from './identity.js'
 import { composePrompt } from './inbound.js'
 import { createModelCatalog } from './models.js'
 import { createOperations, primaryAddress } from './operations.js'
 import { createOutbound } from './outbound.js'
 import { createPrompts } from './prompts.js'
-import { admitPrompt, createSession, recordMessage, resolveAgent, unarchive } from './sessions.js'
+import { createReactions } from './reactions.js'
+import { admitPrompt, createSession, hasRequest, recordMessage, resolveAgent, unarchive } from './sessions.js'
 import { createSpool } from './spool.js'
 import { openState } from './state.js'
 import { clip } from './text.js'
@@ -129,18 +131,21 @@ export function createBridge(ctx, config, core) {
 
   const outbound = createOutbound({ requireRuntime, chatState, reportError, messageOf })
   const { notice, sendText } = outbound
+  const reactions = createReactions({ ctx, getStore: () => store, getRuntime: () => runtime, reportError })
   const turns = createTurns({
     ctx,
     getStore: () => store,
     isRunning: () => runtime !== undefined,
     setting,
     outbound,
+    reactions,
     chatState,
     publishStatus,
     fireAndForget,
     messageOf,
   })
   const { currentTurn } = turns
+  const helpers = createHelpers({ ctx, getStore: () => store, getRuntime: () => runtime, outbound, currentTurn, reportError })
   const operations = createOperations({
     ctx,
     getStore: () => store,
@@ -353,7 +358,8 @@ export function createBridge(ctx, config, core) {
 
   /**
    * Hand a message to the chat's session: into the running turn (`steer`) or
-   * after it (`queue`), with its sender line, quote and file.
+   * after it (`queue`), with its sender line, quote and file. The message gets
+   * the working reaction first, so the sender sees at once that it was taken.
    */
   async function dispatchPrompt(chatId, msg, sender) {
     const { dc, accountId } = requireRuntime()
@@ -362,7 +368,15 @@ export function createBridge(ctx, config, core) {
     while (chat.admission !== undefined) await chat.admission
     let release
     chat.admission = new Promise((resolve) => { release = resolve })
+    const requestId = `${REQUEST_PREFIX}${chatId}:${msg.id}`
+    const steer = setting('busyMessages', 'steer') !== 'queue'
+    let react = false
     try {
+      const boundId = store.chat(chatId)?.sessionId
+      const live = typeof boundId === 'string' ? ctx.get('agents')?.get(boundId) : undefined
+      // A message handed over before (a restart before it was marked seen) gets no new sign.
+      react = live === undefined || !hasRequest(live, requestId)
+      if (react) await reactions.mark(chatId, msg.id, reactions.emojiFor(live?.status !== undefined && live.status !== 'idle', steer))
       let quotedOwn = false
       let sentRecord
       if (msg.quote?.kind === 'WithMessage') {
@@ -390,12 +404,14 @@ export function createBridge(ctx, config, core) {
       const sessionId = agent.session?.id ?? agent.id
       if (await unarchive(ctx, sessionId)) info(`unarchived session ${sessionId} for a message from chat ${chatId}`)
       const running = agent.status !== undefined && agent.status !== 'idle'
-      const mode = running && setting('busyMessages', 'steer') !== 'queue' ? 'steer' : 'queue'
-      const requestId = `${REQUEST_PREFIX}${chatId}:${msg.id}`
-      await admitPrompt(ctx, agent, { requestId, text: prompt.text, attachments: prompt.attachments, mode }, lifetime.signal)
-      if (running) {
-        await dc.rpc.sendReaction(accountId, msg.id, [mode === 'steer' ? STEER_REACTION : '⏳']).catch(() => {})
-      }
+      const mode = running && steer ? 'steer' : 'queue'
+      const admitted = await admitPrompt(ctx, agent, { requestId, text: prompt.text, attachments: prompt.attachments, mode }, lifetime.signal)
+      if (!react) return
+      if (admitted) reactions.admitted(msg.id)
+      else await reactions.release([msg.id])
+    } catch (error) {
+      if (react) await reactions.release([msg.id]).catch(() => {})
+      throw error
     } finally {
       chat.admission = undefined
       release()
@@ -487,6 +503,9 @@ export function createBridge(ctx, config, core) {
       info(`running as ${primary}; invite link written to ${join(dataDir(), 'invite.txt')}`)
       await publishStatus({ state: 'running', detail: '', primary, invite: link })
       spool.start().catch((error) => reportError('spool', error))
+      // Working reactions left by turns that ended while the bot was down,
+      // cleared before unseen messages are handed over (and marked) again.
+      await reactions.resume().catch((error) => reportError('reactions', error))
       // Messages that arrived while the bot was down.
       for (const msgId of (await setup(dc.rpc.getFreshMsgs(accountId))).sort((left, right) => left - right)) void onIncoming(msgId)
     } catch (error) {
@@ -586,6 +605,8 @@ export function createBridge(ctx, config, core) {
     chatState,
     currentTurn,
     ensureAgent,
+    reactions,
+    helpers,
     notice,
     sendText,
     modelCatalog,
@@ -611,6 +632,9 @@ export function createBridge(ctx, config, core) {
     else if (event?.type === 'request/header') fireAndForget('title', () => startTitle(session.id))
   }, { global: true })
 
+  ctx.on('subagent/start', (info) => fireAndForget('helpers', () => helpers.onStart(info)), { global: true })
+  ctx.on('subagent/end', (info) => fireAndForget('helpers', () => helpers.onEnd(info)), { global: true })
+
   ctx.on('settings/document-updated', (namespace) => {
     if (namespace === name) fireAndForget('settings', () => applySettings())
   })
@@ -622,6 +646,7 @@ export function createBridge(ctx, config, core) {
       lifetime.abort()
       if (retryTimer !== undefined) clearTimeout(retryTimer)
       prompts.cancelAll()
+      helpers.dispose()
       stopRuntime()
     }
   }, 'dsh-deltachat-bot: runtime')

package/src/commands.js

@@ -22,6 +22,7 @@ export const COMMANDS = [
   ['status', 'Bot and session status'],
   ['current', "Show this chat's session"],
   ['last', 'Show the latest answers: /last [1-5]'],
+  ['agents', "List this session's helpers and their last reports"],
   ['sessions', 'Browse workspaces and sessions, continue one here'],
   ['workspace', 'Start a new session in another workspace'],
   ['fork', 'Fork this session into a new group: /fork [name]'],
@@ -199,6 +200,7 @@ const HANDLERS = {
 
   async clear(bridge, { chatId }) {
     const removed = clearChatInbox(liveAgent(bridge, chatId), chatId)
+    await bridge.reactions.sweep(chatId)
     await bridge.notice(chatId, removed === 0 ? '🧹 Nothing is waiting.' : `🧹 Dropped ${removed} waiting message(s).`)
   },
 
@@ -221,6 +223,29 @@ const HANDLERS = {
     }
   },
 
+  async agents(bridge, { chatId }) {
+    const sessionId = sessionOf(bridge, chatId)
+    if (sessionId === undefined) {
+      await bridge.notice(chatId, 'This chat has no session yet.')
+      return
+    }
+    const helpers = await bridge.helpers.list(sessionId)
+    if (helpers === undefined) {
+      await bridge.notice(chatId, 'Helpers are not available in this DSH.')
+      return
+    }
+    if (helpers.length === 0) {
+      await bridge.notice(chatId, 'This session has started no helpers.')
+      return
+    }
+    const lines = ['Helpers of this session:']
+    for (const [index, helper] of helpers.entries()) {
+      lines.push('', `${index + 1}. ${helper.running ? '⏳' : '✓'} ${helper.label} · ${age(helper.createdAt)}`)
+      lines.push(helper.report ? clip(toPlainText(helper.report), 400) : helper.running ? '(working)' : '(no report)')
+    }
+    await bridge.notice(chatId, lines.join('\n'))
+  },
+
   async sessions(bridge, { chatId }, args) {
     const workspaces = listWorkspaces(bridge.ctx).slice(0, LIST_LIMIT)
     const [first, second] = args.split(/\s+/u).filter(Boolean)

package/src/helpers.js

@@ -0,0 +1,180 @@
+/**
+ * Helper activity: subagents started under a chat's session are shown in one
+ * status message, edited in place as they start and finish and left as it is
+ * once all of them are done. `/agents` lists a session's helpers on demand.
+ */
+import { sessionModelOf } from './models.js'
+import { recentAssistantTexts } from './sessions.js'
+import { clip } from './text.js'
+
+/** Pause that lets several starts or ends share one edit. */
+const EDIT_DELAY_MS = 1500
+/** Parent links followed from a helper up to the chat's session. */
+const MAX_DEPTH = 8
+/** Helpers `/agents` lists at most. */
+const LIST_LIMIT = 8
+
+/** @returns minutes between two times, as shown in the status message. */
+function minutes(from, to) {
+  const value = Math.floor((to - from) / 60_000)
+  return value < 1 ? '<1 min' : `${value} min`
+}
+
+/**
+ * The status text of one chat's helpers.
+ * @param helpers - helper records in start order.
+ * @param now - current time in ms.
+ */
+export function boardText(helpers, now) {
+  const running = helpers.filter((helper) => helper.endedAt === undefined)
+  const count = (n) => `${n} helper${n === 1 ? '' : 's'}`
+  const head = running.length > 0 ? `🤖 ${count(running.length)} working:` : `🤖 ${count(helpers.length)} done:`
+  const lines = helpers.map((helper) => {
+    const model = helper.model ? `${helper.model}, ` : ''
+    if (helper.endedAt === undefined) return `⏳ ${helper.label} (${model}${minutes(helper.startedAt, now)})`
+    const failed = helper.stopReason !== undefined && helper.stopReason !== 'completed'
+    return `${failed ? '✗' : '✓'} ${helper.label} (${model}${minutes(helper.startedAt, helper.endedAt)}${failed ? `, ${helper.stopReason}` : ''})`
+  })
+  return [head, ...lines].join('\n')
+}
+
+/**
+ * Create the helper tracker.
+ * @param deps - `{ ctx, getStore, getRuntime, outbound, currentTurn, reportError, now }`.
+ * @returns `{ onStart, onEnd, list, dispose }`.
+ */
+export function createHelpers({ ctx, getStore, getRuntime, outbound, currentTurn, reportError, now = Date.now }) {
+  const { queueOut, sendText } = outbound
+  /** Open status messages by chat id: `{ messageId, helpers: Map<runId, helper>, timer }`. */
+  const boards = new Map()
+
+  /** @returns the chat whose session started this helper (directly or through other helpers). */
+  function chatOfHelper(childId) {
+    const agents = ctx.get('agents')
+    const store = getStore()
+    let sessionId = agents?.get(childId)?.session?.header?.parentSession
+    for (let depth = 0; depth < MAX_DEPTH && typeof sessionId === 'string'; depth += 1) {
+      const chatId = store?.chatOfSession(sessionId)
+      if (chatId !== undefined) return { chatId, sessionId }
+      sessionId = agents?.get(sessionId)?.session?.header?.parentSession
+    }
+    return undefined
+  }
+
+  /**
+   * Fill in labels from the parents' catalogs. A child can be announced
+   * before its parent's catalog lists it, so this runs at every publish until
+   * the label is found; meanwhile the id stands in.
+   */
+  async function nameHelpers(helpers) {
+    for (const helper of helpers) {
+      if (helper.named) continue
+      try {
+        const children = await ctx.get('subagents')?.listChildren(helper.parentId)
+        const label = children?.find((child) => child.id === helper.id)?.label
+        if (typeof label === 'string' && label.trim()) {
+          helper.label = clip(label.trim(), 80)
+          helper.named = true
+        }
+      } catch {
+        // The catalog is optional.
+      }
+    }
+  }
+
+  /** Send or edit a chat's status message after a short pause. */
+  function schedule(chatId, board) {
+    if (board.timer !== undefined) return
+    board.timer = setTimeout(() => {
+      board.timer = undefined
+      void queueOut(chatId, () => publish(chatId, board)).catch((error) => reportError(`helpers in chat ${chatId}`, error))
+    }, EDIT_DELAY_MS)
+    board.timer.unref?.()
+  }
+
+  /** Bring the status message up to date; a finished board is left as it is. */
+  async function publish(chatId, board) {
+    const runtime = getRuntime()
+    if (runtime === undefined) return
+    const helpers = [...board.helpers.values()]
+    await nameHelpers(helpers)
+    const text = boardText(helpers, now())
+    const done = helpers.every((helper) => helper.endedAt !== undefined)
+    if (done && boards.get(chatId) === board) boards.delete(chatId)
+    if (board.messageId !== undefined) {
+      try {
+        await runtime.dc.rpc.sendEditRequest(runtime.accountId, board.messageId, text)
+        return
+      } catch (error) {
+        // Without edits the new state goes out as its own message.
+        reportError(`editing helper status ${board.messageId}`, error)
+      }
+    }
+    const [messageId] = await sendText(chatId, text, { plain: true })
+    board.messageId = messageId
+  }
+
+  /**
+   * A helper started (`subagent/start`).
+   * @param info - `{ runId, id, local }`.
+   */
+  async function onStart(info) {
+    const found = chatOfHelper(info?.id)
+    if (found === undefined) return
+    const { chatId, sessionId } = found
+    const turn = currentTurn(sessionId)
+    let board = boards.get(chatId)
+    // Helpers show where the session's answers show.
+    if (board === undefined && !(turn !== undefined && (turn.ours || turn.goal || turn.mirrored))) return
+    if (board === undefined) {
+      board = { messageId: undefined, helpers: new Map(), timer: undefined }
+      boards.set(chatId, board)
+    }
+    const parentId = ctx.get('agents')?.get(info.id)?.session?.header?.parentSession ?? sessionId
+    const helper = { id: info.id, parentId, label: `helper ${String(info.id).slice(0, 8)}`, named: false, model: '', startedAt: now(), endedAt: undefined, stopReason: undefined }
+    board.helpers.set(info.runId, helper)
+    helper.model = (await sessionModelOf(ctx, info.id).catch(() => undefined))?.model ?? ''
+    schedule(chatId, board)
+  }
+
+  /**
+   * A helper finished (`subagent/end`).
+   * @param info - `{ runId, id, stopReason }`.
+   */
+  function onEnd(info) {
+    for (const [chatId, board] of boards) {
+      const helper = board.helpers.get(info?.runId)
+      if (helper === undefined) continue
+      helper.endedAt = now()
+      helper.stopReason = info.stopReason
+      schedule(chatId, board)
+      return
+    }
+  }
+
+  /**
+   * The helpers of a session for `/agents`, newest last, with each one's last report.
+   * @param sessionId - the chat's session.
+   * @returns `[{ id, label, running, createdAt, report }]`.
+   */
+  async function list(sessionId) {
+    const children = await ctx.get('subagents')?.listChildren(sessionId)
+    if (!Array.isArray(children)) return undefined
+    const result = []
+    for (const child of children.slice(-LIST_LIMIT)) {
+      const agent = ctx.get('agents')?.get(child.id)
+      const running = agent !== undefined && agent.status !== undefined && agent.status !== 'idle'
+      const [report = ''] = await recentAssistantTexts(ctx, child.id, 1)
+      result.push({ id: child.id, label: child.label || `helper ${String(child.id).slice(0, 8)}`, running, createdAt: child.createdAt, report })
+    }
+    return result
+  }
+
+  /** Stop pending edits. */
+  function dispose() {
+    for (const board of boards.values()) if (board.timer !== undefined) clearTimeout(board.timer)
+    boards.clear()
+  }
+
+  return { onStart, onEnd, list, dispose }
+}

package/src/operations.js

@@ -52,16 +52,25 @@ export function createOperations({ ctx, getStore, storeReady, requireRuntime, ge
     const text = typeof request?.text === 'string' ? request.text.trim() : ''
     const paths = Array.isArray(request?.files) ? request.files.map(String) : []
     if (text.length === 0 && paths.length === 0) throw finalError('Nothing to send: give text or files.')
+    const from = request?.from ?? {}
+    const sessionId = store.chat(chatId)?.sessionId
+    const ownTurn = typeof from.sessionId === 'string' && from.sessionId === sessionId ? currentTurn(sessionId) : undefined
+    // The answer of a turn this chat receives is delivered by itself, so text
+    // a session sends into its own chat would arrive twice.
+    const delivered = ownTurn !== undefined && (ownTurn.ours || ownTurn.goal || ownTurn.mirrored)
+    if (delivered && paths.length === 0) {
+      throw finalError('This session is bound to that chat and its answer is delivered there when the turn ends: write the text in your answer instead of sending it.')
+    }
     const files = await checkFiles(paths)
     const messageIds = await queueOut(chatId, async () => {
       const ids = text.length > 0 ? await sendText(chatId, text, { quote: replyTo }) : []
       ids.push(...await sendFiles(chatId, files))
       return ids
     })
-    const from = request?.from ?? {}
-    const sessionId = store.chat(chatId)?.sessionId
-    const ownTurn = typeof from.sessionId === 'string' && from.sessionId === sessionId ? currentTurn(sessionId) : undefined
-    if (ownTurn !== undefined) ownTurn.sent = true
+    if (ownTurn !== undefined) {
+      ownTurn.sent = true
+      if (text.length > 0) ownTurn.sentTexts.push(text)
+    }
     await store.noteSent({
       chatId,
       messageIds,

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

package/src/sessions.js

@@ -152,11 +152,17 @@ export async function unarchive(ctx, sessionId) {
   return true
 }
 
-/** @returns whether a pending or recorded message carries this request id. */
-function hasRequest(agent, requestId) {
+/** @returns whether a message the agent has not taken yet carries this request id. */
+export function inInbox(agent, requestId) {
   const matches = (message) => message?.source?.kind === 'user' && message.source.rpcId === requestId
   const inbox = agent?.inbox
-  if (inbox?.nextTurn?.some?.(matches) || inbox?.nextStep?.some?.(matches)) return true
+  return inbox?.nextTurn?.some?.(matches) === true || inbox?.nextStep?.some?.(matches) === true
+}
+
+/** @returns whether a pending or recorded message carries this request id. */
+export function hasRequest(agent, requestId) {
+  if (inInbox(agent, requestId)) return true
+  const matches = (message) => message?.source?.kind === 'user' && message.source.rpcId === requestId
   const events = typeof agent?.session?.snapshotEvents === 'function' ? agent.session.snapshotEvents() : []
   return events.some((event) => event?.type === 'user/message' && matches(event.data))
 }
@@ -172,21 +178,23 @@ function hasRequest(agent, requestId) {
  * @param agent - the session's agent.
  * @param prompt - `{ requestId, text, attachments, mode }`; `mode` is `queue` or `steer`.
  * @param signal - request lifetime.
+ * @returns whether the prompt was handed over (false for a duplicate or an empty one).
  */
 export async function admitPrompt(ctx, agent, { requestId, text, attachments = [], mode }, signal) {
-  if (hasRequest(agent, requestId)) return
+  if (hasRequest(agent, requestId)) return false
   const content = [...(text.trim().length === 0 ? [] : [{ type: 'text', text }]), ...attachments]
-  if (content.length === 0) return
+  if (content.length === 0) return false
   const controller = ctx.get('sessionController')
   const sessionId = agent.session?.id ?? agent.id
   if (attachments.length === 0 && typeof controller?.prompt === 'function') {
     await controller.prompt({ sessionId, requestId, mode, content }, signal)
-    return
+    return true
   }
   const message = { id: randomUUID(), role: 'user', content, source: { kind: 'user', rpcId: requestId } }
   if (mode === 'steer' && typeof agent.steer === 'function') agent.steer(message)
   else if (typeof agent.followup === 'function') agent.followup(message)
   else agent.send(message, mode === 'steer' ? 'next-step' : 'next-turn', true)
+  return true
 }
 
 /**

package/src/state.js

@@ -1,7 +1,8 @@
 /**
  * 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).
+ * 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'
@@ -14,7 +15,7 @@ const PENDING_LIMIT = 50
 
 /** @returns an empty state document. */
 function emptyState() {
-  return { version: 1, chats: {}, pending: {}, sent: [], picks: {} }
+  return { version: 1, chats: {}, pending: {}, sent: [], picks: {}, reactions: {} }
 }
 
 /**
@@ -38,7 +39,7 @@ async function readJson(path) {
 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']) {
+  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 = []
@@ -135,6 +136,20 @@ export async function openState(path = join(dataDir(), 'state.json')) {
       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) {

package/src/turns.js

@@ -1,6 +1,7 @@
 /**
  * Turn delivery: follow every session bound to a chat, collect each turn's
- * answer, and send it when the turn ends.
+ * 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'
@@ -8,24 +9,34 @@ import { clip, localImagePaths, messageAnswer, stripSilent } from './text.js'
 
 /**
  * Create the turn tracker.
- * @param deps - `{ ctx, getStore, isRunning, setting, outbound, chatState, publishStatus, fireAndForget, messageOf }`.
+ * @param deps - `{ ctx, getStore, isRunning, setting, outbound, reactions, chatState, publishStatus, fireAndForget, messageOf }`.
  * @returns `{ onSessionEvent, currentTurn }`.
  */
-export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatState, publishStatus, fireAndForget, messageOf }) {
+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 }`. */
+  /**
+   * 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 }
+      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)
@@ -46,10 +57,12 @@ export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatS
     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 }
+      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)
@@ -58,14 +71,22 @@ export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatS
       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 {
+        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'
@@ -99,9 +120,17 @@ export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatS
     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
-      if (finished !== undefined) void queueOut(chatId, () => deliverTurn(chatId, finished, event.data?.reason))
+      // 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))
+        }
+      })
     }
   }
 
@@ -122,7 +151,9 @@ export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatS
   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'))
+    // 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
@@ -140,6 +171,11 @@ export function createTurns({ ctx, getStore, isRunning, setting, outbound, chatS
     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')

package/tools.js

@@ -32,7 +32,7 @@ export const SEND_SCHEMA = {
 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.',
+    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 in the chat this session is bound to: the final answer of the turn is delivered there by itself, so text-only sends into that chat are refused. Use it to reach another chat, 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) {