talon-agent 3.11.1 → 3.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.11.1",
+  "version": "3.12.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/prompts/discord.md

@@ -1,6 +1,6 @@
 ## Discord Mode
 
-In servers (guilds), you'll see messages prefixed with [Name]: — use their name naturally. In DMs, just one user.
+In servers (guilds), you'll see messages prefixed with `[Name (@handle)]:` — use their name naturally in prose, and the `@handle` when you need to address someone directly. In DMs, just one user.
 
 How replies are delivered (end_turn / send / react and what counts as a valid turn) is defined in the **Response flow** section at the end of these instructions — that contract wins over anything here.
 

package/prompts/telegram.md

@@ -1,6 +1,6 @@
 ## Telegram Mode
 
-In groups, you'll see messages prefixed with [Name]: — use their name naturally.
+In groups, you'll see messages prefixed with `[Name (@handle)]:` — use their name naturally in prose. The `@handle` is their real Telegram username: use it verbatim (with the `@`) whenever you actually need to ping someone, and especially in scheduled/cron messages, where a display name is just inert text and will not notify anyone. A sender with no username shows as `[Name]:` and simply can't be pinged.
 
 How replies are delivered (end_turn / send / react and what counts as a valid turn) is defined in the **Response flow** section at the end of these instructions — that contract wins over anything here.
 

package/src/backend/claude-sdk/handler.ts

@@ -151,7 +151,7 @@ export async function* runChatTurn(
 ): AsyncIterable<AgentEvent> {
   const config = getConfig();
 
-  const { chatId, text, senderName, isGroup } = params;
+  const { chatId, text, senderName, senderHandle, isGroup } = params;
   const session = getSession(chatId);
   const t0 = Date.now();
 
@@ -196,6 +196,7 @@ export async function* runChatTurn(
   let prompt = formatUserPrompt({
     text,
     senderName: senderName ?? "user",
+    senderHandle,
     isGroup,
     messageId: params.messageId,
   });

package/src/backend/codex/handler/message.ts

@@ -200,6 +200,7 @@ export async function handleMessage(
     chatId,
     text,
     senderName,
+    senderHandle,
     isGroup,
     messageId,
     onTextBlock,
@@ -261,6 +262,7 @@ export async function handleMessage(
   const prompt = formatUserPrompt({
     text,
     senderName: senderName ?? "user",
+    senderHandle,
     isGroup,
     messageId,
   });

package/src/backend/kilo/handler/message.ts

@@ -61,6 +61,7 @@ export async function handleMessage(
     chatId,
     text,
     senderName,
+    senderHandle,
     isGroup,
     messageId,
     onTextBlock,
@@ -96,6 +97,7 @@ export async function handleMessage(
   const prompt = formatUserPrompt({
     text,
     senderName: senderName ?? "user",
+    senderHandle,
     isGroup,
     messageId,
   });

package/src/backend/openai-agents/handler/message.ts

@@ -105,6 +105,7 @@ export async function handleMessage(
     chatId,
     text,
     senderName,
+    senderHandle,
     isGroup,
     messageId,
     onTextBlock,
@@ -143,6 +144,7 @@ export async function handleMessage(
   let prompt = formatUserPrompt({
     text,
     senderName: senderName ?? "user",
+    senderHandle,
     isGroup,
     messageId,
   });

package/src/backend/opencode/handler/message.ts

@@ -62,6 +62,7 @@ export async function handleMessage(
     chatId,
     text,
     senderName,
+    senderHandle,
     isGroup,
     messageId,
     onTextBlock,
@@ -93,6 +94,7 @@ export async function handleMessage(
   const prompt = formatUserPrompt({
     text,
     senderName: senderName ?? "user",
+    senderHandle,
     isGroup,
     messageId,
   });

package/src/backend/shared/handler-to-events.ts

@@ -82,6 +82,7 @@ export async function* handlerToEvents(
     model: params.model.id,
     text: params.text,
     senderName: params.senderName,
+    senderHandle: params.senderHandle,
     isGroup: params.isGroup,
     messageId: params.messageId,
     onStreamDelta: (accumulated) => {

package/src/backend/shared/handler-types.ts

@@ -28,6 +28,8 @@ export type QueryParams = {
   model?: string;
   text: string;
   senderName: string;
+  /** Sender's platform handle without `@` (Telegram username, Discord username). */
+  senderHandle?: string;
   isGroup?: boolean;
   /**
    * Provider message ID. Telegram is numeric; Discord snowflakes are strings.

package/src/backend/shared/prompt-format.ts

@@ -10,7 +10,7 @@
  * doesn't" drift that motivated the shared-framework refactor.
  *
  * Examples:
- *   group:  "[2026-05-15 11:01:23] [Dylan] [msg_id:2485]: actual text"
+ *   group:  "[2026-05-15 11:01:23] [Dylan (@dylanneve1)] [msg_id:2485]: actual text"
  *   DM:     "[2026-05-15 11:01:23] [msg_id:2485] actual text"
  *   DM (no msg_id): "[2026-05-15 11:01:23] actual text"
  */
@@ -25,6 +25,13 @@ export type PromptFormatInputs = {
   text: string;
   /** Display name of the sender (e.g. "Dylan"). */
   senderName: string;
+  /**
+   * Platform handle of the sender WITHOUT the leading `@` (e.g. `dylanneve1`).
+   * Rendered next to the display name in group chats so the model can address
+   * or mention someone correctly — display names are not addressable, handles
+   * are. Absent for users who have no handle set.
+   */
+  senderHandle?: string;
   /** True when the chat is a group; influences whether the `[Name]` label is included. */
   isGroup?: boolean;
   /** Provider message id (Telegram numeric, Discord snowflake string). */
@@ -47,11 +54,11 @@ export function formatUserPrompt(inputs: PromptFormatInputs): string {
     inputs.messageId !== undefined ? ` [msg_id:${inputs.messageId}]` : "";
 
   if (inputs.isGroup) {
-    return joinNonEmpty(
-      timeTag,
-      `[${inputs.senderName}]${msgIdHint}:`,
-      inputs.text,
-    );
+    const handle = inputs.senderHandle?.trim().replace(/^@+/, "");
+    const who = handle
+      ? `${inputs.senderName} (@${handle})`
+      : inputs.senderName;
+    return joinNonEmpty(timeTag, `[${who}]${msgIdHint}:`, inputs.text);
   }
 
   // DM: no [Name] label needed (Telegram already shows sender)

package/src/core/agent-runtime/capabilities.ts

@@ -51,6 +51,8 @@ export interface ChatRunParams {
   model: ModelRef;
   text: string;
   senderName: string;
+  /** Sender's platform handle without `@` (Telegram username, Discord username). */
+  senderHandle?: string;
   isGroup?: boolean;
   /** Provider message ID. Telegram is numeric; Discord snowflakes are strings. */
   messageId?: number | string;

package/src/core/background/pulse.ts

@@ -147,7 +147,10 @@ async function pulseChat(chatId: string): Promise<void> {
     .map((m) => {
       const time = formatSmartTimestamp(m.timestamp);
       const media = m.mediaType ? ` [${m.mediaType}]` : "";
-      return `[msg:${m.msgId} ${time}] ${m.senderName}${media}: ${m.text.slice(0, 200)}`;
+      const who = m.senderHandle
+        ? `${m.senderName} (@${m.senderHandle})`
+        : m.senderName;
+      return `[msg:${m.msgId} ${time}] ${who}${media}: ${m.text.slice(0, 200)}`;
     })
     .join("\n");
 

package/src/core/types.ts

@@ -214,6 +214,8 @@ export type ExecuteParams = {
   numericChatId: number;
   prompt: string;
   senderName: string;
+  /** Sender's platform handle without `@` (Telegram username, Discord username). */
+  senderHandle?: string;
   isGroup: boolean;
   /** Provider message ID. Numeric for Telegram, string snowflake for Discord. */
   messageId?: number | string;

package/src/core/weaver/weaver.ts

@@ -231,6 +231,7 @@ export class Weaver {
         model: warp.ref,
         text: params.prompt,
         senderName: params.senderName,
+        senderHandle: params.senderHandle,
         isGroup: params.isGroup,
         messageId: params.messageId,
       });

package/src/frontend/discord/handlers/delivery.ts

@@ -52,6 +52,7 @@ export async function processAndReply(p: ProcessAndReplyParams): Promise<void> {
     numericChatId: p.numericChatId,
     prompt: p.prompt,
     senderName: p.senderName,
+    senderHandle: p.senderUsername,
     isGroup: p.isGroup,
     // Use the real Discord snowflake string, not the hashed numeric.
     // The hash collides with Telegram-style 32-bit IDs and Discord's API

package/src/frontend/discord/middleware.ts

@@ -40,6 +40,9 @@ export function registerMiddleware(client: Client, config: TalonConfig): void {
     const numericMessageId = deriveNumericChatId(msg.id);
     const senderId = deriveNumericChatId(msg.author.id);
     const senderName = getSenderName(msg);
+    // Display names aren't addressable; the username is. Persist it so
+    // later readers can mention the person rather than guess a handle.
+    const senderHandle = msg.author.username;
     const replyToMsgId = msg.reference?.messageId
       ? deriveNumericChatId(msg.reference.messageId)
       : undefined;
@@ -59,6 +62,7 @@ export function registerMiddleware(client: Client, config: TalonConfig): void {
         msgId: numericMessageId,
         senderId,
         senderName,
+        senderHandle,
         text: msg.content || `(${mediaType})`,
         replyToMsgId,
         timestamp,
@@ -69,6 +73,7 @@ export function registerMiddleware(client: Client, config: TalonConfig): void {
         msgId: numericMessageId,
         senderId,
         senderName,
+        senderHandle,
         text: msg.content,
         replyToMsgId,
         timestamp,

package/src/frontend/telegram/handlers/delivery.ts

@@ -195,6 +195,7 @@ export async function processAndReply(
       numericChatId,
       prompt,
       senderName,
+      senderHandle: senderUsername,
       isGroup,
       messageId,
       source: "message",

package/src/frontend/telegram/middleware.ts

@@ -28,6 +28,10 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
   bot.on("message", (ctx, next) => {
     const chatId = String(ctx.chat.id);
     const sender = getSenderName(ctx.from);
+    // The handle is the only addressable form of a user — persist it with
+    // every row so later readers (history views, heartbeat-composed
+    // messages) can mention someone instead of guessing.
+    const senderHandle = ctx.from?.username;
     const senderId = ctx.from?.id ?? 0;
     const msgId = ctx.message.message_id;
     const replyToMsgId = ctx.message.reply_to_message?.message_id;
@@ -44,6 +48,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.text,
         replyToMsgId,
         timestamp,
@@ -53,6 +58,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.caption || "(photo)",
         replyToMsgId,
         timestamp,
@@ -64,6 +70,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.caption || `(sent ${name})`,
         replyToMsgId,
         timestamp,
@@ -74,6 +81,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: "(voice message)",
         replyToMsgId,
         timestamp,
@@ -84,6 +92,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.sticker.emoji || "(sticker)",
         replyToMsgId,
         timestamp,
@@ -95,6 +104,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.caption || "(video)",
         replyToMsgId,
         timestamp,
@@ -105,6 +115,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.caption || "(GIF)",
         replyToMsgId,
         timestamp,
@@ -117,6 +128,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: ctx.message.caption || `(audio: ${title})`,
         replyToMsgId,
         timestamp,
@@ -127,6 +139,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: "(video note)",
         replyToMsgId,
         timestamp,
@@ -137,6 +150,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: `(shared location: ${ctx.message.location.latitude}, ${ctx.message.location.longitude})`,
         replyToMsgId,
         timestamp,
@@ -152,6 +166,7 @@ export function registerMiddleware(bot: Bot, config: TalonConfig): void {
         msgId,
         senderId,
         senderName: sender,
+        senderHandle,
         text: `(shared contact: ${name})`,
         replyToMsgId,
         timestamp,

package/src/storage/db.ts

@@ -84,6 +84,11 @@ function ensureSchema(database: SqlDatabase): void {
   } catch {
     /* duplicate column or no such table — both mean nothing to do */
   }
+  try {
+    database.exec(dbSql.addHistorySenderHandleColumn);
+  } catch {
+    /* duplicate column or no such table — both mean nothing to do */
+  }
   try {
     database.exec(dbSql.addSessionsMetricsColumn);
   } catch {

package/src/storage/history.ts

@@ -142,7 +142,13 @@ function formatMessage(m: HistoryMessage): string {
     : "";
   const fileTag = m.filePath ? ` (file: ${m.filePath})` : "";
   const time = formatSmartTimestamp(m.timestamp);
-  return `[msg:${m.msgId} ${time}] ${m.senderName}${replyTag}${mediaTag}${stickerTag}${fileTag}: ${m.text}`;
+  // The handle rides along with the name: a reader deciding to mention
+  // someone (a scheduled message, a heartbeat-composed reply) has no other
+  // way to learn it, and a display name notifies nobody.
+  const who = m.senderHandle
+    ? `${m.senderName} (@${m.senderHandle})`
+    : m.senderName;
+  return `[msg:${m.msgId} ${time}] ${who}${replyTag}${mediaTag}${stickerTag}${fileTag}: ${m.text}`;
 }
 
 export function getRecentFormatted(chatId: string, limit = 20): string {
@@ -209,7 +215,7 @@ export function getKnownUsers(chatId: string): string {
   return users
     .map(
       (u) =>
-        `${u.name} (user_id: ${u.senderId}) — ${u.messageCount} msgs, last seen ${formatRelativeAge(u.lastSeen)}`,
+        `${u.name}${u.handle ? ` (@${u.handle})` : ""} (user_id: ${u.senderId}) — ${u.messageCount} msgs, last seen ${formatRelativeAge(u.lastSeen)}`,
     )
     .join("\n");
 }

package/src/storage/repositories/history-repo.ts

@@ -13,6 +13,12 @@ export type HistoryMessage = {
   msgId: number;
   senderId: number;
   senderName: string;
+  /**
+   * Platform handle without `@` (Telegram username / Discord username).
+   * Undefined for users who have none. Display names can't be mentioned;
+   * this is the addressable form a later reader needs.
+   */
+  senderHandle?: string;
   text: string;
   replyToMsgId?: number;
   timestamp: number;
@@ -27,6 +33,7 @@ type Row = {
   msg_id: number;
   sender_id: number;
   sender_name: string;
+  sender_handle: string | null;
   text: string;
   reply_to_msg_id: number | null;
   timestamp: number;
@@ -40,6 +47,7 @@ function rowToMessage(row: Row): HistoryMessage {
     msgId: row.msg_id,
     senderId: row.sender_id,
     senderName: row.sender_name,
+    senderHandle: row.sender_handle ?? undefined,
     text: row.text,
     replyToMsgId: row.reply_to_msg_id ?? undefined,
     timestamp: row.timestamp,
@@ -57,6 +65,7 @@ export function insert(chatId: string, msg: HistoryMessage): void {
       msg.msgId,
       msg.senderId,
       msg.senderName,
+      msg.senderHandle ?? null,
       msg.text,
       msg.replyToMsgId ?? null,
       msg.timestamp,
@@ -168,6 +177,8 @@ export function latestMsgId(chatId: string): number | undefined {
 export type KnownUser = {
   senderId: number;
   name: string;
+  /** Latest known platform handle without `@`, if the user has one. */
+  handle?: string;
   lastSeen: number;
   messageCount: number;
 };
@@ -181,10 +192,12 @@ export function knownUsers(chatId: string): KnownUser[] {
     last_seen: number;
     message_count: number;
     name: string;
+    handle: string | null;
   }>;
   return rows.map((r) => ({
     senderId: r.sender_id,
     name: r.name,
+    handle: r.handle ?? undefined,
     lastSeen: r.last_seen,
     messageCount: r.message_count,
   }));

package/src/storage/sql/db.sql

@@ -10,6 +10,11 @@ PRAGMA wal_checkpoint(TRUNCATE)
 -- "no such table" (fresh databases get the column via schema.sql).
 ALTER TABLE media_index ADD COLUMN content_hash TEXT
 
+-- name: addHistorySenderHandleColumn
+-- Column reconciliation for databases that shipped before sender handles
+-- were recorded. Fresh databases get the column via schema.sql.
+ALTER TABLE history_messages ADD COLUMN sender_handle TEXT
+
 -- name: addSessionsMetricsColumn
 -- Column reconciliation for databases that shipped before per-session
 -- metrics existed. Fresh databases get the column via schema.sql.

package/src/storage/sql/history.sql

@@ -3,12 +3,12 @@
 
 -- name: insert
 INSERT OR IGNORE INTO history_messages
-  (chat_id, msg_id, sender_id, sender_name, text, reply_to_msg_id,
-   timestamp, media_type, sticker_file_id, file_path)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  (chat_id, msg_id, sender_id, sender_name, sender_handle, text,
+   reply_to_msg_id, timestamp, media_type, sticker_file_id, file_path)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 
 -- name: recent
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? ORDER BY id DESC LIMIT ?
@@ -16,7 +16,7 @@ WHERE chat_id = ? ORDER BY id DESC LIMIT ?
 -- name: recentBefore
 -- Scroll-back pagination: the window of messages strictly older than a
 -- given msg_id, newest-first (the repository reverses to chronological).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND msg_id < ? ORDER BY id DESC LIMIT ?
@@ -30,7 +30,7 @@ DELETE FROM history_messages WHERE chat_id = ?
 -- name: searchFts
 -- The match param must already be a valid FTS5 expression
 -- (see history.ts ftsQuery).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ?
@@ -39,20 +39,20 @@ ORDER BY id DESC LIMIT ?
 
 -- name: bySenderName
 -- The fragment param is LIKE-escaped by the repository (backslash escape).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND lower(sender_name) LIKE ? ESCAPE '\'
 ORDER BY id DESC LIMIT ?
 
 -- name: byMsgId
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND msg_id = ? ORDER BY id DESC LIMIT 1
 
 -- name: bySenderId
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND sender_id = ? ORDER BY id DESC LIMIT ?
@@ -66,7 +66,13 @@ SELECT sender_id,
        COUNT(*) AS message_count,
        (SELECT sender_name FROM history_messages i
         WHERE i.chat_id = o.chat_id AND i.sender_id = o.sender_id
-        ORDER BY i.id DESC LIMIT 1) AS name
+        ORDER BY i.id DESC LIMIT 1) AS name,
+       -- Most recent NON-NULL handle: people set a username long after
+       -- their first message, and the newest row may predate it.
+       (SELECT i.sender_handle FROM history_messages i
+        WHERE i.chat_id = o.chat_id AND i.sender_id = o.sender_id
+          AND i.sender_handle IS NOT NULL
+        ORDER BY i.id DESC LIMIT 1) AS handle
 FROM history_messages o
 WHERE chat_id = ?
 GROUP BY sender_id

package/src/storage/sql/schema.sql

@@ -11,6 +11,10 @@ CREATE TABLE IF NOT EXISTS history_messages (
   msg_id          INTEGER NOT NULL,
   sender_id       INTEGER NOT NULL,
   sender_name     TEXT    NOT NULL,
+  -- Platform handle without `@` (Telegram username / Discord username).
+  -- Null for users who have none — display names are not addressable, so
+  -- this is what a later reader needs to actually mention someone.
+  sender_handle   TEXT,
   text            TEXT    NOT NULL,
   reply_to_msg_id INTEGER,
   timestamp       INTEGER NOT NULL,

package/src/storage/sql/statements.generated.ts

@@ -16,6 +16,10 @@ CREATE TABLE IF NOT EXISTS history_messages (
   msg_id          INTEGER NOT NULL,
   sender_id       INTEGER NOT NULL,
   sender_name     TEXT    NOT NULL,
+  -- Platform handle without \`@\` (Telegram username / Discord username).
+  -- Null for users who have none — display names are not addressable, so
+  -- this is what a later reader needs to actually mention someone.
+  sender_handle   TEXT,
   text            TEXT    NOT NULL,
   reply_to_msg_id INTEGER,
   timestamp       INTEGER NOT NULL,
@@ -293,6 +297,9 @@ export const dbSql = {
 -- attempts this on every open and swallows "duplicate column name" /
 -- "no such table" (fresh databases get the column via schema.sql).
 ALTER TABLE media_index ADD COLUMN content_hash TEXT`,
+  addHistorySenderHandleColumn: `-- Column reconciliation for databases that shipped before sender handles
+-- were recorded. Fresh databases get the column via schema.sql.
+ALTER TABLE history_messages ADD COLUMN sender_handle TEXT`,
   addSessionsMetricsColumn: `-- Column reconciliation for databases that shipped before per-session
 -- metrics existed. Fresh databases get the column via schema.sql.
 ALTER TABLE sessions ADD COLUMN metrics TEXT NOT NULL DEFAULT '{"lifetime":{"counters":{"queries":0,"toolCalls":0,"turnsWithTools":0,"apiCalls":0,"inputTokens":0,"outputTokens":0,"cacheReadTokens":0,"cacheWriteTokens":0,"failedTurns":0,"flowViolationRetries":0,"flowViolationCapExhausted":0,"trailingTextDropped":0},"latency":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsByName":{},"backend":{},"cacheHitPercent":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"toolCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0},"apiCallsPerTurn":{"count":0,"sumMs":0,"minMs":null,"maxMs":0}},"buckets":{}}'`,
@@ -326,16 +333,16 @@ WHERE chat_id = ? AND status IN (/* statuses */)`,
 
 export const historySql = {
   insert: `INSERT OR IGNORE INTO history_messages
-  (chat_id, msg_id, sender_id, sender_name, text, reply_to_msg_id,
-   timestamp, media_type, sticker_file_id, file_path)
-VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-  recent: `SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+  (chat_id, msg_id, sender_id, sender_name, sender_handle, text,
+   reply_to_msg_id, timestamp, media_type, sticker_file_id, file_path)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  recent: `SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? ORDER BY id DESC LIMIT ?`,
   recentBefore: `-- Scroll-back pagination: the window of messages strictly older than a
 -- given msg_id, newest-first (the repository reverses to chronological).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND msg_id < ? ORDER BY id DESC LIMIT ?`,
@@ -343,23 +350,23 @@ WHERE chat_id = ? AND msg_id < ? ORDER BY id DESC LIMIT ?`,
   deleteChat: `DELETE FROM history_messages WHERE chat_id = ?`,
   searchFts: `-- The match param must already be a valid FTS5 expression
 -- (see history.ts ftsQuery).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ?
   AND id IN (SELECT rowid FROM history_fts WHERE history_fts MATCH ?)
 ORDER BY id DESC LIMIT ?`,
   bySenderName: `-- The fragment param is LIKE-escaped by the repository (backslash escape).
-SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND lower(sender_name) LIKE ? ESCAPE '\\'
 ORDER BY id DESC LIMIT ?`,
-  byMsgId: `SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+  byMsgId: `SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND msg_id = ? ORDER BY id DESC LIMIT 1`,
-  bySenderId: `SELECT msg_id, sender_id, sender_name, text, reply_to_msg_id,
+  bySenderId: `SELECT msg_id, sender_id, sender_name, sender_handle, text, reply_to_msg_id,
        timestamp, media_type, sticker_file_id, file_path
 FROM history_messages
 WHERE chat_id = ? AND sender_id = ? ORDER BY id DESC LIMIT ?`,
@@ -369,7 +376,13 @@ WHERE chat_id = ? AND sender_id = ? ORDER BY id DESC LIMIT ?`,
        COUNT(*) AS message_count,
        (SELECT sender_name FROM history_messages i
         WHERE i.chat_id = o.chat_id AND i.sender_id = o.sender_id
-        ORDER BY i.id DESC LIMIT 1) AS name
+        ORDER BY i.id DESC LIMIT 1) AS name,
+       -- Most recent NON-NULL handle: people set a username long after
+       -- their first message, and the newest row may predate it.
+       (SELECT i.sender_handle FROM history_messages i
+        WHERE i.chat_id = o.chat_id AND i.sender_id = o.sender_id
+          AND i.sender_handle IS NOT NULL
+        ORDER BY i.id DESC LIMIT 1) AS handle
 FROM history_messages o
 WHERE chat_id = ?
 GROUP BY sender_id