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

package/src/controls.js

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

package/src/core.js

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

package/src/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 }
+}