@llblab/pi-telegram 0.27.1 → 0.27.2

package/AGENTS.md

@@ -115,7 +115,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - Use `.agents/skills/telegram-bot/SKILL.md` and its `api.md` reference for native Rich Markdown, Bot API topic transport, and transport capability checks
 - Formula guidance belongs in the Telegram-turn prompt contract: use `$...$` for inline math and `$$...$$` for block math; backticks intentionally render formulas as literal code
 - Real code blocks must stay literal and escaped
-- `telegram_attach` is the canonical outbound file-delivery path for Telegram-originated requests; outside active Telegram turns it may send immediately to the paired/default chat, a registered follower's assigned target, or explicit `chat_id` plus optional `thread_id` for explicit local/TUI delivery requests only when this Pi instance owns `/telegram-connect` or is registered with the Threaded Mode multi-instance bus. `telegram_message` is the first-class direct Telegram Markdown text tool for local/TUI prompts and follows the same ownership-or-bus-registration gate; neither direct tool replaces normal active-turn replies. It reuses top-level `telegram_button` comments for inline buttons; buttons must be attached to a text message, never sent as standalone actions
+- `telegram_attach` is the canonical outbound file-delivery path for Telegram-originated requests; outside active Telegram turns it may send immediately to the paired/default chat, a registered follower's assigned target, or explicit `chat_id` plus optional `thread_id` for explicit local/TUI delivery requests only when this Pi instance owns `/telegram-connect` or is registered with the Threaded Mode multi-instance bus. `telegram_message` is the first-class direct Telegram Markdown text tool and follows the same ownership-or-bus-registration gate; during an active Telegram turn it rejects omitted targeting and the exact active target while allowing an explicit different chat/thread target, so it cannot replace the normal current-turn reply but can satisfy requested cross-target delivery. It reuses top-level `telegram_button` comments for inline buttons; buttons must be attached to a text message, never sent as standalone actions
 - Telegram prompt guidance is layered, authority-aware, and context-frugal: only a current direct owner or registered follower exposes `telegram_attach`, `telegram_message`, `telegram_help`, their active-tool prompt metadata, and the compact bridge suffix. Successful disconnect or transport-authority loss removes those surfaces for subsequent requests while preserving every foreign tool; reconnect/recovery restores only the pi-telegram tool subset that was active before suspension. Telegram-originated turns receive only the minimal per-turn contract, and detailed voice/button/direct-delivery/Threaded Mode/formatting/debug guidance belongs in `telegram_help` instead of every prompt.
 - Telegram inbound prompt topology keeps current user material contiguous: `[outputs]` produced from current attachments follows `[attachments]` immediately, then independent `[reply]` or forwarded-source context follows the complete current-user block. Forwarded Rich Message media belongs under source-attributed `[attachments|from:<identity>]` immediately after its `[forward|from:<identity>]` block and remains available as model image content. Do not place source context between an attachment and its transcription or handler output.
 - Forward-annotation grouping distinguishes two semantic layers: the forward owns its source text/caption/media, while an optional separate owner-authored annotation normally arrives immediately before it. Use a bounded one-second candidate window in both transport orders: ordinary short human text may wait for an adjacent same-sender/chat/thread forward, and a forwarded message—including a media-only forward with no source caption—may wait for one adjacent owner annotation. A matching opposite-kind message flushes immediately; same-kind messages, commands, bots, ordinary non-forward captions, media groups, target/sender mismatches, reversed ids, and distant ids stay separate. Preserve the candidate across session replacement and follower forwarding without weakening exact routing-generation authority.

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.27.2: Target-Aware Direct Message Guard
+
+- `Direct Message Guard`: `telegram_message` now rejects implicit delivery and an explicit target equal to the active Telegram turn, leaving the ordinary final-reply path as the sole current-target response. An explicit different chat/thread target remains allowed for user-requested cross-target delivery, while local/TUI direct sends and automatic Proactive Push remain unchanged. Impact: accidental duplicate replies are prevented without breaking legitimate inter-thread messaging.
+- `Boundary Coverage`: Focused regressions distinguish implicit, same-target, and different-thread direct messaging while retaining the existing active-turn attachment queue contract. Impact: future duplicate protection cannot silently collapse all direct delivery into a coarse active-turn ban.
+
 ## 0.27.1: Humanized Tool Labels Hotfix
 
 - `Tool Labels`: Tool activity roots now replace snake-case underscores with spaces and capitalize every resulting word while preserving recognizable uppercase repeated-letter prefixes per word (`telegram_attach` → `Telegram Attach`, `ff_find_items` → `FF Find Items`). Impact: Rich tool disclosures and their HTML fallback present multi-word tool names as user-facing labels instead of code identifiers.

package/docs/outbound.md

@@ -2,7 +2,7 @@
 
 `pi-telegram` maps hidden assistant-authored HTML comments to Telegram-native outbound actions.
 
-Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden top-level blocks, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. If neither condition is true, the tools fail instead of bypassing singleton ownership. Explicit thread delivery uses `chat_id` plus `thread_id`; registered followers default to their assigned thread target. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded top-level `telegram_button` comments become buttons attached to that text message.
+Normal Telegram-turn replies are intentionally prompt-driven: the agent writes Markdown plus small hidden top-level blocks, and the bridge performs transport after `agent_end`. `telegram_voice` and `telegram_button` are not Pi tools. For local/TUI-initiated work where the user explicitly asks to send something to Telegram, the bridge also exposes direct tools: `telegram_message` for Markdown text and `telegram_attach` for file delivery when no Telegram turn is active. In classic mode, direct local/TUI delivery requires this Pi instance to own `/telegram-connect`; in Threaded Mode, a registered follower may route direct-tool sends through the leader-owned bus transport. During an active Telegram turn, `telegram_message` rejects an implicit or same-turn target so ordinary final delivery remains the sole current-target response, but an explicit different chat/thread target remains available for requested cross-target delivery. If transport authority is absent, the tools fail instead of bypassing singleton ownership. Explicit thread delivery uses `chat_id` plus `thread_id`; registered followers default to their assigned thread target. Outbound behavior combines assistant prompt markup, text command-template handlers, registered voice synthesis providers, generated artifacts, direct Telegram tools, and reply delivery. Direct `telegram_message` text is planned through the same reply markup path, so embedded top-level `telegram_button` comments become buttons attached to that text message.
 
 Text handlers use the portable [Command Template Standard](./command-templates.md). Programmatic outbound handlers use `registerTelegramOutboundHandler(kind, handler)`. Voice replies can use configured command-template handlers or the provider API described in [Voice Integration](./voice.md).
 

package/docs/public-api.md

@@ -62,7 +62,7 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 ### Tools and assistant-authored actions
 
 - `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message. HTML mode, multiple/unsupported files, Guest Mode, and voice outputs retain their established paths. Outside Telegram turns the tool sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
-- `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message from local/TUI-initiated work when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
+- `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed for requested cross-target delivery. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
 - `telegram_help()` returns detailed agent-facing guidance for pi-telegram delivery actions, Threaded Mode, formatting, and debugging. The regular prompt only points agents at this tool instead of repeating the full guidance on every turn. `telegram_attach`, `telegram_message`, and `telegram_help` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through either a JSON object or double-quoted attributes. Equivalent `text` or `value` supplies the spoken payload; explicit `text` takes precedence.
 - `telegram_button` hidden comments create inline buttons whose taps enqueue prompts through the same two payload forms. Use `label` plus `prompt`, or `value` when both strings are identical. The colon after either action name is optional and does not select the format. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.

package/lib/bindings.ts

@@ -158,6 +158,7 @@ export function registerTelegramCommandsAndTools({
   OutboundAttachments.registerTelegramOutboundMessageTool(pi, {
     getDefaultChatId,
     getDefaultTarget,
+    getActiveTurn: activeTurnRuntime.get,
     canSendDirect,
     planMessage:
       OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),

package/lib/outbound-attachments.ts

@@ -81,6 +81,9 @@ export interface TelegramOutboundMessagePlan {
 export interface TelegramOutboundMessageToolRegistrationDeps extends TelegramOutboundAttachmentRuntimeEventRecorderPort {
   getDefaultChatId: () => number | undefined;
   getDefaultTarget?: () => TelegramTarget | undefined;
+  getActiveTurn?: () =>
+    | { chatId: number; target?: TelegramTarget }
+    | undefined;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -521,6 +524,7 @@ export function registerTelegramOutboundMessageTool(
           threadId: params.thread_id,
           getDefaultChatId: deps.getDefaultChatId,
           getDefaultTarget: deps.getDefaultTarget,
+          getActiveTurn: deps.getActiveTurn,
           canSendDirect: deps.canSendDirect,
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
@@ -735,6 +739,9 @@ export async function sendTelegramOutboundMessage(options: {
   target?: TelegramTarget;
   getDefaultChatId?: () => number | undefined;
   getDefaultTarget?: () => TelegramTarget | undefined;
+  getActiveTurn?: () =>
+    | { chatId: number; target?: TelegramTarget }
+    | undefined;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -754,6 +761,21 @@ export async function sendTelegramOutboundMessage(options: {
     getDefaultChatId: options.getDefaultChatId,
     getDefaultTarget: options.getDefaultTarget,
   });
+  const activeTurn = options.getActiveTurn?.();
+  if (activeTurn) {
+    const hasExplicitTarget =
+      options.chatId !== undefined || options.target !== undefined;
+    const activeTarget = activeTurn.target ?? { chatId: activeTurn.chatId };
+    const requestedTarget = target ?? { chatId };
+    const targetsMatch =
+      activeTarget.chatId === requestedTarget.chatId &&
+      activeTarget.threadId === requestedTarget.threadId;
+    if (!hasExplicitTarget || targetsMatch) {
+      throw new Error(
+        "telegram_message cannot send directly to the active Telegram turn target; return the text normally so the bridge can deliver it once",
+      );
+    }
+  }
   const plan = options.planMessage(options.text);
   const messageId = await options.sendMarkdownMessage(chatId, plan.markdown, {
     replyMarkup: plan.replyMarkup,

package/lib/prompts.ts

@@ -31,7 +31,7 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
   "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
-  "Do not use this tool for ordinary Telegram-originated replies; answer normally so the bridge can deliver the active turn reply.",
+  "During an active Telegram turn, omit telegram_message for the current target and answer normally; use it only with an explicit different chat_id/thread_id when the user requests cross-target delivery.",
 ] as const;
 
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([

package/package.json

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