@soffits/dsh-telegram-bot 0.4.3 → 0.5.0

package/MAINTAINING.md

@@ -7,10 +7,10 @@ This repository is a maintained fork of [Boobaw/dsh-telegram-bot](https://github
 - Two-way sync: turns started in the Web UI, by scheduled tasks or by other plugins also appear in the bound topic (`mirrorTurns`).
 - Sending into topics by thread id: the `telegramTopics` Host service, the `telegram_send` tool and the `dsh-telegram-send` command, with the sender (job, session) recorded and remembered, so replies to those messages carry the full original. Every send, the bound session's own included, is recorded in the bound session as a `user/message` (`telegram-post:` request id, which the mirror skips) with its pictures, files and sticker image as attachments, because DSH has no non-model entry a plugin may append (new event types make a session unreadable) and a plain user message is what the Web UI draws with images. `recordMessage` appends it to an idle session and queues it otherwise.
 - Sessions the bot creates are never left blank (DSH's New conversation would reuse them): see `claimForTopic` in `src/app.js`.
-- Topic session titles are `<topic name> · <DSH title>`: 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 bare-name placeholder is a user title that stops automatic titling. 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.
+- 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`.
@@ -36,4 +36,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`, `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.

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 topic's session is titled `<topic name> · <what the conversation is about>` in DSH, for example `Chat-1 · Fix empty Telegram sessions`. The second part is DSH's own title (its title model, or the first words of the first message); until it exists the title is just the topic name. Renaming the topic changes only the first part. 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.
@@ -42,7 +42,7 @@ BotFather: **Bot Settings → Threaded mode → Enable**. Leave **Disallow users
 - `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`.
@@ -98,10 +98,13 @@ Restart `dsh web` after installing or updating the plugin. Then open **Settings
 | `transcribeLanguage` | Language hint for DSH speech-to-text, such as `zh` or `en`; empty uses its own setting |
 | `transcribeCommand` | Program and arguments for `transcriber: command` |
 | `ffmpegPath` | ffmpeg used to decode recordings for DSH speech-to-text; default `ffmpeg` |
+| `userNames` | Names for Telegram user ids (or group chat ids) in session titles, such as `{ "123456789": "Alex" }` |
+| `userNamesFile` | JSON file with more such names, re-read when it changes; `userNames` wins |
+| `userNamesKey` | Key of the id → name object inside `userNamesFile`; empty means the whole file is the map |
 | Bot language | `en` (default) or `ru` |
 | Enable bot | Start or pause Telegram polling |
 
-The voice fields, `controlChat` and `busyMessages` have no controls on the settings page yet; set them in the profile's `cordis.patch.yml` under the `telegram-bot` row's `config`.
+The voice fields, the name fields, `controlChat` and `busyMessages` have no controls on the settings page yet; set them in the profile's `cordis.patch.yml` under the `telegram-bot` row's `config`.
 
 The token field only reports whether a token is configured. A token supplied through the environment cannot be overwritten from the page.
 
@@ -142,11 +145,11 @@ 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.
 
-The bot learns a topic's name when it creates the topic, when Telegram reports a topic being created or renamed, and on `/rename`, and uses it in the labels of recorded messages and in session titles.
+The bot learns a topic's name when it creates the topic, when Telegram reports a topic being created or renamed, and on `/rename`, and uses it in the labels of recorded messages and as the placeholder in session titles.
 
 From a shell (no bot token needed):
 

package/package.json

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

package/src/app.js

@@ -1,5 +1,6 @@
 /** Host runtime: Telegram polling, topic routing and the DSH session bridge. */
 import { randomUUID } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
 import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import https from 'node:https'
 import { tmpdir } from 'node:os'
@@ -34,14 +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 { deliveredToTopic, isAutoCommandTopic, isPlaceholderTitle, isTopicGone, resolveSendTarget, topicNameOf, topicTargetFor, topicTask, topicTitle } from './topics.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'
 import { composePrompt, DOWNLOAD_LIMIT_BYTES, downloadableFile, isForwarded, messageBody, repliedMessage, replyReference, senderLabel } from './message-context.js'
@@ -128,6 +130,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.
@@ -240,6 +246,7 @@ export function apply(ctx, config) {
       threadId: chat.threadId,
       title: title ?? state.sessions[sessionId]?.title ?? '',
       ...(state.sessions[sessionId]?.titleLocked === true ? { titleLocked: true } : {}),
+      ...(typeof state.sessions[sessionId]?.titlePerson === 'string' ? { titlePerson: state.sessions[sessionId].titlePerson } : {}),
       ...(chat.cwd === undefined ? {} : { cwd: chat.cwd }),
       ...(chat.permission === undefined ? {} : { permission: chat.permission }),
       updatedAt: Date.now(),
@@ -1739,10 +1746,11 @@ export function apply(ctx, config) {
   function attachAgent(agent, chat) {
     if (chat.boundAgent === agent) return
     chat.boundAgent = agent
-    // Older versions titled topic sessions "TG · <name>"; move them to the
-    // current form when the session is next used.
-    if (agent.session !== undefined && typeof chat.threadId === 'number' && topicOfSession(agent.session.id) !== undefined) {
-      fireAndForget('topic-title', () => syncTopicTitle(agent.session, chat.chatId, chat.threadId))
+    // Bring a title from an older form, or with a changed person label, to
+    // the current one when the session is used.
+    const bound = agent.session === undefined ? undefined : topicOfSession(agent.session.id)
+    if (bound !== undefined) {
+      fireAndForget('topic-title', () => syncTopicTitle(agent.session, bound.chatId, bound.threadId))
     }
     agent.ctx.on('session/event', (session, event) => {
       try {
@@ -1928,7 +1936,11 @@ export function apply(ctx, config) {
       } catch {
         current = undefined
       }
-      if (service !== undefined && current === undefined) setSessionTitle(session, topicPrefixOf(chat.chatId, chat.threadId))
+      if (service !== undefined && current === undefined) {
+        const person = personOf(chat.chatId)
+        setSessionTitle(session, sessionTitleOf(person, topicNameFor(chat.chatId, chat.threadId)))
+        rememberTitlePerson(session.id, person)
+      }
     }
     if (typeof agent?.followup !== 'function' || typeof agent?.ctx?.on !== 'function') {
       warn(`session ${session?.id ?? agent?.id} cannot run an empty turn; DSH may treat it as blank`)
@@ -2747,7 +2759,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)
@@ -2839,14 +2851,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.
@@ -3438,48 +3452,149 @@ export function apply(ctx, config) {
   }
 
   /**
-   * The topic name a bound session's title starts with.
+   * The topic name that stands in a bound session's title until DSH has
+   * titled the conversation.
    * @param chatId - chat holding the topic.
    * @param threadId - topic thread.
    * @returns the topic's name, or "topic <id>" while it is unknown.
    */
-  function topicPrefixOf(chatId, threadId) {
+  function topicNameFor(chatId, threadId) {
     const name = state.topicNames?.[`${chatId}:${threadId}`]
     return typeof name === 'string' && name.trim().length > 0 ? name.trim() : `topic ${threadId}`
   }
 
+  /** Cached copy of the `userNamesFile` map, re-read when the file changes. */
+  let userNamesCache = { path: '', key: '', mtimeMs: -1, names: {} }
+
+  /**
+   * Names the operator gave Telegram users (and chats): `userNames` from the
+   * config over the map in `userNamesFile`.
+   * @returns `{ "<id>": name }`.
+   */
+  function userNamesOf() {
+    const inline = readLive(config.userNames, {})
+    const path = String(readLive(config.userNamesFile, '') ?? '').trim()
+    const key = String(readLive(config.userNamesKey, '') ?? '').trim()
+    let fromFile = {}
+    if (path.length > 0) {
+      try {
+        const mtimeMs = statSync(path).mtimeMs
+        if (userNamesCache.path !== path || userNamesCache.key !== key || userNamesCache.mtimeMs !== mtimeMs) {
+          const parsed = JSON.parse(readFileSync(path, 'utf8'))
+          const map = key.length > 0 ? parsed?.[key] : parsed
+          userNamesCache = { path, key, mtimeMs, names: map !== null && typeof map === 'object' && !Array.isArray(map) ? map : {} }
+        }
+        fromFile = userNamesCache.names
+      } catch (error) {
+        if (userNamesCache.path !== path || userNamesCache.mtimeMs !== -2) warn(`user names not read from ${path}: ${messageOf(error)}`)
+        userNamesCache = { path, key, mtimeMs: -2, names: {} }
+      }
+    }
+    const names = {}
+    for (const source of [fromFile, inline]) {
+      if (source === null || typeof source !== 'object') continue
+      for (const [id, name] of Object.entries(source)) {
+        if (typeof name === 'string' && name.trim().length > 0) names[String(id).trim()] = name.trim()
+      }
+    }
+    return names
+  }
+
+  /**
+   * Remember how Telegram names a chat, for session titles: a private chat's
+   * first name, a group's title.
+   * @param chat - Telegram chat object.
+   */
+  function rememberChatName(chat) {
+    if (typeof chat?.id !== 'number') return
+    const raw = chat.type === 'private' ? chat.first_name : chat.title
+    const name = typeof raw === 'string' ? raw.trim() : ''
+    if (name.length === 0) return
+    state.chatNames ??= {}
+    if (state.chatNames[String(chat.id)] === name) return
+    state.chatNames[String(chat.id)] = name
+    void persistState()
+  }
+
+  /**
+   * Whose chat a session belongs to, as its title shows it: the name the
+   * operator configured for the chat (a private chat's id is its user's id),
+   * else the name Telegram gives the chat (first name, group title).
+   * @param chatId - Telegram chat id.
+   * @returns the label.
+   */
+  function personOf(chatId) {
+    const configured = userNamesOf()[String(chatId)]
+    if (configured !== undefined) return configured
+    const known = state.chatNames?.[String(chatId)]
+    return typeof known === 'string' && known.length > 0 ? known : `chat ${chatId}`
+  }
+
   /**
-   * The topic a session is bound to.
+   * Learn the names of chats the bot has bound sessions in but never heard
+   * from since this version, so their titles get a name instead of an id.
+   * @param signal - cancellation.
+   */
+  async function learnChatNames(signal) {
+    const configured = userNamesOf()
+    const chatIds = new Set(Object.values(state.sessions).map((record) => record?.chatId).filter((id) => typeof id === 'number'))
+    for (const chatId of chatIds) {
+      if (signal.aborted) return
+      if (configured[String(chatId)] !== undefined || state.chatNames?.[String(chatId)] !== undefined) continue
+      try {
+        rememberChatName(await call('getChat', { chat_id: chatId }, signal, 10_000))
+      } catch (error) {
+        if (!signal.aborted) warn(`chat name not read for ${chatId}: ${messageOf(error)}`)
+      }
+    }
+  }
+
+  /**
+   * The chat a session is bound to: a topic, or a chat without topics.
    * @param sessionId - DSH session id.
-   * @returns `{ chatId, threadId }`, or undefined.
+   * @returns `{ chatId, threadId }` (threadId undefined without topics), or undefined.
    */
   function topicOfSession(sessionId) {
     if (!stateLoaded || typeof sessionId !== 'string') return undefined
     const record = state.sessions[sessionId]
-    if (typeof record?.chatId !== 'number' || typeof record.threadId !== 'number') return undefined
-    if (state.threads[`${record.chatId}:${record.threadId}`] !== sessionId) return undefined
-    return { chatId: record.chatId, threadId: record.threadId }
+    if (typeof record?.chatId !== 'number') return undefined
+    const threadId = typeof record.threadId === 'number' ? record.threadId : undefined
+    if (state.threads[`${record.chatId}:${threadId ?? 0}`] !== sessionId) return undefined
+    return { chatId: record.chatId, threadId }
   }
 
   /**
-   * Bring a topic session's title to "<topic name> · <conversation title>".
-   * DSH writes the conversation part (its title provider, or the first-prompt
-   * fallback); DSH has no title hook, so the bot adds the prefix by appending
-   * the same title event with the same source, which keeps automatic titling
-   * going. Before a conversation title exists the title is the bare topic
-   * name, set as a user title so DSH's fallback does not replace it; the bot
-   * asks DSH for the real title at the first model request (see
-   * `startTopicTitle`). A title someone typed is left alone.
+   * What a bound session's title may carry: the current person label and
+   * placeholder names, plus earlier ones it may still show.
+   * @param sessionId - DSH session id.
+   * @param chatId - chat holding the session.
+   * @param threadId - topic thread, undefined for a chat without topics.
+   * @param previousNames - earlier topic names.
+   * @returns `{ person, names, people }` for `plannedTitle`.
+   */
+  function titleContext(sessionId, chatId, threadId, previousNames = []) {
+    const person = personOf(chatId)
+    const names = typeof threadId === 'number' ? [topicNameFor(chatId, threadId), ...previousNames, `topic ${threadId}`] : []
+    const earlier = state.sessions[sessionId]?.titlePerson
+    return { person, names, people: typeof earlier === 'string' && earlier !== person ? [earlier] : [] }
+  }
+
+  /**
+   * Bring a bound session's title to "Telegram-<person>-<conversation title>"
+   * (see `plannedTitle`). DSH writes the conversation part (its title
+   * provider, or the first-prompt fallback); before it exists a topic
+   * session's title is "Telegram-<person>-<topic name>", set as a user title
+   * so DSH's fallback does not replace it, and the bot asks DSH for the real
+   * title at the first model request (see `startTopicTitle`). A title someone
+   * typed is left alone.
    * @param session - live session.
-   * @param chatId - chat holding the topic.
-   * @param threadId - topic thread.
+   * @param chatId - chat holding the session.
+   * @param threadId - topic thread, undefined for a chat without topics.
    * @param previousNames - earlier topic names the title may still carry.
    */
   function syncTopicTitle(session, chatId, threadId, previousNames = []) {
     const service = ctx.get('sessionTitle')
     if (service === undefined) return
-    const prefix = topicPrefixOf(chatId, threadId)
-    const names = [prefix, ...previousNames, `topic ${threadId}`]
     let current
     try {
       current = service.get(session)
@@ -3487,28 +3602,84 @@ export function apply(ctx, config) {
       warn(`session title not read for ${session?.id}: ${messageOf(error)}`)
       return
     }
-    if (current === undefined) {
-      setSessionTitle(session, prefix)
-      return
-    }
-    const title = current.title
-    if (current.source?.kind === 'user') {
-      if (isPlaceholderTitle(title, names) && title !== prefix) setSessionTitle(session, prefix)
-      return
+    const context = titleContext(session.id, chatId, threadId, previousNames)
+    const plan = plannedTitle(current, context)
+    if (plan.kind === 'rename') {
+      setSessionTitle(session, plan.title)
+    } else if (plan.kind === 'append') {
+      try {
+        session.append('session/title', {
+          title: plan.title,
+          messageSeqs: Array.isArray(current.messageSeqs) ? [...current.messageSeqs] : [],
+          source: current.source,
+        })
+      } catch (error) {
+        warn(`session title not set for ${session?.id}: ${messageOf(error)}`)
+        return
+      }
     }
-    const wanted = topicTitle(prefix, topicTask(title, names))
-    if (wanted === title) return
-    try {
-      session.append('session/title', {
-        title: wanted,
-        messageSeqs: Array.isArray(current.messageSeqs) ? [...current.messageSeqs] : [],
-        source: current.source,
-      })
-    } catch (error) {
-      warn(`session title not set for ${session?.id}: ${messageOf(error)}`)
+    rememberTitlePerson(session.id, context.person)
+  }
+
+  /**
+   * Record which person label a session's title carries, so a later change
+   * of that label (a new configured name) still finds the old prefix.
+   * @param sessionId - DSH session id.
+   * @param person - the label now in the title.
+   */
+  function rememberTitlePerson(sessionId, person) {
+    const record = state.sessions[sessionId]
+    if (record === undefined || record.titlePerson === person) return
+    record.titlePerson = person
+    void persistState()
+  }
+
+  /**
+   * Move every bound session's title to the current form once the bot is
+   * connected, so the sidebar shows where each session comes from without
+   * waiting for it to be used. Titles are read from the session log first;
+   * only a session whose title changes is opened. Topics are never renamed.
+   * @param signal - cancellation.
+   */
+  async function migrateSessionTitles(signal) {
+    const query = ctx.get('sessionQuery')
+    if (ctx.get('sessionTitle') === undefined) return
+    await learnChatNames(signal)
+    for (const [key, sessionId] of Object.entries(state.threads)) {
+      if (signal.aborted) return
+      const topic = topicOfSession(sessionId)
+      if (topic === undefined || `${topic.chatId}:${topic.threadId ?? 0}` !== key) continue
+      try {
+        const live = ctx.get('agents')?.get(sessionId)
+        if (live?.session === undefined && typeof query?.readTitleSnapshot === 'function') {
+          const observed = await query.readTitleSnapshot(sessionId, signal)
+          const context = titleContext(sessionId, topic.chatId, topic.threadId)
+          if (plannedTitle(observed?.title, context).kind === 'none') {
+            rememberTitlePerson(sessionId, context.person)
+            continue
+          }
+        }
+        const agent = live ?? await openForTitle(sessionId)
+        if (agent?.session !== undefined) syncTopicTitle(agent.session, topic.chatId, topic.threadId)
+      } catch (error) {
+        if (!signal.aborted) warn(`session title not migrated for ${sessionId}: ${messageOf(error)}`)
+      }
     }
   }
 
+  /**
+   * Open a bound session only to change its title, through the Web session
+   * controller as the Web UI's rename does. Unlike `ensureAgent`, a failure
+   * leaves the binding alone. Without a controller the session keeps its
+   * title until it is next used.
+   * @param sessionId - DSH session id.
+   * @returns the live agent, or undefined.
+   */
+  async function openForTitle(sessionId) {
+    const controller = sessionControllerOf()
+    return controller === undefined ? undefined : resolveThroughController(controller, sessionId)
+  }
+
   /** Sessions whose first conversation title is being generated. */
   const titleRequests = new Set()
 
@@ -3524,10 +3695,11 @@ export function apply(ctx, config) {
   function startTopicTitle(session) {
     const topic = topicOfSession(session?.id)
     const service = ctx.get('sessionTitle')
-    if (topic === undefined || typeof service?.refresh !== 'function' || titleRequests.has(session.id)) return
+    // Without a topic there is no placeholder, so DSH's own titling runs.
+    if (typeof topic?.threadId !== 'number' || typeof service?.refresh !== 'function' || titleRequests.has(session.id)) return
     const current = service.get(session)
-    const names = [topicPrefixOf(topic.chatId, topic.threadId), `topic ${topic.threadId}`]
-    if (current !== undefined && (current.source?.kind !== 'user' || !isPlaceholderTitle(current.title, names))) return
+    const { person, names, people } = titleContext(session.id, topic.chatId, topic.threadId)
+    if (current !== undefined && (current.source?.kind !== 'user' || !isPlaceholderTitle(current.title, names, [person, ...people]))) return
     const events = typeof session.snapshotEvents === 'function' ? session.snapshotEvents() : []
     const hasPrompt = events.some((event) => event?.type === 'user/message'
       && event.data?.source?.kind === 'user'
@@ -3787,13 +3959,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,
@@ -3940,7 +4116,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) {
@@ -4951,12 +5127,13 @@ export function apply(ctx, config) {
     const directTopicId = message.direct_messages_topic?.topic_id
     const threadId = message.message_thread_id ?? inferredTopicId(message)
     const announced = topicNameOf(message)
-    if (announced !== undefined && chat !== undefined && typeof threadId === 'number') {
-      try {
-        if (chatAllowed(chat, allowedChatsOf(config))) rememberTopicName(chat.id, threadId, announced.name, announced.authoritative)
-      } catch {
-        // A malformed allowlist is reported by the main check below.
+    try {
+      if (chat !== undefined && chatAllowed(chat, allowedChatsOf(config))) {
+        rememberChatName(chat)
+        if (announced !== undefined && typeof threadId === 'number') rememberTopicName(chat.id, threadId, announced.name, announced.authoritative)
       }
+    } catch {
+      // A malformed allowlist is reported by the main check below.
     }
     const hasAttachment = downloadableFile(message) !== undefined
     // A forward is a prompt even when its media cannot be attached (video,
@@ -5707,6 +5884,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.
@@ -5720,6 +5927,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)
@@ -6025,6 +6233,7 @@ export function apply(ctx, config) {
         void publishCommands(tokenLifetime.signal)
         void unpinLegacyGoalPanels(tokenLifetime.signal)
         void checkForumConfiguration(me, tokenLifetime.signal)
+        void migrateSessionTitles(tokenLifetime.signal).catch((error) => warn(`session titles not migrated: ${messageOf(error)}`))
         void notifyAll(
           `🟢 <b>${tr('Telegram bot enabled', 'Telegram-бот включён')}</b>\n` +
             `@${escapeHtml(me.username ?? String(me.id))}\n` +
@@ -6360,6 +6569,8 @@ export function apply(ctx, config) {
     return () => outbox.stop()
   }, 'dsh-telegram-bot: outbox')
 
+  // 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/config.js

@@ -34,6 +34,20 @@ export const Config = z.object({
    * other field is unchanged.
    */
   restartRequest: z.number().default(0).volatile(),
+  /**
+   * Names for Telegram user ids, shown in session titles
+   * ("Telegram-<name>-<task>"). A private chat's id is its user's id; group
+   * chat ids may be listed too. Unlisted chats use the name Telegram gives
+   * them (a user's first name, a group's title). Wins over `userNamesFile`.
+   */
+  userNames: z.dict(z.string()).default({}).volatile(),
+  /**
+   * JSON file with more such names, re-read when it changes, so a list kept
+   * elsewhere stays the one source. Empty means none.
+   */
+  userNamesFile: z.string().default('').volatile(),
+  /** Key of the id → name object inside `userNamesFile`; empty means the whole file. */
+  userNamesKey: z.string().default('').volatile(),
   /** Working directory for Telegram-created DSH sessions. */
   cwd: z.string().default(process.cwd()).volatile(),
   /** Agent preset mounted for Telegram-created sessions when presets exist. */

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/state.js

@@ -35,6 +35,7 @@ async function loadState() {
         updateLedger: parsed.updateLedger !== null && typeof parsed.updateLedger === 'object' && !Array.isArray(parsed.updateLedger) ? parsed.updateLedger : {},
         updateOffset: Number.isSafeInteger(parsed.updateOffset) && parsed.updateOffset >= 0 ? parsed.updateOffset : 0,
         topicNames: parsed.topicNames !== null && typeof parsed.topicNames === 'object' && !Array.isArray(parsed.topicNames) ? parsed.topicNames : {},
+        chatNames: parsed.chatNames !== null && typeof parsed.chatNames === 'object' && !Array.isArray(parsed.chatNames) ? parsed.chatNames : {},
         directChats: parsed.directChats !== null && typeof parsed.directChats === 'object' && !Array.isArray(parsed.directChats) ? parsed.directChats : {},
         directTopics: parsed.directTopics !== null && typeof parsed.directTopics === 'object' && !Array.isArray(parsed.directTopics) ? parsed.directTopics : {},
         goalPanels: parsed.goalPanels !== null && typeof parsed.goalPanels === 'object' && !Array.isArray(parsed.goalPanels) ? parsed.goalPanels : (parsed.goalPins !== null && typeof parsed.goalPins === 'object' && !Array.isArray(parsed.goalPins) ? parsed.goalPins : {}),
@@ -43,7 +44,7 @@ async function loadState() {
   } catch {
     // Missing or corrupt state is nonfatal; the next session creates a mapping.
   }
-  return { version: 2, sessions: {}, threads: {}, updateLedger: {}, updateOffset: 0, topicNames: {}, directChats: {}, directTopics: {}, goalPanels: {} }
+  return { version: 2, sessions: {}, threads: {}, updateLedger: {}, updateOffset: 0, topicNames: {}, chatNames: {}, directChats: {}, directTopics: {}, goalPanels: {} }
 }
 
 export { STATE_PATH, loadState }

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

package/src/topics.js

@@ -17,50 +17,97 @@ export function topicNameOf(message) {
   return undefined
 }
 
-/** Joins a topic name and the task part of a topic session's title. */
-export const TITLE_SEPARATOR = ' · '
+/** Where a bot session comes from, the first part of its DSH title. */
+export const TITLE_SOURCE = 'Telegram'
 
-/** The title form earlier versions gave topic sessions: "TG · <topic name>". */
+/** Joins the source, the person and the task in a session title. */
+const TITLE_JOIN = '-'
+
+/** Joined a topic name and the task in titles of earlier versions. */
+const LEGACY_SEPARATOR = ' · '
+
+/** The title form the oldest versions gave topic sessions: "TG · <topic name>". */
 const LEGACY_PREFIX = 'TG · '
 
 /**
- * The DSH title of a topic session: the topic name, then what the
- * conversation is about once DSH has titled it.
- * @param prefix - the topic's name.
- * @param task - the conversation's own title, or empty before one exists.
+ * The DSH title of a bot session: "Telegram-<person>-<task>". Before DSH has
+ * titled the conversation, a topic's name stands in for the task.
+ * @param person - whose chat it is: a person's name, or a group's title.
+ * @param task - what the conversation is about; empty gives "Telegram-<person>".
  * @returns the session title.
  */
-export function topicTitle(prefix, task) {
+export function sessionTitleOf(person, task) {
   const rest = typeof task === 'string' ? task.trim() : ''
-  return rest.length === 0 ? prefix : `${prefix}${TITLE_SEPARATOR}${rest}`
+  const head = `${TITLE_SOURCE}${TITLE_JOIN}${person}`
+  return rest.length === 0 ? head : `${head}${TITLE_JOIN}${rest}`
 }
 
 /**
- * Whether a title is one the bot set before any conversation title existed:
- * a bare topic name (current or earlier) or the old "TG · <name>" form.
+ * Whether a title is a placeholder the bot set before any conversation title
+ * existed, in this version's form or an earlier one: "Telegram-<person>-<topic
+ * name>", a bare topic name, or "TG · <topic name>".
  * @param title - current session title.
- * @param names - topic names the title may carry.
+ * @param names - topic names the title may carry (current and earlier).
+ * @param people - person labels the title may carry (current and earlier).
  * @returns true for a bot placeholder.
  */
-export function isPlaceholderTitle(title, names) {
-  return typeof title === 'string' && (title.startsWith(LEGACY_PREFIX) || names.includes(title))
+export function isPlaceholderTitle(title, names, people = []) {
+  if (typeof title !== 'string') return false
+  if (title.startsWith(LEGACY_PREFIX) || names.includes(title)) return true
+  return people.some((person) => names.some((name) => sessionTitleOf(person, name) === title))
 }
 
 /**
- * The conversation part of a title, without a topic-name prefix the bot added.
+ * The conversation part of a title, without the source, person or topic-name
+ * prefix the bot added in this or an earlier version.
  * @param title - current session title.
- * @param names - topic names a prefix may carry, current name first.
- * @returns the task part; empty when the title is only a prefix.
+ * @param names - topic names an earlier-form prefix may carry.
+ * @param people - person labels a prefix may carry.
+ * @returns the task part; empty when the title is only a placeholder.
  */
-export function topicTask(title, names) {
-  if (isPlaceholderTitle(title, names)) return ''
-  // Longest name first, so "Chat · 2" wins over "Chat" for "Chat · 2 · Fix".
+export function titleTask(title, names, people = []) {
+  if (isPlaceholderTitle(title, names, people)) return ''
+  // Longest label first, so "Ann-Marie" wins over "Ann".
+  for (const person of [...people].sort((a, b) => b.length - a.length)) {
+    const head = sessionTitleOf(person, '')
+    if (title === head) return ''
+    if (title.startsWith(`${head}${TITLE_JOIN}`)) return title.slice(head.length + TITLE_JOIN.length).trim()
+  }
   for (const name of [...names].sort((a, b) => b.length - a.length)) {
-    if (title.startsWith(`${name}${TITLE_SEPARATOR}`)) return title.slice(name.length + TITLE_SEPARATOR.length).trim()
+    if (title.startsWith(`${name}${LEGACY_SEPARATOR}`)) return title.slice(name.length + LEGACY_SEPARATOR.length).trim()
   }
   return title
 }
 
+/**
+ * Decide how a bot session's title should change. DSH has no title hook, so
+ * the bot rewrites titles after the fact: a missing title or a bot
+ * placeholder becomes the current placeholder through a user rename (which
+ * stops DSH's own fallback from replacing it); a generated title gets the
+ * prefix by re-appending it with the same source, so automatic titling keeps
+ * running. A title someone typed is left alone.
+ * @param current - the latest title snapshot (`{ title, source }`), if any.
+ * @param options - `person`, the label for the chat now; `names`, topic names
+ *   the title may carry, current first (empty for a chat without topics);
+ *   `people`, earlier person labels the title may carry.
+ * @returns `{ kind: 'rename' | 'append', title }`, or `{ kind: 'none' }`.
+ */
+export function plannedTitle(current, { person, names = [], people = [] }) {
+  const labels = [person, ...people.filter((label) => label !== person)]
+  const placeholder = names.length > 0 ? sessionTitleOf(person, names[0]) : undefined
+  if (current === undefined || typeof current?.title !== 'string') {
+    return placeholder === undefined ? { kind: 'none' } : { kind: 'rename', title: placeholder }
+  }
+  const title = current.title
+  if (current.source?.kind === 'user') {
+    const stale = placeholder !== undefined && title !== placeholder && isPlaceholderTitle(title, names, labels)
+    return stale ? { kind: 'rename', title: placeholder } : { kind: 'none' }
+  }
+  const task = titleTask(title, names, labels)
+  const wanted = task.length > 0 ? sessionTitleOf(person, task) : (placeholder ?? sessionTitleOf(person, ''))
+  return wanted === title ? { kind: 'none' } : { kind: 'append', title: wanted }
+}
+
 /**
  * Commands about the chat as a whole rather than one topic. When one of them
  * is sent in All, Telegram turns it into a topic of its own; the bot answers