@soffits/dsh-telegram-bot 0.4.2 → 0.4.4

package/MAINTAINING.md

@@ -7,7 +7,7 @@ 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.

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-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.
 - 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.
@@ -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.
 
@@ -146,7 +149,7 @@ Scripts, scheduled jobs, other plugins and agents can post into a topic by its n
 
 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.2",
+  "version": "0.4.4",
   "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'
@@ -41,7 +42,7 @@ import { createUpdateAdmission } from './update-ledger.js'
 import { publishStatus } from './status.js'
 import { messageAnswer, turnAnswer } from './final-text.js'
 import { createOutbox } from './outbox.js'
-import { 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'
@@ -240,6 +241,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 +1741,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 +1931,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`)
@@ -2800,6 +2807,25 @@ export function apply(ctx, config) {
     await sendPlain(chat.chatId, tr('↪️ Sent to the running turn.', '↪️ Отправлено в текущий ход.'), signal, chat.threadId)
   }
 
+  /**
+   * Bring a topic's archived session back before a message from the topic
+   * starts a turn in it. DSH admits a prompt into an archived session but
+   * rejects its every model step (the archived-session gate), so without this
+   * the turn would end as `blocked` and the message would get no answer.
+   * @param chat - chat bridge state.
+   */
+  async function unarchiveForTopic(chat) {
+    const registry = ctx.get('workspaceRegistry')
+    const sessionId = chat.sessionId
+    if (typeof sessionId !== 'string' || registry?.archivedSessionIds?.includes(sessionId) !== true) return
+    if (typeof registry.unarchiveSession !== 'function') {
+      warn(`session ${sessionId} is archived and this DSH cannot unarchive it; the message will not be answered`)
+      return
+    }
+    await registry.unarchiveSession(sessionId)
+    info(`unarchived session ${sessionId} for a message in its topic`)
+  }
+
   /**
    * Show the turn's placeholders and hand its prompt to DSH.
    * @param chat - chat bridge state.
@@ -2818,6 +2844,7 @@ export function apply(ctx, config) {
     chat.lastEdit = Date.now()
     try {
       const agent = await ensureAgent(chat)
+      await unarchiveForTopic(chat)
       let admitted = false
       if (nativeText) {
         admitted = admitText(ctx, { sessionId: chat.sessionId, chatId: chat.chatId, messageId, text }, signal)
@@ -3418,48 +3445,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
+  }
+
   /**
-   * The topic a session is bound to.
+   * 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}`
+  }
+
+  /**
+   * 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)
@@ -3467,28 +3595,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()
 
@@ -3504,10 +3688,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'
@@ -4931,12 +5116,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,
@@ -6005,6 +6191,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` +

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/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/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