@llblab/pi-telegram 0.27.2 → 0.27.3

package/AGENTS.md

@@ -94,7 +94,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - Thread bindings are bidirectional. From the Pi-instance side, an instance knows and preserves its target, slot, thread name, lifecycle state, and direct-delivery defaults. From the Telegram-client/bot side, the bridge observes thread creation/close/reopen/stale-send signals and reconciles them into instance binding state. Lifecycle transitions that affect operator understanding should be Telegram-visible when a live transport remains: every successful follower registration/re-registration gets a compact connected notice in the assigned thread, while heartbeat pruning stays silent because it is only liveness suspicion. These notices should use the instance thread name when known and fall back to the slot letter only while the thread is still unnamed. New unknown or command-created temporary threads receive the complete forward plus replace/restore control set and remain preserved until the user chooses one. Successful forward deletes the chooser and temporary thread; successful replace/restore always deletes the chooser, rebinds the temporary thread, and deletes only the replaced old thread. Any destructive cleanup must go through `thread-reconciler`. Unknown `forum_topic_created` service events are observations, not destructive cleanup proof.
 - The multi-instance bus uses private bot DMs with Telegram private-chat Threaded Mode enabled for the bot. No supergroup, group, or forum configuration is needed; the thread chat is always the private chat with the paired owner. Threaded capability checks must use bot/private-chat evidence such as `getMe.has_topics_enabled`, incoming `message_thread_id`, and topic operation success/failure; do not use group chat metadata as the control-plane truth for Telegram private-chat Threaded Mode.
 - Target-scoped behavior must preserve `{ chatId, threadId? }` through inbound messages/edits/callbacks/reactions, thread lifecycle service messages, media and split-text grouping, queue mutations, active-turn cleanup, previews, reply deduplication, menus, sections, generated buttons, voice, attachments, and direct delivery. Threaded Mode replies must keep Telegram's reply affordance to the triggering message just like classic DM mode. In Telegram private-chat Threaded Mode, mobile Telegram has been live-verified to render `sendMessage` replies that include top-level `message_thread_id` plus same-chat `reply_parameters.message_id`; Telegram Desktop may fail to show the visual reply header for the same correct payload, so do not treat Desktop-only absence as bridge failure without mobile/payload evidence.
-- Local bus IPC is a local-only trust boundary: private socket directories/files are necessary but not the whole authorization model; never let arbitrary local processes inject prompts, callbacks, API sends, or artifact routes.
+- Local bus IPC is a local-only trust boundary: private socket directories/files are necessary but not the whole authorization model; never let arbitrary local processes inject prompts, callbacks, API sends, or artifact routes. Ordinary follower Bot API sends remain assigned-target scoped; runtime-marked `telegram_message` cross-target sends may address only a different thread in the same paired chat, and the leader must strip that internal authorization marker before Telegram transport.
 - Queue admission is explicit and validated: immediate commands, control lane, priority lane, and default lane must preserve allowed kind/lane pairings
 - Dispatch is gated by active turns, pending dispatch, unsettled control work, compaction, `ctx.isIdle()`, and Pi pending messages; dispatched prompts remain queued until `agent_start` consumes them
 - Telegram `/compact` owns a native `typing` keepalive for the compaction window so phone clients show activity between the started/completed notices; stop it on both completion and failure. Automatic/session compaction may start native typing only when an active Telegram turn exists, and must reuse that turn target; startup, reload, connect, restore, and idle/background compaction must not create visible typing by themselves.

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.27.3: Follower Cross-Thread Delivery Hotfix
+
+- `Follower Cross-Thread Delivery`: The bus-aware Telegram API runtime now marks sends whose target differs from the follower's assigned thread, and the leader authorizes that internal marker only for a different target inside the same paired chat before stripping it from the Bot API request. Impact: `telegram_message` can fulfill explicit inter-thread delivery from follower instances without opening arbitrary cross-chat or generic follower API access.
+- `Authorization Coverage`: Focused regressions cover follower marker admission, assigned-target rejection, wrong-chat rejection, unmarked rejection, transport metadata stripping, and Rich-message marking while preserving the existing target-aware active-turn guard. Impact: the outbound policy and bus trust boundary now agree end to end instead of allowing a request locally and rejecting it at leader transport.
+
 ## 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.

package/docs/multi-instance-bus.md

@@ -408,7 +408,7 @@ All files containing routing, chat ids, thread ids, or process details use priva
 
 - Messages, edits, callbacks, and reactions check user authorization, not only chat/thread membership.
 - Followers authenticate to the local leader IPC with a leader-minted capability secret carried in the active lock entry; registration, heartbeat, forwarded updates, and follower API calls without the secret are rejected. Registration rejections are surfaced verbatim in the follower `/telegram-connect` result, registration waits through leader-side Telegram thread provisioning, and successful registrations send an immediate heartbeat before the interval ticker so the leader does not prune a live follower before its first scheduled heartbeat. The local bus socket is also created under a private `0700` directory with `0600` socket permissions as a first local-only boundary.
-- Follower Bot API proxying is allowlisted and target-scoped where applicable so a follower can reply in its assigned thread without gaining arbitrary bot control.
+- Follower Bot API proxying is allowlisted and target-scoped where applicable. Ordinary sends remain confined to the follower's assigned thread; trusted runtime-marked `telegram_message` cross-target sends may address only a different thread inside the same paired chat, and the leader strips the internal marker before calling Telegram. This preserves requested inter-thread delivery without granting arbitrary bot or cross-chat control.
 - Button and section callbacks verify authorized `from.id` and owning target/instance.
 - Generated artifacts stay scoped to the owning thread after leader failover.
 - Diagnostics redact bot tokens, large prompts, attachment paths, and handler output.

package/lib/bus-api.ts

@@ -4,7 +4,10 @@
  * Wraps the direct Telegram Bot API runtime so follower instances can route outbound calls through the bus leader
  */
 
-import { stripTelegramBusApiMetadata } from "./bus.ts";
+import {
+  markTelegramBusCrossTargetDelivery,
+  stripTelegramBusApiMetadata,
+} from "./bus.ts";
 import { isTelegramMessageNotModifiedError } from "./telegram-api.ts";
 import type {
   TelegramAnswerGuestQueryOptions,
@@ -56,6 +59,19 @@ function withDefaultThreadTarget(
     : body;
 }
 
+function markFollowerCrossTargetDelivery<T extends Record<string, unknown>>(
+  body: T,
+  defaultTarget: { chatId: number; threadId?: number } | undefined,
+): T {
+  if (!defaultTarget || body.chat_id !== defaultTarget.chatId) return body;
+  const threadId = body.message_thread_id;
+  const isDifferentTarget =
+    threadId === undefined
+      ? defaultTarget.threadId !== undefined
+      : threadId !== defaultTarget.threadId;
+  return isDifferentTarget ? markTelegramBusCrossTargetDelivery(body) : body;
+}
+
 function rejectTelegramDirectOwnership(method: string): Promise<never> {
   return Promise.reject(
     new Error(`Telegram ${method} requires direct transport ownership.`),
@@ -238,16 +254,28 @@ export function createTelegramBusAwareApiRuntime(
       return deps.ownsDirect()
         ? deps.directRuntime.sendMessage(stripTelegramBusApiMetadata(body))
         : deps
-            .callFollowerApi("call", ["sendMessage", body])
+            .callFollowerApi("call", [
+              "sendMessage",
+              markFollowerCrossTargetDelivery(
+                body,
+                deps.getDefaultTarget?.(),
+              ),
+            ])
             .then(asSentMessage);
     },
     sendRichMessage(
       body: TelegramSendRichMessageBody,
     ): Promise<TelegramSentMessage> {
       return deps.ownsDirect()
-        ? deps.directRuntime.sendRichMessage(body)
+        ? deps.directRuntime.sendRichMessage(stripTelegramBusApiMetadata(body))
         : deps
-            .callFollowerApi("call", ["sendRichMessage", body])
+            .callFollowerApi("call", [
+              "sendRichMessage",
+              markFollowerCrossTargetDelivery(
+                body,
+                deps.getDefaultTarget?.(),
+              ),
+            ])
             .then(asSentMessage);
     },
     sendRichMessageDraft(

package/lib/bus.ts

@@ -229,6 +229,8 @@ export function getTelegramFollowerTargetOwnership(input: {
 }
 
 const TELEGRAM_BUS_AGGREGATE_DELIVERY_FIELD = "__piTelegramAggregateDelivery";
+const TELEGRAM_BUS_CROSS_TARGET_DELIVERY_FIELD =
+  "__piTelegramCrossTargetDelivery";
 
 export function markTelegramBusAggregateDelivery<
   T extends Record<string, unknown>,
@@ -249,12 +251,38 @@ export function isTelegramBusAggregateDelivery(body: unknown): boolean {
   );
 }
 
+export function markTelegramBusCrossTargetDelivery<
+  T extends Record<string, unknown>,
+>(body: T): T {
+  return {
+    ...body,
+    [TELEGRAM_BUS_CROSS_TARGET_DELIVERY_FIELD]: true,
+  };
+}
+
+export function isTelegramBusCrossTargetDelivery(body: unknown): boolean {
+  return Boolean(
+    body &&
+    typeof body === "object" &&
+    !Array.isArray(body) &&
+    (body as Record<string, unknown>)[
+      TELEGRAM_BUS_CROSS_TARGET_DELIVERY_FIELD
+    ] === true,
+  );
+}
+
 export function stripTelegramBusApiMetadata<T extends Record<string, unknown>>(
   body: T,
 ): T {
-  if (!(TELEGRAM_BUS_AGGREGATE_DELIVERY_FIELD in body)) return body;
+  if (
+    !(TELEGRAM_BUS_AGGREGATE_DELIVERY_FIELD in body) &&
+    !(TELEGRAM_BUS_CROSS_TARGET_DELIVERY_FIELD in body)
+  ) {
+    return body;
+  }
   const clean = { ...body };
   delete clean[TELEGRAM_BUS_AGGREGATE_DELIVERY_FIELD];
+  delete clean[TELEGRAM_BUS_CROSS_TARGET_DELIVERY_FIELD];
   return clean;
 }
 
@@ -304,6 +332,18 @@ export function isTelegramFollowerApiCallAllowed(input: {
     const record = body as Record<string, unknown>;
     return matchesId(record.chat_id, target.chatId);
   };
+  const isDifferentTargetScoped = (body: unknown): boolean => {
+    if (!target || !isTargetChatScoped(body)) return false;
+    const threadId = (body as Record<string, unknown>).message_thread_id;
+    if (threadId === undefined) return target.threadId !== undefined;
+    const parsedThreadId =
+      typeof threadId === "number" ? threadId : Number(threadId);
+    return (
+      Number.isInteger(parsedThreadId) &&
+      (target.threadId === undefined ||
+        !matchesId(threadId, target.threadId))
+    );
+  };
   const isTargetMessageScoped = (body: unknown): boolean => {
     if (!isTargetChatScoped(body)) return false;
     const messageId = (body as Record<string, unknown>).message_id;
@@ -350,6 +390,12 @@ export function isTelegramFollowerApiCallAllowed(input: {
       const body = input.args[1] as Record<string, unknown>;
       return body.message_thread_id === undefined && isTargetChatScoped(body);
     }
+    if (
+      (apiMethod === "sendMessage" || apiMethod === "sendRichMessage") &&
+      isTelegramBusCrossTargetDelivery(input.args[1])
+    ) {
+      return isDifferentTargetScoped(input.args[1]);
+    }
     if (
       apiMethod === "deleteMessage" ||
       apiMethod === "editMessageReplyMarkup" ||

package/package.json

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