@soffits/dsh-telegram-bot 0.5.0 → 0.6.0

package/MAINTAINING.md

@@ -18,6 +18,7 @@ This repository is a maintained fork of [Boobaw/dsh-telegram-bot](https://github
 - Models (`src/models.js`): the session's agent owns its model (`agent.model.current()`); the bot keeps no copy, because a copy drifted on fallback switches and Web UI picks and was carried into `/new`. Sessions are created and resumed through `sessionController.create` / `resolveAgent` (the Web UI's own composition); the raw `agents` registry is only the headless fallback. The picker reads `sessionController.modelCatalog()` and applies picks with `sessionController.selectModel`, which also saves the default, as a Web pick does. `/new` starts the new session on the previous session's current model.
 - Lifecycle notices go to a chat fixed by config (`controlChatOf` in `src/utils.js`: `controlChat`, else the first allowed user's private chat). Upstream moves its control chat to whoever wrote last and stores it in `topics.json`; the fork dropped that file.
 - Final replies keep only the answer (`src/final-text.js`): text written between tool calls streams as a live draft, but at the turn's end the reply is rebuilt from the session's durable messages, keeping the last text block of each message that called no tool. Mirrored turns use the same rule.
+- Subagent activity (`src/agents.js`): `subagent/start` and `subagent/end` (global listeners) drive one status message per topic turn, found by following `session.header.parentSession` from the child up to a bound session. A board is keyed by the topic's `turnEpoch` and opens only while the topic shows a turn (`busy` and not `done`); a nested child joins the board that lists its nearest ancestor. Edits are coalesced (1.5 s) and serialized per board, a running board ticks once a minute but edits only when the text changes, and a board whose children are all done is frozen. The description is the parent catalog's `label` (the delegation's `description`), read again at each edit until found. `/agents` walks `subagents.listChildren` (durable catalogs, bounded reads) and reads each child's `subagentTiming` and `modelSelection` projections and its log for the last `send_message` or tool-free answer.
 - Reply, quote and forward context: the agent sees what a message replies to, quotes or forwards, and forwards sent together become one prompt.
 
 Upstream changes are merged in, not rebased, so the history of both lines stays intact.
@@ -36,4 +37,4 @@ git push origin main
 
 Conflicts usually land in `src/app.js` (most of the bridge lives there), `README.md` and the `name` and `version` lines of `package.json`. Keep the fork's own name and version: it is published on npm as `@soffits/dsh-telegram-bot` with its own semver line (0.4.0 was the first release, on top of upstream 0.3.0), so bump the minor version for features and upstream merges and the patch version for fixes, and name the merged upstream version in the merge or release commit. Make sure `client.js` still matches `src/client.js` after the merge (`cmp client.js src/client.js`).
 
-Fork-only code is kept in separate files where that is natural (`src/topics.js`, `src/outbox.js`, `src/message-context.js`, `src/sent-log.js`, `src/voice.js`, `src/steer.js`, `src/sender.js`, `src/models.js`, `src/final-text.js`, `bin/dsh-telegram-send.js`, `test/fake-dsh.js`, `test/fork-features.test.js`, `test/message-context.test.js`, `test/sent-log.test.js`, `test/steer.test.js`, `test/sender.test.js`, `test/models.test.js`, `test/final-text.test.js`, `test/voice.test.js`), so most upstream edits apply without touching it.
+Fork-only code is kept in separate files where that is natural (`src/topics.js`, `src/outbox.js`, `src/message-context.js`, `src/sent-log.js`, `src/voice.js`, `src/steer.js`, `src/sender.js`, `src/models.js`, `src/final-text.js`, `src/agents.js`, `bin/dsh-telegram-send.js`, `test/fake-dsh.js`, `test/fork-features.test.js`, `test/message-context.test.js`, `test/sent-log.test.js`, `test/steer.test.js`, `test/sender.test.js`, `test/models.test.js`, `test/final-text.test.js`, `test/agents.test.js`, `test/voice.test.js`), so most upstream edits apply without touching it.

package/README.md

@@ -37,6 +37,15 @@ BotFather: **Bot Settings → Threaded mode → Enable**. Leave **Disallow users
 - Automatic goal rounds of a topic's session are shown in the topic like a Telegram turn, with thinking, tool calls and the final answer, also when **Show turns from other clients** is off. Their approvals and questions are answered in the topic.
 - While a turn runs in a topic's session (started from Telegram or shown from another client), that topic shows "typing…". Each topic shows its own; it stops when the turn ends, fails or is stopped.
 - Reasoning and tool calls are shown as temporary messages and removed after the answer. Each tool-call entry is capped at two lines.
+- Subagents show in the topic. When a turn the topic shows starts subagents, one quiet status message lists them, each with its description, model and running time, and is edited in place as they start and finish (✓ done, ✗ failed with the reason). Changes that land within about 1.5 seconds share one edit, and running times are refreshed at most once a minute, which keeps well inside Telegram's edit limits. Subagents started by subagents are listed under their parent. Once all of them are done the message stays as it is, and the next subagent opens a new one. For example:
+
+  ```
+  🤖 3 subagents · 1 running
+  ✓ Compare flight prices · claude-opus-5-5 · 2m 14s
+  ↳ ✓ Check baggage rules · claude-haiku-4-5 · 41s
+  ⏳ Find a hotel near the venue · deepseek-v4-flash · 3m
+  ```
+- `/agents` lists the session's running and most recent subagents (up to eight, nested ones included), with their state, model, time, when they started and the beginning of their last report (the last message they sent their parent, or their final answer). It reads DSH's saved sessions, so it also covers subagents from before a restart; one cut off by a restart shows as interrupted.
 - Inline controls for model, reasoning effort, permission mode and context usage. The model picker offers every provider and model of the Web UI's model picker (provider first, then its models, with paging) and switches the session the way the Web UI does, which also makes the pick the default for new sessions. The panel always shows the model the session runs now; `/new` starts the next session on that model.
 - Tool approvals with **Deny** / **Allow** buttons.
 - `ask_user_question` support: options, multi-select, custom answers and plan review.
@@ -45,7 +54,7 @@ BotFather: **Bot Settings → Threaded mode → Enable**. Leave **Disallow users
 - Every prompt from Telegram starts with a line naming the sender, such as `[Telegram message from Ana Silva (@ana, user id 123)]`, so the agent knows who is writing when several allowed users share the bot. Prompts typed in the Web UI are not labelled. The sender is also recorded as data on the prompt's source as `principal`, the field DSH uses for the caller behind a user message: `{ kind: 'telegram-user', channel: 'telegram', id: '123', name: 'Ana Silva', username: 'ana', chat: { id, thread, name } }`, where `chat` is the chat, its topic thread and the topic's name. Scripts that read session logs can use it instead of parsing the line.
 - Replies, quotes and forwards keep their context. The agent sees the text of the replied-to message (or only the quoted part), who wrote it and when; a replied-to photo or document is attached too. A forwarded message is labelled with its origin (person, hidden account, group or channel with a message link) and original date. Several messages forwarded together become one prompt, and forwarded text never runs as a command. Long quoted text is cut at about 2,000 characters with a note.
 - Replies to messages sent into a topic by a script, job, plugin or another session (see [Send to a topic](#send-to-a-topic)) also carry the full original text, when it was sent, and the sending session and job, even if the topic has moved to a new session since.
-- `/new`, `/workspace`, `/last`, `/goal`, `/rename`, `/topic`, `/fork`, `/clear`, `/stop`, `/restart`, `/status` and `/menu`.
+- `/new`, `/workspace`, `/last`, `/agents`, `/goal`, `/rename`, `/topic`, `/fork`, `/clear`, `/stop`, `/restart`, `/status` and `/menu`.
 - `/goal` shows the current DSH goal and the command hints. `/goal <objective>` creates or replaces the goal and starts working immediately; `/goal edit <objective>` updates the objective and resumes a paused, blocked or disarmed goal; `/goal pause`, `/goal resume` and `/goal clear` manage the current goal. `/goal <objective>` and `/goal edit <objective>` replace the current panel with one fresh message; later goal changes edit that message in place. The panel is never pinned.
 - `/new` in a session topic starts a fresh DSH session in the same workspace and binds it to the same topic; the previous session stays in DSH. In All it opens a new session topic.
 - One session is bound to at most one topic: binding it to a new topic releases the old one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soffits/dsh-telegram-bot",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Telegram sessions, topics, model controls and approvals for DeepSeek Harness.",
   "type": "module",
   "main": "./index.js",

package/src/agents.js

@@ -0,0 +1,440 @@
+/**
+ * Subagent activity in Telegram topics.
+ *
+ * When a turn the topic is showing starts subagents, one status message lists
+ * them (description, model, elapsed time) and is edited in place as they
+ * start and finish. Changes that land close together share one edit, and a
+ * running board is refreshed at most once a minute so its times move. Once
+ * every subagent on it is done the message is left as it is; the next
+ * subagent opens a new one. Subagents started by subagents count under the
+ * topic of the session at the top of the chain.
+ *
+ * `/agents` lists a session's subagents from DSH's durable catalogs, so it
+ * also works after a restart.
+ */
+import { messageAnswer } from './final-text.js'
+
+/** Pause that lets several starts or ends share one edit. */
+export const EDIT_DELAY_MS = 1500
+/** How often a board with running subagents is refreshed for its times. */
+export const TICK_MS = 60_000
+/** Parent links followed from a subagent up to a bound session. */
+const MAX_DEPTH = 8
+/** Subagents `/agents` lists at most, running ones first. */
+export const LIST_LIMIT = 8
+/** Lines a status message shows at most; older finished lines are folded. */
+const MAX_LINES = 25
+/** Longest description shown on a line. */
+const LABEL_MAX = 60
+/** Longest report preview `/agents` shows per subagent. */
+export const REPORT_MAX = 240
+
+/** @returns the text cut to `max` characters with an ellipsis. */
+export function clip(text, max) {
+  const value = String(text ?? '')
+  return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1)).trimEnd()}…`
+}
+
+/**
+ * Format a duration. Running times are shown in whole minutes, so a board
+ * refreshed once a minute stays accurate; finished times also show seconds.
+ * @param ms - duration in milliseconds.
+ * @param precise - include seconds.
+ */
+export function formatElapsed(ms, precise) {
+  const seconds = Math.max(0, Math.floor(ms / 1000))
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  if (hours > 0) return `${hours}h ${minutes % 60}m`
+  if (!precise) return minutes < 1 ? '<1m' : `${minutes}m`
+  if (minutes < 1) return `${seconds}s`
+  return `${minutes}m ${seconds % 60}s`
+}
+
+/** @returns true when a finished run did not complete normally. */
+function failed(stopReason) {
+  return stopReason !== undefined && stopReason !== 'completed'
+}
+
+/** @returns the reason text for a failed run (`max_tokens` → `max tokens`). */
+function reasonText(stopReason) {
+  return String(stopReason).replace(/[_-]+/gu, ' ')
+}
+
+/**
+ * The status text of one board.
+ * @param entries - `{ label, model, depth, startedAt, endedAt, stopReason }` in start order.
+ * @param now - current time in ms.
+ * @param tr - `(en, ru) => text` for the bot language.
+ */
+export function boardText(entries, now, tr = (en) => en) {
+  const running = entries.filter((entry) => entry.endedAt === undefined).length
+  const failures = entries.filter((entry) => entry.endedAt !== undefined && failed(entry.stopReason)).length
+  const total = entries.length
+  const noun = tr(total === 1 ? 'subagent' : 'subagents', 'субагент(ов)')
+  let head
+  if (running > 0) head = `🤖 ${total} ${noun} · ${running} ${tr('running', 'работают')}`
+  else if (failures > 0) head = `🤖 ${total} ${noun} · ${tr('done', 'готово')}, ${failures} ${tr('failed', 'с ошибкой')}`
+  else head = `🤖 ${total} ${noun} · ${tr('all done', 'все готовы')}`
+  const lines = entries.map((entry) => {
+    const indent = entry.depth > 1 ? `${'  '.repeat(entry.depth - 2)}↳ ` : ''
+    const parts = [clip(entry.label, LABEL_MAX)]
+    if (entry.model) parts.push(entry.model)
+    if (entry.endedAt === undefined) {
+      parts.push(formatElapsed(now - entry.startedAt, false))
+      return `${indent}⏳ ${parts.join(' · ')}`
+    }
+    parts.push(formatElapsed(entry.endedAt - entry.startedAt, true))
+    if (failed(entry.stopReason)) parts.push(reasonText(entry.stopReason))
+    return `${indent}${failed(entry.stopReason) ? '✗' : '✓'} ${parts.join(' · ')}`
+  })
+  if (lines.length > MAX_LINES) {
+    // Keep running lines and the newest ones; fold the oldest finished lines.
+    const keep = new Set()
+    entries.forEach((entry, index) => { if (entry.endedAt === undefined) keep.add(index) })
+    for (let index = entries.length - 1; index >= 0 && keep.size < MAX_LINES - 1; index -= 1) keep.add(index)
+    const folded = lines.length - keep.size
+    const shown = lines.filter((_line, index) => keep.has(index))
+    return [head, `… ${folded} ${tr('earlier finished', 'завершённых ранее')}`, ...shown].join('\n')
+  }
+  return [head, ...lines].join('\n')
+}
+
+/** @returns whether a tool name is the subagent reporting tool (`send_message`, maybe prefixed). */
+function isReportTool(name) {
+  return typeof name === 'string' && (name === 'send_message' || name.endsWith('__send_message'))
+}
+
+/** @returns the `message` argument of a tool call, or ''. */
+function reportArgument(block) {
+  let args = block?.arguments ?? block?.input
+  if (typeof args === 'string') {
+    try {
+      args = JSON.parse(args)
+    } catch {
+      return ''
+    }
+  }
+  return typeof args?.message === 'string' ? args.message.trim() : ''
+}
+
+/**
+ * The latest report a subagent left: a message it sent its parent, or the
+ * answer of its last tool-free message, whichever is newer.
+ * @param events - the child's session events (`{ type, data }`).
+ * @returns the report text, or ''.
+ */
+export function reportOf(events) {
+  if (!Array.isArray(events)) return ''
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event?.type !== 'assistant/message') continue
+    const message = event.data?.message ?? event.data
+    const content = Array.isArray(message?.content) ? message.content : []
+    for (let block = content.length - 1; block >= 0; block -= 1) {
+      const item = content[block]
+      if (item?.type === 'tool-call' && isReportTool(item.name)) {
+        const text = reportArgument(item)
+        if (text.length > 0) return text
+      }
+    }
+    const answer = messageAnswer(message)
+    if (answer.length > 0) return answer
+  }
+  return ''
+}
+
+/**
+ * State of one listed subagent, from its live agent and durable timing.
+ * @param facts - `{ status, timing }`: live agent status (or undefined when not loaded) and the `subagentTiming` view.
+ * @param now - current time in ms.
+ * @returns `{ state, elapsedMs }`; state is running, done, failed, interrupted or idle.
+ */
+export function childState({ status, timing }, now) {
+  const settled = Number.isFinite(timing?.settledMs) ? timing.settledMs : 0
+  const active = timing?.active
+  if (status === 'running') {
+    return { state: 'running', elapsedMs: active === undefined ? settled : settled + Math.max(0, now - active.since) }
+  }
+  if (active !== undefined) {
+    // A turn left open with no live agent was cut off, usually by a restart.
+    return { state: status === undefined ? 'interrupted' : 'running', elapsedMs: settled + Math.max(0, (status === undefined ? active.through : now) - active.since) }
+  }
+  if (timing?.lastTurnCompleted === false) return { state: 'failed', elapsedMs: settled }
+  if (timing?.lastTurnCompleted === true) return { state: 'done', elapsedMs: settled }
+  return { state: 'idle', elapsedMs: settled }
+}
+
+/** @returns relative age such as `5m ago`. */
+export function ageText(createdAt, now, tr = (en) => en) {
+  if (!Number.isFinite(createdAt)) return ''
+  const minutes = Math.max(0, Math.floor((now - createdAt) / 60_000))
+  if (minutes < 1) return tr('just now', 'только что')
+  if (minutes < 60) return tr(`${minutes}m ago`, `${minutes} мин назад`)
+  const hours = Math.floor(minutes / 60)
+  if (hours < 48) return tr(`${hours}h ago`, `${hours} ч назад`)
+  return tr(`${Math.floor(hours / 24)}d ago`, `${Math.floor(hours / 24)} дн назад`)
+}
+
+const STATE_ICONS = { running: '⏳', done: '✓', failed: '✗', interrupted: '⚠️', idle: '•' }
+
+/**
+ * The `/agents` reply.
+ * @param rows - `{ label, model, depth, state, elapsedMs, createdAt, report }`, newest first.
+ * @param total - how many subagents the session has in all.
+ * @param now - current time in ms.
+ * @param tr - `(en, ru) => text`.
+ */
+export function agentsListText(rows, total, now, tr = (en) => en) {
+  if (rows.length === 0) return tr('This session has started no subagents.', 'Эта сессия не запускала субагентов.')
+  const head = total > rows.length
+    ? tr(`🤖 Subagents (latest ${rows.length} of ${total}):`, `🤖 Субагенты (последние ${rows.length} из ${total}):`)
+    : tr('🤖 Subagents:', '🤖 Субагенты:')
+  const states = {
+    running: tr('running', 'работает'),
+    done: tr('done', 'готово'),
+    failed: tr('failed', 'ошибка'),
+    interrupted: tr('interrupted', 'прерван'),
+    idle: tr('idle', 'ожидает'),
+  }
+  const blocks = rows.map((row) => {
+    const indent = row.depth > 1 ? '↳ ' : ''
+    const facts = [states[row.state] ?? row.state]
+    if (row.model) facts.push(row.model)
+    if (row.elapsedMs > 0 || row.state === 'running') facts.push(formatElapsed(row.elapsedMs, row.state !== 'running'))
+    const age = ageText(row.createdAt, now, tr)
+    if (age) facts.push(age)
+    const lines = [`${indent}${STATE_ICONS[row.state] ?? '•'} ${clip(row.label, LABEL_MAX)}`, `   ${facts.join(' · ')}`]
+    const report = clip(String(row.report ?? '').replace(/\s+/gu, ' ').trim(), REPORT_MAX)
+    if (report) lines.push(`   “${report}”`)
+    return lines.join('\n')
+  })
+  return [head, '', blocks.join('\n\n')].join('\n')
+}
+
+/**
+ * Track subagent runs and keep one status message per batch in the topic.
+ * @param deps - Host and Telegram access:
+ *   - `parentOf(sessionId)`: the parent session id of a live session, or undefined.
+ *   - `topicOf(sessionId)`: the topic state a session is bound to, or undefined.
+ *   - `turnOf(topic)`: a key for the turn the topic is showing, or undefined when none.
+ *   - `labelOf(parentId, childId)`: the child's description from its parent's catalog.
+ *   - `modelOf(childId)`: the child's model id.
+ *   - `post(topic, text)`: send a message, resolves to its id or undefined.
+ *   - `edit(topic, messageId, text)`: resolves to `ok`, `gone` (send a new one) or `failed` (try later).
+ *   - `reportError(scope, error)`, `tr(en, ru)`, `now()`, `delayMs`, `tickMs`.
+ * @returns `{ onStart, onEnd, dispose, boards }`.
+ */
+export function createAgentBoards(deps) {
+  const {
+    parentOf, topicOf, turnOf, labelOf, modelOf, post, edit, reportError,
+    tr = (en) => en, now = Date.now, delayMs = EDIT_DELAY_MS, tickMs = TICK_MS,
+  } = deps
+  /** Open boards by topic key, oldest first. */
+  const open = new Map()
+  let disposed = false
+
+  function boardsOf(key) {
+    let list = open.get(key)
+    if (list === undefined) {
+      list = []
+      open.set(key, list)
+    }
+    return list
+  }
+
+  function closeBoard(board) {
+    const list = open.get(board.topic.key)
+    if (list !== undefined) {
+      const index = list.indexOf(board)
+      if (index !== -1) list.splice(index, 1)
+      if (list.length === 0) open.delete(board.topic.key)
+    }
+    if (board.tick !== undefined) clearInterval(board.tick)
+    board.tick = undefined
+  }
+
+  /** Publish soon; changes before the timer fires share the edit. */
+  function schedule(board) {
+    if (disposed || board.timer !== undefined) return
+    board.timer = setTimeout(() => {
+      board.timer = undefined
+      board.chain = board.chain
+        .then(() => publish(board))
+        .catch((error) => reportError('subagent status', error))
+    }, delayMs)
+    board.timer.unref?.()
+  }
+
+  async function fillLabels(board) {
+    await Promise.all([...board.entries.values()].filter((entry) => !entry.labelKnown).map(async (entry) => {
+      const label = await Promise.resolve(labelOf(entry.parentId, entry.id)).catch(() => undefined)
+      if (typeof label === 'string' && label.trim()) {
+        entry.label = label.trim()
+        entry.labelKnown = true
+      }
+    }))
+  }
+
+  async function publish(board) {
+    if (disposed) return
+    await fillLabels(board)
+    const entries = [...board.entries.values()]
+    const done = entries.every((entry) => entry.endedAt !== undefined)
+    // Freeze before any wait, so a subagent starting meanwhile opens a new board.
+    if (done) closeBoard(board)
+    const text = boardText(entries, now(), tr)
+    if (text === board.lastText) return
+    if (board.messageId !== undefined) {
+      const outcome = await edit(board.topic, board.messageId, text)
+      if (outcome === 'ok') {
+        board.lastText = text
+        return
+      }
+      if (outcome !== 'gone') {
+        // A running board retries with its next change or tick; a finished
+        // one has neither, so it tries once more after a pause.
+        if (done) {
+          await new Promise((resolve) => { setTimeout(resolve, delayMs * 4).unref?.() })
+          if (!disposed && (await edit(board.topic, board.messageId, text)) === 'ok') board.lastText = text
+        }
+        return
+      }
+      board.messageId = undefined
+    }
+    const messageId = await post(board.topic, text)
+    if (messageId !== undefined) {
+      board.messageId = messageId
+      board.lastText = text
+    }
+  }
+
+  /**
+   * A subagent run started (`subagent/start`).
+   * @param info - `{ runId, id }`.
+   */
+  async function onStart(info) {
+    if (disposed || typeof info?.id !== 'string') return
+    const parentId = parentOf(info.id)
+    let topic
+    const ancestors = []
+    let current = parentId
+    for (let depth = 0; depth < MAX_DEPTH && typeof current === 'string'; depth += 1) {
+      topic = topicOf(current)
+      if (topic !== undefined) break
+      ancestors.push(current)
+      current = parentOf(current)
+    }
+    if (topic === undefined) return
+    const list = boardsOf(topic.key)
+    // A nested subagent joins the board that shows its nearest ancestor.
+    let board
+    for (const ancestor of ancestors) {
+      board = list.find((candidate) => [...candidate.entries.values()].some((entry) => entry.id === ancestor))
+      if (board !== undefined) break
+    }
+    if (board === undefined) {
+      const turn = turnOf(topic)
+      if (turn === undefined) {
+        if (list.length === 0) open.delete(topic.key)
+        return
+      }
+      board = list.find((candidate) => candidate.turn === turn)
+      if (board === undefined) {
+        board = { topic, turn, entries: new Map(), messageId: undefined, lastText: undefined, timer: undefined, tick: undefined, chain: Promise.resolve() }
+        list.push(board)
+        board.tick = setInterval(() => schedule(board), tickMs)
+        board.tick.unref?.()
+      }
+    }
+    const entry = {
+      id: info.id,
+      parentId,
+      label: tr(`subagent ${info.id.slice(0, 8)}`, `субагент ${info.id.slice(0, 8)}`),
+      labelKnown: false,
+      model: '',
+      depth: ancestors.length + 1,
+      startedAt: now(),
+      endedAt: undefined,
+      stopReason: undefined,
+    }
+    board.entries.set(info.runId ?? info.id, entry)
+    schedule(board)
+    const model = await Promise.resolve(modelOf(info.id)).catch(() => undefined)
+    if (typeof model === 'string' && model.length > 0) entry.model = model
+  }
+
+  /**
+   * A subagent run ended (`subagent/end`).
+   * @param info - `{ runId, id, stopReason }`.
+   */
+  function onEnd(info) {
+    const key = info?.runId ?? info?.id
+    for (const list of open.values()) {
+      for (const board of list) {
+        const entry = board.entries.get(key)
+        if (entry === undefined || entry.endedAt !== undefined) continue
+        entry.endedAt = now()
+        entry.stopReason = info.stopReason
+        schedule(board)
+        return
+      }
+    }
+  }
+
+  function dispose() {
+    disposed = true
+    for (const list of open.values()) {
+      for (const board of list) {
+        if (board.timer !== undefined) clearTimeout(board.timer)
+        if (board.tick !== undefined) clearInterval(board.tick)
+      }
+    }
+    open.clear()
+  }
+
+  return { onStart, onEnd, dispose, boards: open }
+}
+
+/**
+ * Collect a session's subagents for `/agents`: every descendant reachable
+ * through the catalogs of recent children, newest first, running ones kept.
+ * @param listChildren - `(sessionId) => Promise<[{ id, label, createdAt, mode }]>`.
+ * @param rootId - the topic's session.
+ * @param isRunning - `(id) => boolean` for live, working subagents.
+ * @param limit - rows to return.
+ * @returns `{ rows: [{ id, label, createdAt, depth }], total }`.
+ */
+export async function collectSubagents(listChildren, rootId, isRunning, limit = LIST_LIMIT) {
+  const found = []
+  const seen = new Set([rootId])
+  /** Catalog reads are bounded: descendants of old children are old too. */
+  let budget = limit * 4
+  const walk = async (parentId, depth) => {
+    let children
+    try {
+      children = await listChildren(parentId)
+    } catch {
+      return
+    }
+    if (!Array.isArray(children)) return
+    const recent = [...children].sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0))
+    for (const child of recent) {
+      if (seen.has(child.id)) continue
+      seen.add(child.id)
+      found.push({ id: child.id, label: child.label, createdAt: child.createdAt, depth })
+    }
+    for (const child of recent) {
+      if (child.mode === 'external' || depth >= MAX_DEPTH) continue
+      if (budget <= 0 && !isRunning(child.id)) continue
+      budget -= 1
+      await walk(child.id, depth + 1)
+    }
+  }
+  await walk(rootId, 1)
+  found.sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0))
+  const running = found.filter((row) => isRunning(row.id))
+  const rows = [...running, ...found.filter((row) => !isRunning(row.id)).slice(0, Math.max(0, limit - running.length))]
+  rows.sort((left, right) => (right.createdAt ?? 0) - (left.createdAt ?? 0))
+  return { rows, total: found.length }
+}

package/src/app.js

@@ -43,6 +43,7 @@ import { createUpdateAdmission } from './update-ledger.js'
 import { publishStatus } from './status.js'
 import { messageAnswer, turnAnswer } from './final-text.js'
 import { createOutbox } from './outbox.js'
+import { agentsListText, childState, collectSubagents, createAgentBoards, reportOf } from './agents.js'
 import { deliveredToTopic, isAutoCommandTopic, isPlaceholderTitle, isTopicGone, plannedTitle, resolveSendTarget, sessionTitleOf, topicNameOf, topicTargetFor } from './topics.js'
 import { runProgram, spokenMediaOf, transcribe, transcriptNote } from './voice.js'
 import { createStickerLibrary, describeSticker, STICKER_PREVIEW_DIR } from './stickers.js'
@@ -4263,6 +4264,110 @@ export function apply(ctx, config) {
     return texts
   }
 
+  /**
+   * The description a parent gave one of its subagents, from its catalog.
+   * @param parentId - parent session.
+   * @param childId - subagent session.
+   * @returns the label, or undefined.
+   */
+  async function subagentLabel(parentId, childId) {
+    if (typeof parentId !== 'string') return undefined
+    const children = await ctx.get('subagents')?.listChildren(parentId).catch(() => undefined)
+    const label = Array.isArray(children) ? children.find((child) => child.id === childId)?.label : undefined
+    return typeof label === 'string' && label.trim().length > 0 ? label.trim() : undefined
+  }
+
+  /**
+   * Post a subagent status message, after what the topic has queued.
+   * @param chat - topic state.
+   * @param text - status text.
+   * @returns the message id, or undefined.
+   */
+  function postAgentStatus(chat, text) {
+    const posted = (chat.answerEdit ?? Promise.resolve()).catch(() => {}).then(async () => {
+      try {
+        const result = await call('sendMessage', {
+          chat_id: chat.chatId,
+          ...topicTarget(chat.chatId, chat.threadId),
+          text,
+          disable_notification: true,
+        }, bridgeAbort.signal)
+        return typeof result?.message_id === 'number' ? result.message_id : undefined
+      } catch (error) {
+        if (!bridgeAbort.signal.aborted) warn(`subagent status send failed: ${messageOf(error)}`)
+        return undefined
+      }
+    })
+    chat.answerEdit = posted.then(() => {}, () => {})
+    return posted
+  }
+
+  /**
+   * Edit a subagent status message in place.
+   * @returns `ok`, `gone` when the message can no longer be edited, or `failed`.
+   */
+  async function editAgentStatus(chat, messageId, text) {
+    try {
+      await call('editMessageText', {
+        chat_id: chat.chatId,
+        message_id: messageId,
+        ...(chat.threadId === undefined || chat.threadId === 0 ? {} : { message_thread_id: chat.threadId }),
+        text,
+      }, bridgeAbort.signal)
+      return 'ok'
+    } catch (error) {
+      const message = messageOf(error)
+      if (/not modified/i.test(message)) return 'ok'
+      if (/message to edit not found|message can't be edited|message_id_invalid/i.test(message)) return 'gone'
+      if (!bridgeAbort.signal.aborted) warn(`subagent status edit failed: ${message}`)
+      return 'failed'
+    }
+  }
+
+  /**
+   * The `/agents` text for a session: its running and latest subagents with
+   * their state and the start of their last report. Read from DSH's durable
+   * catalogs and session logs, so it works for subagents of earlier runs.
+   * @param sessionId - the topic's session.
+   * @returns the reply text, or undefined when this DSH has no subagent service.
+   */
+  async function subagentsText(sessionId) {
+    const subagents = ctx.get('subagents')
+    if (typeof subagents?.listChildren !== 'function') return undefined
+    const agents = ctx.get('agents')
+    const isRunning = (id) => agents?.get(id)?.status === 'running'
+    const { rows, total } = await collectSubagents((id) => subagents.listChildren(id), sessionId, isRunning)
+    const now = Date.now()
+    const query = ctx.get('sessionQuery')
+    const detailed = await Promise.all(rows.map(async (row) => {
+      let timing
+      let model
+      let observation
+      try {
+        observation = await query?.observeSession(row.id)
+        const values = observation?.projections?.values
+        timing = values?.subagentTiming
+        const selection = values?.modelSelection
+        model = (selection?.next ?? selection?.pending ?? selection?.lastUsed)?.model
+      } catch {
+        // State falls back to what the live agent says.
+      } finally {
+        observation?.[Symbol.dispose]?.()
+      }
+      const live = agents?.get(row.id)
+      if (typeof live?.model?.current === 'function') model = live.model.current()?.model ?? model
+      let events = []
+      try {
+        events = (await query?.readSurface(row.id))?.events ?? []
+      } catch {
+        // No report preview.
+      }
+      const { state, elapsedMs } = childState({ status: live?.status, timing }, now)
+      return { ...row, label: row.label || `subagent ${String(row.id).slice(0, 8)}`, model, state, elapsedMs, report: reportOf(events) }
+    }))
+    return agentsListText(detailed, total, now, tr)
+  }
+
   /**
    * Deliver a session preview into its topic.
    * @param record - topic mapping.
@@ -5252,7 +5357,7 @@ export function apply(ctx, config) {
               ? `${tr('To start a conversation, create a topic and send a message in it, or just send a message here in All: Telegram makes a topic for it. In the topic, pick the workspace, then a new session or an existing one. /sessions opens existing sessions in new topics.', 'Чтобы начать разговор, создай топик и напиши в него, или просто напиши здесь, в All: Telegram сам создаст для сообщения топик. В топике выбери workspace, затем новую или существующую сессию. /sessions открывает существующие сессии в новых топиках.')}\n`
               : `${tr('This topic has no session yet. Send a message to choose a workspace.', 'У этого топика ещё нет сессии. Напиши сообщение, чтобы выбрать workspace.')}\n`) +
           `\n<b>${tr('First run', 'Первый запуск')}:</b> @BotFather → Bot Settings → <b>Threaded mode</b> → ${tr('Enable', 'Включить')}.\n` +
-          `${tr('Commands', 'Команды')}: /sessions, /new, /workspace, /current, /menu, /rename, /topic, /fork, /last, /clear, /stop, /restart, /status, /id, /ping, /goal.`,
+          `${tr('Commands', 'Команды')}: /sessions, /new, /workspace, /current, /menu, /rename, /topic, /fork, /last, /agents, /clear, /stop, /restart, /status, /id, /ping, /goal.`,
         signal,
         threadId,
       )
@@ -5453,6 +5558,17 @@ export function apply(ctx, config) {
       return
     }
 
+    if (command === '/agents') {
+      if (!inSession) {
+        await send(chat.id, tr('This topic is not bound to a session. /sessions.', 'Этот topic не привязан к сессии. /sessions.'), signal, threadId)
+        return
+      }
+      const listed = await subagentsText(chatState.sessionId)
+      const body = listed ?? tr('This DSH has no subagent service.', 'В этом DSH нет сервиса субагентов.')
+      await sendPlain(chat.id, body.length > MAX_TELEGRAM_TEXT ? `${body.slice(0, MAX_TELEGRAM_TEXT - 1)}…` : body, signal, threadId)
+      return
+    }
+
     if (command === '/fork') {
       if (!inSession) {
         await send(chat.id, tr('Open a session first: /sessions.', 'Сначала открой сессию: /sessions.'), signal, threadId)
@@ -6569,6 +6685,29 @@ export function apply(ctx, config) {
     return () => outbox.stop()
   }, 'dsh-telegram-bot: outbox')
 
+  // Subagents started by a turn the topic shows get one status message per
+  // batch (src/agents.js).
+  const agentBoards = createAgentBoards({
+    parentOf: (id) => ctx.get('agents')?.get(id)?.session?.header?.parentSession,
+    topicOf: (sessionId) => (lifetime === undefined ? undefined : chatForSession(sessionId)),
+    turnOf: (chat) => (chat.busy && !chat.done ? chat.turnEpoch : undefined),
+    labelOf: subagentLabel,
+    modelOf: async (id) => (await sessionModelOf(ctx, id).catch(() => undefined))?.model,
+    post: postAgentStatus,
+    edit: editAgentStatus,
+    reportError,
+    tr,
+  })
+  ctx.on('subagent/start', (info) => fireAndForget('subagent status', () => agentBoards.onStart(info)), { global: true })
+  ctx.on('subagent/end', (info) => {
+    try {
+      agentBoards.onEnd(info)
+    } catch (error) {
+      reportError('subagent status', error)
+    }
+  }, { global: true })
+  ctx.effect(() => () => agentBoards.dispose(), 'dsh-telegram-bot: subagent status')
+
   // Record each Telegram sender on the prompt the session controller built for it.
   ctx.on('agent/pre-step', (payload, next) => principals.preStep(payload, next), { global: true })
   // Host-wide feeds: every session's events, whichever client started the

package/src/constants.js

@@ -41,6 +41,7 @@ const BOT_COMMANDS = [
   { command: 'topic', description: 'Manage topics: delete, wipe' },
   { command: 'fork', description: 'Fork this session into a new topic' },
   { command: 'last', description: 'Show the latest assistant messages' },
+  { command: 'agents', description: 'List running and recent subagents' },
   { command: 'goal', description: 'Goal: /goal <objective>, edit, pause, resume, clear' },
   { command: 'restart', description: 'Restart the Telegram bot runtime' },
   { command: 'id', description: 'Show user and chat ids' },
@@ -63,6 +64,7 @@ const BOT_COMMANDS_RU = [
   { command: 'topic', description: 'Управление топиками: delete, wipe' },
   { command: 'fork', description: 'Форкнуть сессию в новый topic' },
   { command: 'last', description: 'Показать последние ответы ассистента' },
+  { command: 'agents', description: 'Работающие и недавние субагенты' },
   { command: 'goal', description: 'Цель: /goal <цель>, edit, pause, resume, clear' },
   { command: 'restart', description: 'Перезапустить Telegram-бота' },
   { command: 'id', description: 'Показать user id и chat id' },