@llblab/pi-telegram 0.19.3 → 0.20.1

package/lib/locks.ts

@@ -12,20 +12,38 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname } from "node:path";
+import { resolveTelegramLocksPath } from "./paths.ts";
 
 export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 5_000;
+const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
+const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
 
-function getAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
+function getLocksPath(): string {
+  return resolveTelegramLocksPath();
 }
 
-function getLocksPath(): string {
-  return join(getAgentDir(), "locks.json");
+/**
+ * Resolve the scoped lock key for the active Telegram profile.
+ * Default profile → @llblab/pi-telegram
+ * Named profile → @llblab/pi-telegram:<name>
+ */
+export function resolveTelegramLockKey(activeProfile?: string): string {
+  if (activeProfile) return `${TELEGRAM_LOCK_KEY}:${activeProfile}`;
+  return TELEGRAM_LOCK_KEY;
+}
+
+export interface TelegramActiveProfileGetter {
+  getActiveProfileName: () => string | undefined;
+}
+
+export function createTelegramLockKeyResolver(
+  activeProfile: TelegramActiveProfileGetter,
+): () => string {
+  return function getTelegramLockKey() {
+    return resolveTelegramLockKey(activeProfile.getActiveProfileName());
+  };
 }
 
 export interface TelegramLockEntry {
@@ -81,7 +99,7 @@ export interface TelegramLockContextStore<
 }
 
 export interface TelegramLockRuntimeOptions {
-  key?: string;
+  key?: string | (() => string | undefined);
   locksPath?: string;
   pid?: number;
   isProcessAlive?: (pid: number) => boolean;
@@ -104,23 +122,46 @@ export function readLocks(path = getLocksPath()): Record<string, unknown> {
   }
 }
 
+function isRetryableLockWriteError(error: unknown): boolean {
+  const code = (error as { code?: unknown })?.code;
+  return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+
+function sleepSync(ms: number): void {
+  const buffer = new SharedArrayBuffer(4);
+  Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+
 export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
-  const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    renameSync(tempPath, path);
-  } catch (error) {
+  const payload = `${JSON.stringify(locks, null, 2)}\n`;
+  let lastError: unknown;
+  for (let attempt = 0; attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+    const tempPath = `${path}.${process.pid}.${Date.now()}.${attempt}.tmp`;
     try {
-      unlinkSync(tempPath);
-    } catch {
-      /* best effort */
+      writeFileSync(tempPath, payload, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+      renameSync(tempPath, path);
+      return;
+    } catch (error) {
+      lastError = error;
+      try {
+        unlinkSync(tempPath);
+      } catch {
+        /* best effort */
+      }
+      if (
+        !isRetryableLockWriteError(error) ||
+        attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
+      ) {
+        throw error;
+      }
+      sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
     }
-    throw error;
   }
+  throw lastError;
 }
 
 export function parseTelegramLockEntry(
@@ -238,10 +279,18 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     nowMs: getNowMs(),
     staleHeartbeatMs: options.staleHeartbeatMs,
   });
-  const readLock = () => parseTelegramLockEntry(readLocks(locksPath)[key]);
+  const resolveEffectiveKey = (): string => {
+    if (typeof key === "function") return key() || TELEGRAM_LOCK_KEY;
+    return key;
+  };
+  const readLock = () => {
+    const effectiveKey = resolveEffectiveKey();
+    return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+  };
   const writeLock = (lock: TelegramLockEntry) => {
+    const effectiveKey = resolveEffectiveKey();
     const locks = readLocks(locksPath);
-    locks[key] = lock;
+    locks[effectiveKey] = lock;
     writeLocks(locksPath, locks);
   };
   return {
@@ -262,7 +311,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
       const state = getLockState(readLock(), pid, isAlive, stateOptions());
       if (state.kind === "active-here" || state.kind === "stale") {
         const locks = readLocks(locksPath);
-        delete locks[key];
+        delete locks[resolveEffectiveKey()];
         writeLocks(locksPath, locks);
       }
       return state;
@@ -411,7 +460,11 @@ export function createTelegramLockedPollingRuntime<
     const owner = snapshotLockContext(ctx);
     stopOwnershipWatcher();
     ownershipInterval = setInterval(() => {
-      if (deps.lock.refresh(owner)) return;
+      try {
+        if (deps.lock.refresh(owner)) return;
+      } catch (error) {
+        deps.recordRuntimeEvent?.("lock", error, { phase: "refresh" });
+      }
       stopAfterOwnershipLoss();
     }, ownershipCheckMs);
     ownershipInterval.unref?.();

package/lib/{runtime-log.ts → logs.ts}

@@ -1,7 +1,7 @@
 /**
- * Telegram runtime JSONL diagnostics log
+ * Telegram diagnostics logs
  * Zones: telegram diagnostics, filesystem, session observability
- * Owns session-local append-only runtime evidence for debugging without becoming routing state
+ * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
  */
 
 import {
@@ -12,8 +12,13 @@ import {
   writeFileSync,
   appendFile,
 } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname } from "node:path";
+import {
+  resolveAgentDir,
+  resolveTelegramProfileTempFilePath,
+} from "./paths.ts";
+
+export type TelegramLogPathInput = string | (() => string);
 
 export interface TelegramRuntimeJsonlEvent {
   at: number;
@@ -23,14 +28,14 @@ export interface TelegramRuntimeJsonlEvent {
 }
 
 export interface TelegramRuntimeJsonlLogOptions {
-  path?: string;
-  previousPath?: string;
+  path?: TelegramLogPathInput;
+  previousPath?: TelegramLogPathInput;
   maxBytes?: number;
   getNowMs?: () => number;
 }
 
 export interface TelegramRuntimeJsonlLog {
-  path: string;
+  getPath: () => string;
   reset: (reason: string, scope?: Record<string, unknown>) => void;
   resetIfScopeChanged: (
     scopeKey: string,
@@ -42,21 +47,36 @@ export interface TelegramRuntimeJsonlLog {
 
 const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
 
-function getAgentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
+export function getTelegramRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "logs",
+    "jsonl",
+    agentDir,
+    profileName,
+  );
 }
 
-export function getTelegramRuntimeLogPath(agentDir = getAgentDir()): string {
-  return join(agentDir, "tmp", "telegram", "logs.jsonl");
+export function getTelegramPreviousRuntimeLogPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "logs",
+    "previous.jsonl",
+    agentDir,
+    profileName,
+  );
 }
 
 function safeJsonLine(value: unknown): string {
   return JSON.stringify(value, (_key, item) => {
     if (item instanceof Error) return item.message;
     if (typeof item === "bigint") return item.toString();
-    if (typeof item === "function" || typeof item === "symbol") return undefined;
+    if (typeof item === "function" || typeof item === "symbol")
+      return undefined;
     return item;
   });
 }
@@ -64,27 +84,35 @@ function safeJsonLine(value: unknown): string {
 export function createTelegramRuntimeJsonlLog(
   options: TelegramRuntimeJsonlLogOptions = {},
 ): TelegramRuntimeJsonlLog {
-  const path = options.path ?? getTelegramRuntimeLogPath();
-  const previousPath =
-    options.previousPath ?? path.replace(/\.jsonl$/u, ".previous.jsonl");
+  const resolvePath = () =>
+    typeof options.path === "function"
+      ? options.path()
+      : (options.path ?? getTelegramRuntimeLogPath());
+  const resolvePreviousPath = () => {
+    if (typeof options.previousPath === "function") return options.previousPath();
+    if (options.previousPath) return options.previousPath;
+    return resolvePath().replace(/\.jsonl$/u, ".previous.jsonl");
+  };
   const maxBytes = options.maxBytes ?? DEFAULT_MAX_LOG_BYTES;
   const getNowMs = options.getNowMs ?? Date.now;
-  let scopeKey: string | undefined;
+  const scopeKeys = new Map<string, string | undefined>();
   let pending: Promise<void> = Promise.resolve();
 
-  const ensureParent = () => {
+  const ensureParent = (path: string) => {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   };
 
-  const preserveCurrentLog = () => {
+  const preserveCurrentLog = (path: string, previousPath: string) => {
     if (!existsSync(path)) return;
     mkdirSync(dirname(previousPath), { recursive: true, mode: 0o700 });
     copyFileSync(path, previousPath);
   };
 
   const writeReset = (reason: string, scope?: Record<string, unknown>) => {
-    ensureParent();
-    preserveCurrentLog();
+    const path = resolvePath();
+    const previousPath = resolvePreviousPath();
+    ensureParent(path);
+    preserveCurrentLog(path, previousPath);
     writeFileSync(
       path,
       safeJsonLine({
@@ -102,7 +130,8 @@ export function createTelegramRuntimeJsonlLog(
     pending = pending
       .catch(() => undefined)
       .then(async () => {
-        ensureParent();
+        const path = resolvePath();
+        ensureParent(path);
         if (existsSync(path) && statSync(path).size > maxBytes) {
           writeReset("max-bytes", { maxBytes });
         }
@@ -116,9 +145,10 @@ export function createTelegramRuntimeJsonlLog(
   };
 
   return {
-    path,
+    getPath: resolvePath,
     reset(reason, scope) {
-      scopeKey = scope ? safeJsonLine(scope) : undefined;
+      const path = resolvePath();
+      scopeKeys.set(path, scope ? safeJsonLine(scope) : undefined);
       try {
         writeReset(reason, scope);
       } catch {
@@ -126,8 +156,9 @@ export function createTelegramRuntimeJsonlLog(
       }
     },
     resetIfScopeChanged(nextScopeKey, reason, scope) {
-      if (scopeKey === nextScopeKey) return;
-      scopeKey = nextScopeKey;
+      const path = resolvePath();
+      if (scopeKeys.get(path) === nextScopeKey) return;
+      scopeKeys.set(path, nextScopeKey);
       try {
         writeReset(reason, scope);
       } catch {

package/lib/media.ts

@@ -33,11 +33,36 @@ export interface TelegramRichMessage {
   blocks?: unknown[];
 }
 
+export interface TelegramMessageUser {
+  id?: number;
+  is_bot?: boolean;
+  first_name?: string;
+  last_name?: string;
+  username?: string;
+}
+
+export interface TelegramMessageForwardOrigin {
+  type?: string;
+  sender_user?: TelegramMessageUser;
+  sender_user_name?: string;
+  sender_chat?: { title?: string; username?: string; id?: number };
+  chat?: { title?: string; username?: string; id?: number };
+  author_signature?: string;
+}
+
 export interface TelegramReplyToMessage {
   message_id?: number;
+  from?: TelegramMessageUser;
   text?: string;
   caption?: string;
   rich_message?: TelegramRichMessage;
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  video?: TelegramVideo;
+  audio?: TelegramAudio;
+  voice?: TelegramVoice;
+  animation?: TelegramAnimation;
+  sticker?: TelegramSticker;
 }
 
 export interface TelegramSticker {
@@ -46,6 +71,10 @@ export interface TelegramSticker {
 
 export interface TelegramMediaMessage {
   message_id: number;
+  from?: TelegramMessageUser;
+  forward_origin?: TelegramMessageForwardOrigin;
+  forward_from?: TelegramMessageUser;
+  forward_sender_name?: string;
   text?: string;
   caption?: string;
   rich_message?: TelegramRichMessage;
@@ -277,6 +306,39 @@ function truncateTelegramReplyContextText(text: string): string {
   return `${text.slice(0, TELEGRAM_REPLY_CONTEXT_MAX_LENGTH).trimEnd()}…`;
 }
 
+function formatTelegramUser(user: TelegramMessageUser | undefined): string | undefined {
+  if (!user) return undefined;
+  if (user.username) return user.username;
+  if (typeof user.id === "number") return String(user.id);
+  const name = [user.first_name, user.last_name].filter(Boolean).join(" ").trim();
+  return name || undefined;
+}
+
+function formatTelegramForwardOriginIdentifier(
+  message: TelegramMediaMessage,
+): string | undefined {
+  const origin = message.forward_origin;
+  const user = origin?.sender_user ?? message.forward_from;
+  if (user?.username) return user.username;
+  if (typeof user?.id === "number") return String(user.id);
+  const chat = origin?.sender_chat ?? origin?.chat;
+  if (chat?.username) return chat.username;
+  if (typeof chat?.id === "number") return String(chat.id);
+  return origin?.sender_user_name ?? message.forward_sender_name;
+}
+
+export function extractTelegramForwardContextText(
+  message: TelegramMediaMessage,
+  allowedUserId?: number,
+): string {
+  const originUser = message.forward_origin?.sender_user ?? message.forward_from;
+  const isOwnerOrigin =
+    typeof allowedUserId === "number" && originUser?.id === allowedUserId;
+  const origin = formatTelegramForwardOriginIdentifier(message);
+  if (!origin || isOwnerOrigin) return "";
+  return `from: ${origin}`;
+}
+
 export function extractTelegramReplyContextText(
   message: TelegramMediaMessage,
 ): string {
@@ -289,13 +351,44 @@ export function extractTelegramReplyContextText(
   return quoted ? truncateTelegramReplyContextText(quoted) : "";
 }
 
+export function buildTelegramReplyContextBlock(
+  message: TelegramMediaMessage,
+  replyFiles: Pick<DownloadedTelegramFile, "path">[] = [],
+): string {
+  const from = formatTelegramUser(message.reply_to_message?.from);
+  const header = from ? `[reply|from:${from}]` : "[reply]";
+  const text = extractTelegramReplyContextText(message);
+  const dirs = [...new Set(replyFiles.map((file) => dirname(file.path)))];
+  const sameDir = dirs.length === 1;
+  const attachmentHeader = sameDir
+    ? `[attachments${from ? `|from:${from}` : ""}] ${dirs[0]}`
+    : `[attachments${from ? `|from:${from}` : ""}]`;
+  const fileLines = sameDir
+    ? replyFiles.map((file) => `- /${basename(file.path)}`)
+    : replyFiles.map((file) => `- ${file.path}`);
+  const replyBlock = text ? `${header} ${text}` : header;
+  if (fileLines.length > 0) {
+    return `${replyBlock}\n\n${attachmentHeader}\n${fileLines.join("\n")}`;
+  }
+  if (text) return replyBlock;
+  return "";
+}
+
 export function appendTelegramReplyContext(
   text: string,
   replyContext: string,
 ): string {
   if (!replyContext) return text;
-  const replyBlock = `[reply] ${replyContext}`;
-  return text ? `${text}\n\n${replyBlock}` : `_\n\n${replyBlock}`;
+  return text ? `${text}\n\n${replyContext}` : `_\n\n${replyContext}`;
+}
+
+export function appendTelegramForwardContext(
+  text: string,
+  forwardContext: string,
+): string {
+  if (!forwardContext) return text;
+  const forwardBlock = `[forward|${forwardContext.replace(/:\s+/g, ":")}]`;
+  return text ? `\n\n${forwardBlock} ${text}` : `\n\n${forwardBlock}`;
 }
 
 export function extractTelegramMessagePromptText(
@@ -303,7 +396,7 @@ export function extractTelegramMessagePromptText(
 ): string {
   return appendTelegramReplyContext(
     extractTelegramMessageText(message),
-    extractTelegramReplyContextText(message),
+    buildTelegramReplyContextBlock(message),
   );
 }
 
@@ -321,7 +414,7 @@ export function extractTelegramMessagesPromptText(
   if (!firstMessage) return text;
   return appendTelegramReplyContext(
     text,
-    extractTelegramReplyContextText(firstMessage),
+    buildTelegramReplyContextBlock(firstMessage),
   );
 }
 

package/lib/outbound-buttons.ts

@@ -192,7 +192,7 @@ export function createTelegramButtonPromptTurn(options: {
     replyToMessageId: options.replyToMessageId,
     sourceMessageIds: [options.replyToMessageId],
     queueOrder: options.queueOrder,
-    queueLane: "default",
+    queueLane: "priority",
     laneOrder: options.queueOrder,
     queuedAttachments: [],
     content: [{ type: "text", text: prompt }],

package/lib/outbound.ts

@@ -6,8 +6,9 @@
 
 import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
+
+import { resolveTelegramTempDir } from "./paths.ts";
 
 import {
   planTelegramButtonReply,
@@ -66,8 +67,7 @@ export function recordTelegramRuntimeEvent(
 }
 
 export type TelegramOutboundCommandTemplateConfig =
-  | string
-  | CommandTemplateObjectConfig;
+  string | CommandTemplateObjectConfig;
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
   type?: string;
   match?: string | string[];
@@ -448,10 +448,7 @@ function getVoiceReplyTemplateValues(
 }
 
 function getDefaultTelegramVoiceTempDir(): string {
-  const agentDir = process.env.PI_CODING_AGENT_DIR
-    ? resolve(process.env.PI_CODING_AGENT_DIR)
-    : join(homedir(), ".pi", "agent");
-  return join(agentDir, "tmp", "telegram");
+  return resolveTelegramTempDir();
 }
 
 async function generateTelegramVoiceReplyFileWithHandler(

package/lib/paths.ts

@@ -0,0 +1,77 @@
+/**
+ * Telegram bridge path resolution for Pi-compatible runtimes
+ * Zones: telemetry paths, filesystem, runtime identity
+ * Owns agent-dir detection and extension-local path derivation
+ *
+ * This domain is pure/path-only: it resolves directories and file paths
+ * from environment and runtime identity. It does not read config, manage
+ * state, or import broader Telegram domains.
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface TelegramAgentDirResolutionInput {
+  env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;
+  execPath?: string;
+  argv?: readonly string[];
+}
+
+/**
+ * Resolve the agent data directory for the current Pi-compatible runtime.
+ *
+ * Precedence:
+ * 1. `PI_CODING_AGENT_DIR` env variable, when explicitly set.
+ * 2. Detect Pi-compatible runtime identity from the executable or argv[1]
+ *    (e.g. OMP vs standard Pi agent).
+ * 3. Fallback: `~/.pi/agent`.
+ */
+export function resolveAgentDir(
+  input: TelegramAgentDirResolutionInput = {},
+): string {
+  const env = input.env ?? process.env;
+  if (env.PI_CODING_AGENT_DIR) return resolve(env.PI_CODING_AGENT_DIR);
+  const execPath = input.execPath ?? process.execPath;
+  const argv = input.argv ?? process.argv;
+  const execBasename = execPath.toLowerCase().split(/[\\/]/u).pop() ?? "";
+  const argv1Last = (argv[1] ?? "").toLowerCase().split(/[\\/]/u).pop() ?? "";
+  if (execBasename.startsWith("omp") || argv1Last.startsWith("omp")) {
+    return join(homedir(), ".omp", "agent");
+  }
+  return join(homedir(), ".pi", "agent");
+}
+
+/** Telegram bridge configuration file (<agentDir>/telegram.json). */
+export function resolveTelegramConfigPath(): string {
+  return join(resolveAgentDir(), "telegram.json");
+}
+
+/** Telegram singleton lock file (<agentDir>/locks.json). */
+export function resolveTelegramLocksPath(): string {
+  return join(resolveAgentDir(), "locks.json");
+}
+
+/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
+  return join(agentDir, "tmp", "telegram");
+}
+
+export function getTelegramProfilePathSuffix(profileName?: string): string {
+  return profileName ? `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}` : "";
+}
+
+export function resolveTelegramProfileTempFilePath(
+  baseName: string,
+  extension: string,
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return join(
+    resolveTelegramTempDir(agentDir),
+    `${baseName}${getTelegramProfilePathSuffix(profileName)}.${extension}`,
+  );
+}
+
+/** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
+export function resolveTelegramRuntimeLogPath(): string {
+  return resolveTelegramProfileTempFilePath("logs", "jsonl");
+}

package/lib/prompt-templates.ts

@@ -116,11 +116,13 @@ export function getTelegramPromptTemplateCommands(
     if (!telegramCommand) continue;
     if (reservedNames.has(telegramCommand)) continue;
     if (seen.has(telegramCommand)) continue;
+    const sourcePath = command.sourceInfo?.path;
+    if (!sourcePath) continue;
     seen.add(telegramCommand);
     promptCommands.push({
       command: telegramCommand,
       description: command.description,
-      path: command.sourceInfo.path,
+      path: sourcePath,
     });
   }
   return promptCommands.sort((a, b) => a.command.localeCompare(b.command));

package/lib/prompts.ts

@@ -15,7 +15,7 @@ Telegram bridge available. Do not use it from local/TUI prompts unless explicitl
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`.`;
+Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload.`;
 
 const TELEGRAM_HELP_TEXT = `--- TELEGRAM BRIDGE HELP ---
 

package/lib/queue.ts

@@ -273,6 +273,37 @@ export function appendTelegramQueueItem<
   return [...items, item];
 }
 
+function getTelegramPromptTextSignature(item: PendingTelegramTurn): string {
+  return item.content
+    .filter((entry): entry is TelegramPromptTextContent => entry.type === "text")
+    .map((entry) => entry.text)
+    .join("\n");
+}
+
+function isDuplicateTelegramPromptTurn(
+  left: PendingTelegramTurn,
+  right: PendingTelegramTurn,
+): boolean {
+  return (
+    left.chatId === right.chatId &&
+    left.target?.threadId === right.target?.threadId &&
+    left.replyToMessageId === right.replyToMessageId &&
+    getTelegramPromptTextSignature(left) === getTelegramPromptTextSignature(right)
+  );
+}
+
+export function appendTelegramPromptTurnOnce<TContext = unknown>(
+  items: TelegramQueueItem<TContext>[],
+  turn: PendingTelegramTurn,
+): { items: TelegramQueueItem<TContext>[]; appended: boolean } {
+  assertTelegramQueueItemAdmissionValid(turn);
+  const duplicate = items.some(
+    (item) => isPendingTelegramTurn(item) && isDuplicateTelegramPromptTurn(item, turn),
+  );
+  if (duplicate) return { items, appended: false };
+  return { items: [...items, turn], appended: true };
+}
+
 export function compareTelegramQueueItems<TContext = unknown>(
   left: TelegramQueueItem<TContext>,
   right: TelegramQueueItem<TContext>,
@@ -2051,7 +2082,7 @@ export function executeTelegramQueueDispatchPlan<TContext = unknown>(
   }
   deps.onPromptDispatchStart(plan.item.chatId);
   try {
-    deps.sendUserMessage(plan.item.content, TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY);
+    deps.sendUserMessage(plan.item.content);
   } catch (error) {
     const message = getTelegramQueueErrorMessage(error);
     deps.onPromptDispatchFailure(message);