@llblab/pi-telegram 0.20.5 → 0.20.6

package/BACKLOG.md

@@ -2,38 +2,18 @@
 
 _This backlog tracks only open release-relevant work: live promoted-follower verification, evidence-gated Telegram client/runtime follow-ups, and upstream Pi API blockers. Completed validation evidence belongs in `CHANGELOG.md`, not in this queue._
 
-## P0 — Private Guest DM Peer Attribution
+## P1 — Guest Media Live Follow-Ups
 
-Evidence: live private Guest Mode produced `[telegram|guest:<owner>]` for an owner-authored DM turn even though `guest` must identify the remote conversation peer. Code inspection confirms that private guest routing falls back to `fromPeer` whenever an owner-authored message has no usable `reply_to_message`; because `from.id` then equals the configured `allowedUserId`, the owner is mislabeled as the guest. Existing coverage protects incoming guest messages and owner replies with explicit replied-guest metadata, but does not cover owner-authored private guest messages without reply context.
+Context: 0.20.5 shipped deterministic Guest Mode file/audio delivery coverage. Post-release private-DM smoke confirmed that one local document reaches the remote conversation through `answerGuestQuery`; remaining checks validate Telegram client behavior rather than gate the implemented transport.
 
-Planned work:
-
-- [ ] Capture or minimize the raw private `guest_message` shape for owner-authored turns without reply context and identify the stable remote-peer fields supplied by Telegram (`chat` identity, username/name/id, or another explicit peer field) before choosing a resolver.
-- [ ] Centralize Guest Mode peer attribution: group turns use the group title; private non-owner turns use the sender; private owner turns use the replied guest when present and otherwise the remote private-chat peer.
-- [ ] Compare ownership by Telegram user id (`allowedUserId`), not display name or username. Never emit the configured owner as `guest`; if Telegram omits a username, fall back to the remote peer's stable name/id rather than the owner.
-- [ ] Keep `[reply|from:...]` and `[attachments|from:...]` source attribution aligned with the same resolved peer without changing the current-turn/source-context distinction.
-- [ ] Add regressions for incoming private guests, owner replies, owner-authored no-reply turns, missing usernames, username changes, and named-profile pairing identities.
-- [ ] Update the prompt-context contract/docs only after the minimized Telegram fixture establishes the actual private Guest Mode field semantics.
-
-Done when: `[telegram|guest:...]` always identifies the remote peer or group for private/group Guest Mode, never the paired owner, and reply/attachment provenance remains source-correct.
-
-## P0 — Guest Reply File And Audio Delivery
-
-Evidence: live Guest Mode accepted `telegram_attach` during an active guest turn and reported the file as queued, but delivered nothing. Code inspection confirms that guest turns use sentinel `chatId: 0`; the tool appends files to `queuedAttachments`, then the agent-end guest branch sends only `answerGuestQuery` text and returns before queued attachments or voice artifacts run. Telegram's `answerGuestQuery` accepts one `InlineQueryResult`, not ordinary `sendDocument`/`sendVoice` multipart delivery, so local artifacts require a guest-specific result plan rather than reuse of chat/thread attachment transport.
+Open work:
 
-Planned work:
+- [x] Confirm one local document in a private Guest Mode DM after extension reload.
+- [x] Confirm one synthesized paired-comment voice result in a private Guest Mode DM; Telegram delivered it to the correctly attributed remote peer without visible fallback text.
+- [ ] Confirm one local document and one synthesized voice/audio result in group Guest Mode.
+- [ ] Record a focused client/API caveat only if live behavior contradicts the one-result and staging contracts.
 
-- [x] Fail closed immediately for unsupported guest attachments until guest delivery is available; never return `Queued` when the guest agent-end path cannot consume the artifact.
-- [x] Map the current Bot API `InlineQueryResult` capabilities for document, photo, audio, and voice replies, including URL versus cached `file_id`, caption limits, supported formats, and the one-result-per-guest-query constraint. `answerGuestQuery` accepts exactly one result; local multipart uploads are not accepted there. URL results require public HTTP content (documents only PDF/ZIP, audio MP3, voice OGG/OPUS, photos JPEG up to 5 MB), while cached result variants accept Telegram `document_file_id`, `photo_file_id`, `audio_file_id`, or `voice_file_id`; media captions remain limited to 0–1024 characters after entity parsing.
-- [x] Design one guest reply planner that chooses exactly one result: text article, one cached local file/media with answer text reduced to a caption, or one cached synthesized voice/audio result. Guest tool admission rejects a second attachment before mutation. A failure before the one-shot answer may degrade to one text article; an ambiguous/failing `answerGuestQuery` call must not issue a second answer that could duplicate delivery.
-- [x] Determine an evidence-backed local-file staging path. Local media must upload through the existing leader-owned multipart transport to the paired owner's bot chat, extract the returned Telegram `file_id`, answer the guest query with the matching cached result, and delete the staging message in `finally`. The staging message can briefly appear or notify the owner; this unavoidable Bot API limitation must be documented, no external hosting is introduced, and cleanup failure must be diagnosed rather than hidden.
-- [x] Extend `answerGuestQuery` and bus forwarding from hard-coded article input to the minimal typed result union required by confirmed file/audio/voice cases.
-- [x] Route `telegram_attach`, queued outbound artifacts, and `telegram_voice` through the guest planner before the guest branch returns; never call ordinary multipart methods with sentinel `chatId: 0`.
-- [x] Preserve follower operation by routing staging and `answerGuestQuery` through the transport leader without duplicate answers or leaked staging messages.
-- [x] Add regressions for unsupported fail-closed behavior, document/image/audio/voice result construction, caption fallback, staging cleanup/failure, multiple-file rejection, guest query one-shot semantics, and text fallback after media failure.
-- [ ] Capture live private and group Guest Mode evidence for one local document and one synthesized voice/audio reply before claiming support.
-
-Done when: guest turns never silently lose queued artifacts, one supported local file or audio/voice result can be delivered through `answerGuestQuery` with clear constraints, and unsupported/multi-file cases fail visibly without sending to an unrelated thread.
+Done when: private and group Guest Mode each have direct document and voice/audio delivery evidence, or a confirmed Telegram limitation is documented.
 
 ## P1 — Compaction Status Ownership And Native Activity
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.20.6: Guest Attribution And Voice Action Hotfix
+
+- `[Voice Action Syntax]` Hidden `telegram_voice` actions now accept the intuitive paired form `<!-- telegram_voice ... -->...<!-- /telegram_voice -->` alongside inline, attribute-text, and single-comment multiline forms. The parser captures a non-empty multiline body and preserves language/rate attributes while leaving surrounding prose visible. Impact: agents can use an explicit closing tag without leaking the intended TTS payload as ordinary text.
+- `[Voice Investigation]` Removed the premature Guest Mode generate-before-answer experiment and unrelated voice-pipeline changes after live evidence identified unsupported paired markup as the confounder. After reload, voice-only paired actions delivered exactly one playable voice response with no visible fallback text in both the Aster thread and a correctly attributed private Guest Mode conversation; `telegram_attach` independently delivered the same format. Impact: standard Threaded Mode and private Guest Mode now have direct live proof on the established delivery architecture, while group Guest Mode confirmation remains explicit in `BACKLOG.md`.
+- `[Guest Attribution]` Private Guest Mode now resolves `guest` as the remote conversation peer instead of the paired owner: a non-owner sender identifies itself, while an owner-authored turn prefers the replied peer, then the private-chat identity, then non-owner caller metadata. Username falls back to the remote display name and numeric id, and an unresolved payload records redacted field-presence diagnostics without leaking the owner's identity into `[telegram|guest:...]`. Group Guest Mode continues to use the group title. Impact: the agent sees the third party it is assisting in a direct conversation, not the bot owner who invoked it.
+- `[Validation]` Added route and resolver regressions for owner-authored no-reply DMs, explicit replies, non-owner peers, username changes, missing usernames, numeric fallback, alternate paired profile ids, and owner-only unresolved input. Impact: private attribution and source-context provenance remain distinct while the paired owner can never become the guest label.
+- `[Live Evidence]` After reloading the hotfix workspace, a real owner-authored private Guest Mode invocation arrived as `[telegram|guest:mariannaelunina]` instead of the paired owner `llblab`. Impact: the repaired remote-peer attribution now has direct Telegram evidence, so the completed P0 moved out of `BACKLOG.md` and the tree is ready for the next hotfix scope.
+
 ## 0.20.5: Guest Media And Runtime Recovery Hotfix
 
 - `[Setup Persistence]` The setup prompt now applies the validated bot identity to its config store before invoking persistence, so adapters that serialize current store state cannot write an empty or stale `telegram.json` on first run. Persistence failure rolls the in-memory candidate back and remains ahead of success notifications and polling startup. Impact: setup from a missing file or `{}` durably writes `botToken`, `botId`, and `botUsername` on the first successful command for default and named profiles without reporting an unsaved connection.

package/docs/architecture.md

@@ -233,7 +233,7 @@ Assistant delivery guarantees:
 
 - Model-authored Markdown is the source of truth; the bridge does not pre-render assistant Markdown to HTML unless the operator selects `assistant.rendering: "html"` for compatibility.
 - Before native Rich Markdown delivery, the bridge normalizes known Bot-API-fragile source forms without changing visible meaning, including space-after-marker blockquotes and dollar-prefixed ticker atoms that Telegram may otherwise treat as unterminated math.
-- Prompt context blocks use compact metadata (`[tag|key:value]`) as the stable inbound contract. `[telegram...]` names the current surface only: owner/current turns use `[telegram]` or `[telegram|thread:<name>]`; guest-mode turns use `[telegram|guest:<group-title-or-peer-username-or-id>]`. Source authors for quoted/forwarded material and their files are carried by `[reply|from:<username-or-id>]`, `[forward|from:<username-or-id>]`, and `[attachments|from:<username-or-id>]`, while plain `[attachments]` remains current-turn attachments and is ordered before reply/forward/source context.
+- Prompt context blocks use compact metadata (`[tag|key:value]`) as the stable inbound contract. `[telegram...]` names the current surface only: owner/current turns use `[telegram]` or `[telegram|thread:<name>]`; guest-mode turns use `[telegram|guest:<group-title-or-peer-username-or-id>]`. In a private Guest Mode turn the paired owner's `from` identity is never the guest: an explicit replied peer wins, then the remote private-chat identity, then non-owner caller metadata; username falls back to the remote display name and numeric id. Source authors for quoted/forwarded material and their files are carried by `[reply|from:<username-or-id>]`, `[forward|from:<username-or-id>]`, and `[attachments|from:<username-or-id>]`, while plain `[attachments]` remains current-turn attachments and is ordered before reply/forward/source context.
 - Quoted rich replies use Telegram `rich_message` blocks as the prompt-context source when available, so `[reply]` context receives rendered plain text instead of raw `InputRichMessage.markdown` fallback text.
 - Long native Markdown replies are split only at Telegram Rich Message transport limits; oversized fenced code, display-math, and fully wrapped inline-formatting blocks are rewrapped per chunk so persisted Rich Markdown chunks remain structurally valid.
 - When Draft previews are enabled, streaming previews pass structurally closed assistant Markdown prefixes through to `sendRichMessageDraft` with ownership checks, voice suppression, and serialized flushes. Unclosed inline spans, links, fenced code, comments, and display-math blocks are held back until a safe boundary exists. Draft failures are recorded and the failing frame is skipped instead of degrading to raw plain-message previews, because partial Markdown can be invalid while the final message remains valid.

package/lib/outbound-markup.ts

@@ -64,6 +64,36 @@ function isTopLevelClosingFence(
   );
 }
 
+function collectPairedTelegramVoiceActionBody(
+  markdown: string,
+  bodyStart: number,
+  commentContent: string,
+): { content: string; end: number } | undefined {
+  const normalizedContent = commentContent.trim();
+  if (
+    !normalizedContent.startsWith("telegram_voice") ||
+    !isTelegramActionCommentContent(commentContent)
+  ) {
+    return undefined;
+  }
+  let offset = bodyStart;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    if (line === "<!-- /telegram_voice -->") {
+      const body = markdown.slice(bodyStart, offset).trim();
+      if (!body) return undefined;
+      return {
+        content: `${commentContent.trimEnd()}\n${body}`,
+        end: lineEnd,
+      };
+    }
+    if (line.startsWith("<!--")) return undefined;
+    offset = lineEnd;
+  }
+  return undefined;
+}
+
 function collectInlineClosedTelegramActionBody(
   markdown: string,
   bodyStart: number,
@@ -117,14 +147,19 @@ export function collectTopLevelHtmlComments(markdown: string): {
       const closesOnOpeningLine = closeIndex < lineEnd;
       const hasOnlyWhitespaceAfterClose =
         line.slice(closeColumn + 3).trim() === "";
-      const inlineBody =
+      const pairedVoiceBody =
         closesOnOpeningLine && hasOnlyWhitespaceAfterClose
+          ? collectPairedTelegramVoiceActionBody(markdown, lineEnd, content)
+          : undefined;
+      const inlineBody =
+        !pairedVoiceBody && closesOnOpeningLine && hasOnlyWhitespaceAfterClose
           ? collectInlineClosedTelegramActionBody(markdown, lineEnd, content)
           : undefined;
-      if (inlineBody) {
-        end = inlineBody.end;
+      const recoveredBody = pairedVoiceBody ?? inlineBody;
+      if (recoveredBody) {
+        end = recoveredBody.end;
         raw = markdown.slice(offset, end);
-        content = inlineBody.content;
+        content = recoveredBody.content;
       }
       comments.push({ raw, content, start: offset, end });
       offset = getMarkdownLineEnd(markdown, end);

package/lib/prompts.ts

@@ -16,7 +16,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\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload.`;
+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. For voice use a top-level HTML action: \`<!-- telegram_voice: Speak this. -->\`, multiline \`<!-- telegram_voice lang=ru\nSpeak this.\n-->\`, or paired \`<!-- telegram_voice lang=ru -->\nSpeak this.\n<!-- /telegram_voice -->\`.`;
 
 function buildTelegramHelpText(profileName?: string): string {
   const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
@@ -37,7 +37,8 @@ How to answer Telegram turns:
 Assistant-authored Telegram actions:
 - \`telegram_voice\` and \`telegram_button\` are hidden top-level HTML comments, not Pi tools.
 - Put action comments at column zero, outside code, quotes, lists, and indented examples.
-- Voice forms: \`<!-- telegram_voice text="Short summary" -->\` or \`<!-- telegram_voice: Short summary -->\`.
+- Voice forms: \`<!-- telegram_voice text="Short summary" -->\`, \`<!-- telegram_voice: Short summary -->\`, multiline \`<!-- telegram_voice lang=ru\nShort summary.\n-->\`, or paired \`<!-- telegram_voice lang=ru -->\nShort summary.\n<!-- /telegram_voice -->\`.
+- Keep the complete action at top level and include a non-empty voice payload.
 - Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
 - Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
 - Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.

package/lib/routing.ts

@@ -21,10 +21,67 @@ import * as TextGroups from "./text-groups.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import * as Turns from "./turns.ts";
 
-function formatTelegramPromptPeer(user: { id?: unknown; username?: unknown } | undefined): string | undefined {
-  if (!user) return undefined;
-  if (typeof user.username === "string" && user.username.length > 0) return user.username;
-  return typeof user.id === "number" ? String(user.id) : undefined;
+interface TelegramPromptPeerView {
+  id?: unknown;
+  username?: unknown;
+  first_name?: unknown;
+  last_name?: unknown;
+  title?: unknown;
+}
+
+function formatTelegramPromptPeer(
+  peer: TelegramPromptPeerView | undefined,
+): string | undefined {
+  if (!peer) return undefined;
+  if (typeof peer.username === "string" && peer.username.length > 0) {
+    return peer.username;
+  }
+  const displayName = [peer.first_name, peer.last_name]
+    .filter(
+      (part): part is string =>
+        typeof part === "string" && part.length > 0,
+    )
+    .join(" ");
+  if (displayName) return displayName;
+  if (typeof peer.title === "string" && peer.title.length > 0) {
+    return peer.title;
+  }
+  return typeof peer.id === "number" ? String(peer.id) : undefined;
+}
+
+function isTelegramPromptOwnerPeer(
+  peer: TelegramPromptPeerView | undefined,
+  ownerUserId: number | undefined,
+): boolean {
+  return ownerUserId !== undefined && peer?.id === ownerUserId;
+}
+
+export function resolveTelegramGuestPromptPeer(input: {
+  chatType?: string;
+  chat?: TelegramPromptPeerView;
+  from?: TelegramPromptPeerView;
+  replyFrom?: TelegramPromptPeerView;
+  guestBotCallerUser?: TelegramPromptPeerView;
+  guestBotCallerChat?: TelegramPromptPeerView;
+  ownerUserId?: number;
+}): string | undefined {
+  if (input.chatType !== "private") {
+    return formatTelegramPromptPeer(input.chat);
+  }
+  if (!isTelegramPromptOwnerPeer(input.from, input.ownerUserId)) {
+    return formatTelegramPromptPeer(input.from);
+  }
+  for (const candidate of [
+    input.replyFrom,
+    input.chat,
+    input.guestBotCallerUser,
+    input.guestBotCallerChat,
+  ]) {
+    if (isTelegramPromptOwnerPeer(candidate, input.ownerUserId)) continue;
+    const peer = formatTelegramPromptPeer(candidate);
+    if (peer) return peer;
+  }
+  return undefined;
 }
 
 function appendTelegramSourceAttachmentSection(
@@ -1812,22 +1869,43 @@ export function createTelegramInboundRouteRuntime<
     const gm = guestMessage as unknown as Record<string, unknown>;
     // Build telegram prefix with guest context
     const chatRaw = gm.chat as Record<string, unknown>;
-    const chatTitle = chatRaw?.title as string | undefined;
     const chatType = chatRaw?.type as string;
     const fromRaw = gm.from as Record<string, unknown> | undefined;
     const replyMsg = gm.reply_to_message as Record<string, unknown> | undefined;
     const replyFromRaw = replyMsg?.from as Record<string, unknown> | undefined;
-    const fromPeer = formatTelegramPromptPeer(fromRaw);
+    const guestBotCallerUser = gm.guest_bot_caller_user as
+      | Record<string, unknown>
+      | undefined;
+    const guestBotCallerChat = gm.guest_bot_caller_chat as
+      | Record<string, unknown>
+      | undefined;
+    const ownerUserId = deps.configStore.getAllowedUserId();
     const replyPeer = formatTelegramPromptPeer(replyFromRaw);
-    const fromIsOwner = fromRaw?.id === deps.configStore.getAllowedUserId();
-    const guestPeer = chatType === "private" && fromIsOwner && replyPeer
-      ? replyPeer
-      : fromPeer;
+    const guestPeer = resolveTelegramGuestPromptPeer({
+      chatType,
+      chat: chatRaw,
+      from: fromRaw,
+      replyFrom: replyFromRaw,
+      guestBotCallerUser,
+      guestBotCallerChat,
+      ownerUserId,
+    });
     const prefixParts = ["telegram"];
-    if (chatType !== "private" && chatTitle) {
-      prefixParts.push(`guest:${chatTitle}`);
-    } else if (chatType === "private" && guestPeer) {
+    if (guestPeer) {
       prefixParts.push(`guest:${guestPeer}`);
+    } else if (chatType === "private") {
+      deps.recordRuntimeEvent?.(
+        "guest",
+        new Error("Private Guest Mode remote peer could not be resolved"),
+        {
+          phase: "peer-attribution",
+          chatId: typeof chatRaw?.id === "number" ? chatRaw.id : undefined,
+          fromId: typeof fromRaw?.id === "number" ? fromRaw.id : undefined,
+          hasReplyFrom: !!replyFromRaw,
+          hasCallerUser: !!guestBotCallerUser,
+          hasCallerChat: !!guestBotCallerChat,
+        },
+      );
     }
     const telegramPrefix = `[${prefixParts.join("|")}]`;
     // Extract reply context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "private": false,
   "publishConfig": {
     "access": "public"