@soffits/dsh-telegram-bot 0.4.4 → 0.6.0

package/MAINTAINING.md

@@ -10,7 +10,7 @@ This repository is a maintained fork of [Boobaw/dsh-telegram-bot](https://github
 - Session titles are `Telegram-<person>-<DSH title>` (`plannedTitle` in `src/topics.js`): DSH has no title hook, so `syncTopicTitle` re-appends each generated `session/title` with the prefix and the same source (automatic titling keeps running), and `startTopicTitle` calls `sessionTitle.refresh` at the first model request, because the `Telegram-<person>-<topic name>` placeholder is a user title that stops automatic titling. `<person>` comes from `userNames` / `userNamesFile`, else the chat's Telegram name (`chatNames` in the state file, learned from messages or `getChat`). Each session record keeps the label its title carries (`titlePerson`), so a changed name still finds the old prefix. `migrateSessionTitles` brings every bound session to the current form once the bot connects, reading titles from the log first and opening only sessions whose title changes. DSH's session header keeps only its own fields (dsh-session copies `cwd`, `parentSession`, `agentPreset` and the rest by name), so the source and person are not in session meta; DSH 0.2.2 has experimental plugin records (`appendPluginRecord` in dsh-session) that could carry them in the log later. Topic renames record a `telegram-topic` notice as a `user/message` (`recordNote`): session search indexes only message, tool and todo events, not titles or queued inbox items.
 - Deleted topics are forgotten as soon as any Bot API call reports them gone (`forgetGoneTopic`).
 - Chat-wide commands sent in All are answered in All; the topic Telegram made for them is deleted.
-- Sender labels: each Telegram prompt names who wrote it.
+- Sender labels: each Telegram prompt names who wrote it, in a text line for the model and as `source.principal` for readers (`src/sender.js`). DSH writes `principal` itself only for non-owner callers of its session controller, and the bot hands text prompts to that controller, which builds the message, so the bot remembers the sender by request id and records it on the message in an `agent/pre-step` listener (DSH lets that hook replace a step's messages); messages the bot builds itself get it directly. Sends recorded in a bound session carry the sender (job, session or label) the same way.
 - Voice messages, audio and round videos: downloaded, transcribed (DSH speech-to-text or a configured command) and passed with their file path.
 - Messages sent during a running turn are steered into it (`src/steer.js`): text through `sessionController.prompt({ mode: 'steer' })`, the Web UI's own call, and prompts with stored attachments through `agent.steer`, the method that mode uses. DSH keeps the turn going while its next-step inbox holds input and starts a new turn when input is left after `turn/end`, so a message that lands as the turn ends is still answered; `chat.steerFollow` shows that turn in the topic even with `mirrorTurns` off, and is cleared at the first `turn/end` that leaves the inbox empty. Prompts reach DSH in order (`admitInOrder`). `busyMessages: queue` keeps upstream's bot-side queue.
 - Stickers: received ones are attached as images (thumbnail or first frame for animated and video stickers) and kept in a library (`src/stickers.js`) with the agent's meaning notes; the `telegram_sticker` tool finds, views, notes, loads sets and sends them through `sendToTopic`.
@@ -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/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/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

@@ -25,7 +25,7 @@ BotFather: **Bot Settings → Threaded mode → Enable**. Leave **Disallow users
 - One Telegram topic per DSH session; Web and Telegram use the same session.
 - You create the topics. A new topic asks which workspace to use, then whether to start a new session or continue an existing one from that workspace. The message that opened the topic runs once the session is chosen.
 - Topic names are yours: the bot never renames a topic after the session title. `/rename` renames it on request.
-- A Telegram session is titled `Telegram-<person>-<what the conversation is about>` in DSH, for example `Telegram-Livia-Fix empty Telegram sessions`, so the sidebar shows where each session comes from and whose chat it is. `<person>` is the name set for the chat's user in `userNames` or `userNamesFile`, else the user's Telegram first name; in a group it is the group's title. The last part is DSH's own title (its title model, or the first words of the first message); until it exists the topic name stands in for it. Sessions with titles from earlier versions (`<topic name> · <task>`, a bare topic name) are moved to this form when the bot starts. A title someone types for the session is left alone.
+- A Telegram session is titled `Telegram-<person>-<what the conversation is about>` in DSH, for example `Telegram-Ana-Plan a weekend trip`, so the sidebar shows where each session comes from and whose chat it is. `<person>` is the name set for the chat's user in `userNames` or `userNamesFile`, else the user's Telegram first name; in a group it is the group's title. The last part is DSH's own title (its title model, or the first words of the first message); until it exists the topic name stands in for it. Sessions with titles from earlier versions (`<topic name> · <task>`, a bare topic name) are moved to this form when the bot starts. A title someone types for the session is left alone.
 - Renaming a topic also records a short note in its session, such as `Telegram topic renamed: "Old" -> "New" (thread 123)`, so searching earlier sessions finds it under either name.
 - A session the bot creates for a topic is never handed out as a blank session. DSH's **New conversation** reuses a session that has not started a turn yet; the bot therefore starts one empty turn as soon as it creates a session, and stops it before any model request. Without this, a topic session waiting for its first message could be picked up by the Web UI, and that Web chat would be mirrored into the topic.
 - Deleted topics clean themselves up: when Telegram answers any call for a topic with "message thread not found", `TOPIC_ID_INVALID` or `TOPIC_DELETED`, the bot drops that topic's session binding and name and logs it. The session stays in DSH. A closed topic keeps its binding, since it can be reopened.
@@ -37,15 +37,24 @@ 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.
 - Documents and photos sent in a session topic are saved as DSH attachments and passed to the agent.
 - Voice messages, audio files and round video messages are saved as files and transcribed; the agent gets the transcript and the file's path, so it can check a doubtful transcript against the recording. See [Voice messages](#voice-messages).
-- 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.
+- 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.
@@ -145,7 +154,7 @@ Private-chat topics send with `message_thread_id`. If Telegram answers `message
 
 ## Send to a topic
 
-Scripts, scheduled jobs, other plugins and agents can post into a topic by its numeric thread id (`/id` in the topic shows it). The message (text, files, a sticker) appears in the topic and is also recorded in the session bound to that topic, without starting a turn, labelled with who sent it. This holds for the bound session's own sends too, so a Web UI reader of that session sees the same pictures, files and stickers: pictures and stickers (as their still image) are recorded as images, other files as file attachments. An idle session gets the record at once; a busy one gets it at its next step. Thread ids belong to one chat, so the message goes to the chat the bot saw that thread in (its binding or known name), not the chat that last wrote to the bot. A thread id the bot does not know in any chat is an error; nothing is created. In the rare case two chats have a topic with the same thread id, the send fails until the caller names the chat (`chat`, `--chat`). Topic names are only labels, never addresses. A known topic with no session gets a new one first, made the way `/new` makes it (the configured working directory and preset, titled after the topic), so the message is recorded; only a topic whose user is still choosing its session just shows the message, and the result says so (`note`). If no session can take the record, the message is still sent and the result carries `recordError`.
+Scripts, scheduled jobs, other plugins and agents can post into a topic by its numeric thread id (`/id` in the topic shows it). The message (text, files, a sticker) appears in the topic and is also recorded in the session bound to that topic, without starting a turn, labelled with who sent it. The record's source (kind `telegram-post`) names the topic it went to (`channel: 'telegram'`, `chatId`, `threadId`, `topic`) and the sender as `principal`: `{ kind: 'cron-job', channel: 'cron', id, name, sessionId? }` for a scheduled job, `{ kind: 'dsh-session', channel: 'dsh', id }` for a DSH session, or `{ kind: 'external', channel: 'external', id: <label> }` for a caller that gave only a label. This holds for the bound session's own sends too, so a Web UI reader of that session sees the same pictures, files and stickers: pictures and stickers (as their still image) are recorded as images, other files as file attachments. An idle session gets the record at once; a busy one gets it at its next step. Thread ids belong to one chat, so the message goes to the chat the bot saw that thread in (its binding or known name), not the chat that last wrote to the bot. A thread id the bot does not know in any chat is an error; nothing is created. In the rare case two chats have a topic with the same thread id, the send fails until the caller names the chat (`chat`, `--chat`). Topic names are only labels, never addresses. A known topic with no session gets a new one first, made the way `/new` makes it (the configured working directory and preset, titled after the topic), so the message is recorded; only a topic whose user is still choosing its session just shows the message, and the result says so (`note`). If no session can take the record, the message is still sent and the result carries `recordError`.
 
 The bot also remembers each such send (`$DSH_HOME/telegram/sent-messages.json`: the last 1,000 sends from the past 180 days, text up to 20,000 characters). When someone replies to or quotes one of those messages, the agent gets the whole original text, however many Telegram messages it was split into, with its send time, job name and sending session, and a hint to open that session for more context. This works after `/new` too, when the current session never saw the message.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soffits/dsh-telegram-bot",
-  "version": "0.4.4",
+  "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

@@ -35,13 +35,15 @@ import {
   toTelegramMarkdown,
   toolArg,
 } from './formatting.js'
-import { admitText } from './admission.js'
+import { admitText, promptRequestId } from './admission.js'
 import { STEER_REACTION, busyMode, clearTelegramInbox, hasPendingInput, steerPrompt } from './steer.js'
+import { createPrincipalTagger, sendPrincipal, telegramUserPrincipal } from './sender.js'
 import { loadState, STATE_PATH } from './state.js'
 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'
@@ -129,6 +131,10 @@ export function apply(ctx, config) {
     })
   /** Ids of legacy follow-up messages the bridge submitted from Telegram. */
   const telegramMessageIds = new Set()
+  // Telegram senders by `<chatId>:<messageId>`, kept from routing until the
+  // prompt is handed to DSH (a topic binding or the queue may come between).
+  const promptSenders = new Map()
+  const principals = createPrincipalTagger()
 
   /**
    * Persist the chat → session mapping atomically.
@@ -2754,7 +2760,7 @@ export function apply(ctx, config) {
       }
       let requestId
       try {
-        requestId = await steerPrompt(ctx, agent, { sessionId: chat.sessionId, chatId: chat.chatId, messageId, text, attachments }, signal)
+        requestId = await steerPrompt(ctx, agent, { sessionId: chat.sessionId, chatId: chat.chatId, messageId, text, attachments, principal: promptPrincipal(chat, messageId) }, signal, principals)
       } catch (error) {
         // Not admitted: the bot's queue still delivers it after the turn.
         reportError('steer', error)
@@ -2846,14 +2852,16 @@ export function apply(ctx, config) {
       const agent = await ensureAgent(chat)
       await unarchiveForTopic(chat)
       let admitted = false
+      const principal = promptPrincipal(chat, messageId)
       if (nativeText) {
+        principals.remember(promptRequestId(chat.chatId, messageId), principal)
         admitted = admitText(ctx, { sessionId: chat.sessionId, chatId: chat.chatId, messageId, text }, signal)
         if (admitted !== false) await admitted
       }
       if (!admitted) {
         const id = randomUUID()
         telegramMessageIds.add(id)
-        agent.followup({ id, role: 'user', content: [...(text.trim().length === 0 ? [] : [{ type: 'text', text }]), ...attachments], source: { kind: 'user' } })
+        agent.followup({ id, role: 'user', content: [...(text.trim().length === 0 ? [] : [{ type: 'text', text }]), ...attachments], source: { kind: 'user', ...(principal === undefined ? {} : { principal }) } })
       }
       // The turn/end listener finalizes the Telegram turn. whenIdle is only a
       // fallback for the turn that started this epoch, never a queued turn.
@@ -3952,13 +3960,17 @@ export function apply(ctx, config) {
    *   line the model also reads, `from` the request's sender.
    * @returns the message source.
    */
-  function postSource({ header, threadId, topic, from, self }) {
+  function postSource({ header, chatId, threadId, topic, from, self }) {
     const job = typeof from?.job === 'string' && from.job.trim().length > 0 ? from.job.trim() : null
     const label = typeof from?.label === 'string' && from.label.trim().length > 0 ? from.label.trim() : null
+    const principal = sendPrincipal(from)
     return {
       kind: POST_SOURCE_KIND,
       form: 'notice',
       summary: header.slice(0, 120),
+      ...(principal === undefined ? {} : { principal }),
+      channel: 'telegram',
+      chatId: String(chatId),
       threadId,
       topic: topic ?? null,
       job,
@@ -4105,7 +4117,7 @@ export function apply(ctx, config) {
           id: randomUUID(),
           role: 'user',
           content,
-          source: postSource({ header, threadId, topic: target.name, from: request?.from, self }),
+          source: postSource({ header, chatId, threadId, topic: target.name, from: request?.from, self }),
         })
         recorded = true
       } catch (error) {
@@ -4252,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.
@@ -5241,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,
       )
@@ -5442,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)
@@ -5873,6 +6000,36 @@ export function apply(ctx, config) {
     return { text, attachments, messageId: message.message_id, from: message.from }
   }
 
+  /**
+   * Keep who wrote a Telegram message until its prompt reaches DSH.
+   * @param chatId - Telegram chat.
+   * @param messageId - Telegram message id.
+   * @param from - Telegram `from` of the message.
+   */
+  function rememberSender(chatId, messageId, from) {
+    if (!Number.isSafeInteger(messageId) || from === undefined || from === null) return
+    const key = `${chatId}:${messageId}`
+    promptSenders.delete(key)
+    promptSenders.set(key, from)
+    if (promptSenders.size > 1024) promptSenders.delete(promptSenders.keys().next().value)
+  }
+
+  /**
+   * The sender of a Telegram message, recorded on its prompt's source.
+   * @param chat - the topic the prompt runs in.
+   * @param messageId - Telegram message id.
+   * @returns the principal, or undefined when the sender is not known.
+   */
+  function promptPrincipal(chat, messageId) {
+    const from = promptSenders.get(`${chat.chatId}:${messageId}`)
+    if (from === undefined) return undefined
+    return telegramUserPrincipal(from, {
+      chatId: chat.chatId,
+      threadId: chat.threadId,
+      topic: typeof chat.threadId === 'number' ? topicNameFor(chat.chatId, chat.threadId) : undefined,
+    })
+  }
+
   /**
    * Route one prompt: a new topic from All, the workspace picker in a topic
    * without a session, or a turn in the bound session.
@@ -5886,6 +6043,7 @@ export function apply(ctx, config) {
     // Say who is writing: several allowed users may share one bot.
     const label = senderLabel(prompt.from)
     if (label !== undefined) prompt = { ...prompt, text: prompt.text.length > 0 ? `${label}\n${prompt.text}` : label }
+    rememberSender(chatId, prompt.messageId, prompt.from)
     const route = routeMessage({ threadId, inSession: typeof chatState.sessionId === 'string' })
     if (route === 'new-topic') {
       await createNewSessionTopic(chatId, threadId, signal, defaultWorkspaceCwd(), prompt.text, prompt.attachments, prompt.messageId)
@@ -6527,6 +6685,31 @@ 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
   // turn. Only sessions bound to a topic are mirrored.
   ctx.on('session/event', (session, event) => {

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' },

package/src/sender.js

@@ -0,0 +1,134 @@
+/**
+ * Who sent a message, as data on the message itself.
+ *
+ * DSH's field for the caller behind a user message is `source.principal`:
+ * the session controller writes it for callers other than the owner, so an
+ * absent principal means the owner. The bot admits every Telegram prompt as
+ * the owner, so it fills the field itself, and also on the copies of sends it
+ * records in bound sessions. Readers then get the sender without parsing the
+ * sender line, which stays in the text for the model.
+ *
+ * Every principal has `kind`, `channel` and `id`, and `name` when one is
+ * known; the other fields depend on the kind. None carries a credential, so
+ * all are safe in a session log.
+ */
+
+/** Remembered prompts waiting for their step; the oldest go first past this. */
+export const MAX_PENDING_PRINCIPALS = 1024
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined
+}
+
+/**
+ * The Telegram user who wrote a message, and where.
+ * @param user - Telegram `from` of the message.
+ * @param where - `{ chatId, threadId, topic }`: the chat, its topic thread and the topic's name.
+ * @returns the principal, or undefined without a sender.
+ */
+export function telegramUserPrincipal(user, { chatId, threadId, topic } = {}) {
+  if (user === undefined || user === null || user.id === undefined || user.id === null) return undefined
+  const name = [user.first_name, user.last_name].map(nonEmpty).filter((part) => part !== undefined).join(' ')
+  const username = nonEmpty(user.username)
+  const chat = chatId === undefined || chatId === null
+    ? undefined
+    : {
+        id: String(chatId),
+        ...(Number.isSafeInteger(threadId) && threadId > 0 ? { thread: threadId } : {}),
+        ...(nonEmpty(topic) === undefined ? {} : { name: nonEmpty(topic) }),
+      }
+  return {
+    kind: 'telegram-user',
+    channel: 'telegram',
+    id: String(user.id),
+    ...(name.length > 0 ? { name } : {}),
+    ...(username === undefined ? {} : { username }),
+    ...(chat === undefined ? {} : { chat }),
+  }
+}
+
+/**
+ * The sender of a send into a topic, from the request's `from`: a scheduled
+ * job, else a DSH session, else the free-form label of an outside caller.
+ * @param from - `{ job?, jobId?, sessionId?, label? }`.
+ * @returns the principal, or undefined when the request names no sender.
+ */
+export function sendPrincipal(from) {
+  const job = nonEmpty(from?.job)
+  const jobId = nonEmpty(from?.jobId)
+  const sessionId = nonEmpty(from?.sessionId)
+  const label = nonEmpty(from?.label)
+  if (job !== undefined || jobId !== undefined) {
+    return {
+      kind: 'cron-job',
+      channel: 'cron',
+      id: jobId ?? job,
+      ...(job === undefined ? {} : { name: job }),
+      ...(sessionId === undefined ? {} : { sessionId }),
+    }
+  }
+  if (sessionId !== undefined) {
+    return { kind: 'dsh-session', channel: 'dsh', id: sessionId, ...(label === undefined ? {} : { name: label }) }
+  }
+  if (label !== undefined) return { kind: 'external', channel: 'external', id: label, name: label }
+  return undefined
+}
+
+/**
+ * A frozen copy of a message whose source records its sender.
+ * @param message - the user message.
+ * @param principal - its sender.
+ * @returns the copy; the message itself when there is no principal.
+ */
+export function withPrincipal(message, principal) {
+  if (principal === undefined) return message
+  return Object.freeze({ ...message, source: Object.freeze({ ...message.source, principal: deepFreeze(principal) }) })
+}
+
+function deepFreeze(value) {
+  if (typeof value === 'object' && value !== null && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child)
+    Object.freeze(value)
+  }
+  return value
+}
+
+/**
+ * Principals for prompts the bot hands to DSH's session controller, which
+ * builds the message itself. The bot remembers the sender by request id
+ * before the hand-over; `preStep`, an `agent/pre-step` listener, records it
+ * on the message as it enters a step, so it is in the session log with the
+ * message (DSH lets that hook replace the messages of a step).
+ * @param limit - most principals remembered at once.
+ */
+export function createPrincipalTagger(limit = MAX_PENDING_PRINCIPALS) {
+  const pending = new Map()
+  return {
+    /** Remember the sender of the prompt with this request id. */
+    remember(requestId, principal) {
+      if (typeof requestId !== 'string' || principal === undefined) return
+      pending.delete(requestId)
+      pending.set(requestId, principal)
+      if (pending.size > limit) pending.delete(pending.keys().next().value)
+    },
+    /** Pending principals, for tests. */
+    get size() {
+      return pending.size
+    },
+    /** `agent/pre-step` listener: record remembered senders on the step's messages. */
+    async preStep(_payload, next) {
+      const decision = await next()
+      if (decision?.kind !== 'enter' || pending.size === 0 || !Array.isArray(decision.messages)) return decision
+      let changed = false
+      const messages = decision.messages.map((message) => {
+        const rpcId = message?.source?.kind === 'user' ? message.source.rpcId : undefined
+        const principal = typeof rpcId === 'string' ? pending.get(rpcId) : undefined
+        if (principal === undefined || message.source.principal !== undefined) return message
+        pending.delete(rpcId)
+        changed = true
+        return withPrincipal(message, principal)
+      })
+      return changed ? { ...decision, messages } : decision
+    },
+  }
+}

package/src/steer.js

@@ -52,20 +52,24 @@ function hasRequest(agent, requestId) {
  * dropped. A request id already admitted is skipped, so it is never sent twice.
  * @param ctx - plugin context.
  * @param agent - the session's live agent.
- * @param prompt - `{ sessionId, chatId, messageId, text, attachments }`.
+ * @param prompt - `{ sessionId, chatId, messageId, text, attachments, principal }`;
+ *   `principal` is the sender recorded on the message's source.
  * @param signal - request lifetime.
+ * @param tagger - remembers the principal of a prompt the session controller
+ *   builds (see `createPrincipalTagger`).
  * @returns the request id, or `undefined` when this DSH cannot steer.
  */
-export async function steerPrompt(ctx, agent, { sessionId, chatId, messageId, text, attachments = [] }, signal) {
+export async function steerPrompt(ctx, agent, { sessionId, chatId, messageId, text, attachments = [], principal }, signal, tagger) {
   const requestId = steerRequestId(chatId, messageId)
   const content = [...(text.trim().length === 0 ? [] : [{ type: 'text', text }]), ...attachments]
   const controller = ctx.get('sessionController')
   if (attachments.length === 0 && content.length > 0 && typeof controller?.prompt === 'function') {
+    tagger?.remember(requestId, principal)
     await controller.prompt({ sessionId, requestId, mode: 'steer', content }, signal)
     return requestId
   }
   if (hasRequest(agent, requestId)) return requestId
-  const message = { id: randomUUID(), role: 'user', content, source: { kind: 'user', rpcId: requestId } }
+  const message = { id: randomUUID(), role: 'user', content, source: { kind: 'user', rpcId: requestId, ...(principal === undefined ? {} : { principal }) } }
   if (typeof agent?.steer === 'function') agent.steer(message)
   else if (typeof agent?.send === 'function') agent.send(message, 'next-step', true)
   else return undefined