@llblab/pi-telegram 0.27.4 → 0.27.6

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.27.6: Autonomous Follow-Up Delivery Hotfix
+
+- `Follow-Up Finals`: Completed public assistant blocks from unclassified Pi turns now follow the default-enabled Proactive Push path, alongside explicitly local and autonomous turns. Impact: actor terminal follow-ups and comparable extension-triggered continuations no longer show reasoning/activity in Telegram while silently dropping the final answer.
+- `Safety and Coverage`: Telegram-originated finals remain exclusively owned by active-turn settlement, while unclassified output still requires Proactive Push policy plus fresh direct/follower transport authority. Regression coverage proves unclassified finals deliver once when enabled and remain suppressed when disabled.
+
+## 0.27.5: Cross-Instance Agent Turns
+
+- `Live Thread Addressing`: `telegram_message` now accepts `thread` as a case-insensitive live thread name or numeric id. Resolution uses leader-owned live registrations and rejects unknown, ambiguous, same-target, offline, and cross-chat destinations before visible Telegram mutation.
+- `Agent Turn Routing`: A successful targeted send routes the same text through the authenticated, generation-fenced bus into the owning Pi instance as `[agent|from-thread:<name>]`, preserving one visible Telegram message without impersonating direct user input. Leader and follower targets share the ordinary inbound queue path, request deduplication, rendering, buttons, and authority fencing.
+- `Compatibility and Coverage`: Existing default and `chat_id` / `thread_id` behavior remains compatible; active-turn cross-thread sends gain agent routing when available. Regressions cover protocol parsing, stale generations, name resolution, ambiguity, attribution, preflight ordering, and tool delivery.
+
 ## 0.27.4: Disconnect Leadership Release Hotfix
 
 - `Leadership Release`: Manual disconnect now treats thread deletion as a durable cleanup side effect rather than a prerequisite for relinquishing transport leadership. A leader or promoted follower persists the exact cleanup intent, attempts close/delete under its epoch, and then stops polling and releases the owner lock even when Telegram rejects cleanup or the epoch changes. Impact: `Telegram Error` after `/telegram-disconnect` can no longer leave a live process pinning leadership and force newly connected instances to become followers.

package/README.md

@@ -8,7 +8,7 @@
 
 It is a **runtime adapter**, not a remote terminal. Start or supervise work in the Pi TUI, then continue from Telegram while away from the keyboard. Each Telegram destination follows a running Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session file or session identity. The bridge preserves Pi session semantics instead of pretending Telegram is a PTY, shell, process launcher, or session browser. That boundary is the product: Telegram gets safe runtime handles, not raw terminal power.
 
-Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local and autonomous work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order; set it explicitly to `false` to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
+Every completed intermediate commentary block from a Telegram-originated turn is delivered once as its own message before the existing final reply. Proactive push is enabled by default for local, autonomous, and unclassified extension follow-up work: `assistant.proactivePush` projects visible checkpoints and the final answer to the authorized Telegram target once and in order; set it explicitly to `false` to disable only that local/autonomous projection. Neither path mirrors local prompts, thinking, tool traffic, token deltas, or stale-generation work. The separate `Activity` setting defaults to `verbose` so new installations discover collapsed provider-exposed thinking and tool evidence immediately; operators can narrow it to one class or choose `quiet`. See [Outbound](docs/outbound.md#public-assistant-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 

package/docs/activity.md

@@ -236,7 +236,7 @@ The Delivery API independently serializes concrete Telegram operations per targe
 
 ### Core assistant-output projection
 
-Activity's built-in assistant-output projection uses the same normalized `assistant-segment` boundary exposed to public handlers. For `telegram` activity it always projects complete `intermediate` commentary to the immutable originating target, while final and terminal-partial segments remain with active-turn settlement. For `local` or `autonomous` activity, `assistant.proactivePush` enables projection of every completed public block, including intermediate commentary/checkpoints and the final block. It never projects text token deltas, reasoning events, tool events or payloads, unknown-source activity, or empty text.
+Activity's built-in assistant-output projection uses the same normalized `assistant-segment` boundary exposed to public handlers. For `telegram` activity it always projects complete `intermediate` commentary to the immutable originating target, while final and terminal-partial segments remain with active-turn settlement. For `local`, `autonomous`, or unclassified extension follow-up activity, `assistant.proactivePush` enables projection of every completed public block, including intermediate commentary/checkpoints and the final block. This closes actor-follow-up delivery without reclassifying it as direct user input. It never projects text token deltas, reasoning events, tool events or payloads, or empty text.
 
 The projection does not delay Activity dispatch or Pi lifecycle. Its ordered admission tail deduplicates normalized event identity, while existing routing and outbound owners revalidate the immutable admission-time target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation immediately before each send. Active-turn final delivery waits for admitted commentary inside its existing background task. A replacement or stale owner drops queued work rather than rerouting it, and an already-started non-idempotent Bot API mutation follows the normal `commit-unknown` no-replay contract.
 

package/docs/multi-instance-bus.md

@@ -281,6 +281,8 @@ Follower instances receive normalized events, not raw Telegram transport interna
 
 Followers do not call Telegram Bot API directly for routed Telegram work. Instead, they call a leader-owned transport port:
 
+Explicit `telegram_message(..., thread)` delivery also uses the bus as an agent-message plane. The leader resolves the case-insensitive name or numeric id against live leader/follower registrations, rejects ambiguous, stale, same-instance, cross-chat, and replayed requests, then coordinates visible Bot API delivery with one source-attributed synthetic turn routed through the destination instance's ordinary queue. The destination sees `[agent|from-thread:<name>]`, not an impersonated user message. Generation fencing and request-ledger deduplication apply to both resolution and routing.
+
 ```text
 follower reply/preview/upload/chat-action/download/callback-answer -> leader IPC -> Telegram API
 ```

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. 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.
+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. Its `thread` argument accepts a case-insensitive live thread name or numeric id: the bridge preflights one live owner, sends visibly, then admits the text as a source-attributed turn in that instance. Unknown, ambiguous, same-target, offline, and cross-chat destinations fail before sending. Existing `chat_id` plus `thread_id` targeting stays compatible; registered followers use authenticated, generation-fenced bus routing. 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).
 
@@ -10,7 +10,7 @@ Text handlers use the portable [Command Template Standard](./command-templates.m
 
 Every completed `assistant-segment` with `placement: "intermediate"` from a Telegram-originated turn is delivered as its own message to the immutable originating target before the ordinary active-turn final reply. This commentary path always applies; `assistant.proactivePush` does not disable it. Final and terminal-partial Telegram segments remain owned by active-turn settlement so the final answer, voice, buttons, previews, and artifacts are not duplicated.
 
-Proactive projection defaults on for local and autonomous Pi work. With `assistant.proactivePush` omitted or set to `true`, every completed public block—including visible commentary/checkpoints and the final answer—is projected to the instance's authorized target in source order; set it explicitly to `false` to opt out of only this local/autonomous projection. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
+Proactive projection defaults on for local, autonomous, and unclassified extension follow-up Pi work. With `assistant.proactivePush` omitted or set to `true`, every completed public block—including visible commentary/checkpoints and the final answer—is projected to the instance's authorized target in source order; set it explicitly to `false` to opt out of only this local/autonomous projection. Both paths consume normalized complete Activity segments rather than raw token deltas, reasoning, or tool traffic.
 
 Projected blocks use `assistant.rendering` independently of voice policy. Rich mode sends native Rich Markdown and HTML mode keeps the established HTML renderer; projection does not synthesize voice or attach queued files merely because Rich rendering is active. Ordered admission revalidates the exact target, profile/token transport generation, leader epoch or follower registration generation, and session generation before each send. Active-turn final delivery waits for admitted commentary inside its existing background delivery task, preserving commentary-before-final order without blocking Pi lifecycle completion. A `commit-unknown` outcome never permits replay.
 

package/index.ts

@@ -5,6 +5,7 @@
  */
 
 import * as Activity from "./lib/activity.ts";
+import * as AgentMessages from "./lib/agent-messages.ts";
 import * as ActivityVerbosity from "./lib/activity-verbosity.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as BusApi from "./lib/bus-api.ts";
@@ -811,6 +812,17 @@ export default function (pi: Pi.ExtensionAPI) {
       handleAuthorizedReactionUpdate:
         inboundRouteRuntime.handleAuthorizedReactionUpdate,
     });
+  const agentMessageRuntime = AgentMessages.createTelegramAgentMessageRuntime({
+    instanceId: telegramInstanceId,
+    getAllowedChatId: configStore.getAllowedUserId,
+    getLeaderTarget: telegramBusLeaderState.getTarget,
+    getLeaderThreadName() {
+      return findCurrentThreadRecord()?.threadName;
+    },
+    followerRegistry: telegramBusFollowerRegistry,
+    getContext: telegramSessionContextStore.get,
+    handleUpdate: inboundRouteRuntime.handleUpdate,
+  });
   const telegramBusFollowerAssemblyDeps =
     BusFollower.createTelegramBusFollowerRuntimeAssemblyDeps<
       Pi.ExtensionContext,
@@ -898,6 +910,16 @@ export default function (pi: Pi.ExtensionAPI) {
         startPolling: pollingRuntime.start,
         stopPolling: pollingRuntime.stop,
         authorizeFollowerApiCall,
+        resolveAgentTarget(follower, selector) {
+          return agentMessageRuntime.resolveTarget(selector, follower.target);
+        },
+        routeAgentMessage(follower, message) {
+          return agentMessageRuntime.route({
+            sourceTarget: follower.target,
+            sourceThreadName: follower.threadName,
+            message,
+          });
+        },
         isFollowerProcessAlive: Locks.isProcessAlive,
         shouldCleanupConfirmedDeadFollower:
           configControls.resolveAutomaticThreadCleanupEnabled,
@@ -1094,6 +1116,32 @@ export default function (pi: Pi.ExtensionAPI) {
     callMultipart,
     getDefaultChatId: proactivePushChatIdGetter,
     getDefaultTarget: proactivePushTargetGetter,
+    async resolveAgentTarget(selector) {
+      if (lockRuntime.owns()) {
+        const target = agentMessageRuntime.resolveTarget(
+          selector,
+          proactivePushTargetGetter(),
+        );
+        if (!target) {
+          throw new Error(
+            "Telegram agent target is unavailable, ambiguous, or not live.",
+          );
+        }
+        return target;
+      }
+      return telegramBusFollowerClients.agentMessages.resolveTarget(selector);
+    },
+    async routeAgentMessage(message) {
+      if (lockRuntime.owns()) {
+        await agentMessageRuntime.route({
+          sourceTarget: proactivePushTargetGetter(),
+          sourceThreadName: findCurrentThreadRecord()?.threadName,
+          message,
+        });
+        return;
+      }
+      await telegramBusFollowerClients.agentMessages.routeMessage(message);
+    },
     canSendDirect() {
       return (
         ownsTelegramDirectDelivery() ||

package/lib/activity.ts

@@ -732,7 +732,9 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
   const admitted = new Set<string>();
   const isEligibleEvent = (event: TelegramAssistantSegmentEvent): boolean =>
     (event.source === "telegram" && event.placement === "intermediate") ||
-    ((event.source === "local" || event.source === "autonomous") &&
+    ((event.source === "local" ||
+      event.source === "autonomous" ||
+      event.source === "unknown") &&
       deps.isEnabled());
 
   return {

package/lib/agent-messages.ts

@@ -0,0 +1,116 @@
+/**
+ * Cross-instance Telegram agent message resolution and turn injection
+ * Zones: multi-instance bus, inbound routing, operational delivery
+ * Owns live target resolution, source attribution, same-target fencing, and synthetic turn construction; excludes Bot API delivery and bus transport.
+ */
+
+import type {
+  TelegramBusAgentMessage,
+  TelegramBusAgentTargetSelector,
+  TelegramBusFollowerRegistry,
+} from "./bus.ts";
+import type { TelegramRoutedMessage } from "./routing.ts";
+import type { TelegramTarget } from "./target.ts";
+
+export interface TelegramAgentMessageRuntimeDeps<TContext, TUpdate> {
+  instanceId: string;
+  getAllowedChatId: () => number | undefined;
+  getLeaderTarget: () => TelegramTarget | undefined;
+  getLeaderThreadName: () => string | undefined;
+  followerRegistry: TelegramBusFollowerRegistry;
+  getContext: () => TContext | undefined;
+  handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
+  getNowMs?: () => number;
+}
+
+export function createTelegramAgentMessageRuntime<TContext, TUpdate>(
+  deps: TelegramAgentMessageRuntimeDeps<TContext, TUpdate>,
+) {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const sameTarget = (left?: TelegramTarget, right?: TelegramTarget) =>
+    left?.chatId === right?.chatId && left?.threadId === right?.threadId;
+  const listLiveTargets = () => {
+    const targets: Array<{
+      target: TelegramTarget & { threadId: number };
+      threadName?: string;
+    }> = [];
+    const leaderTarget = deps.getLeaderTarget();
+    if (leaderTarget?.threadId) {
+      targets.push({
+        target: { chatId: leaderTarget.chatId, threadId: leaderTarget.threadId },
+        threadName: deps.getLeaderThreadName(),
+      });
+    }
+    for (const follower of deps.followerRegistry.list()) {
+      if (!follower.target?.threadId) continue;
+      targets.push({
+        target: {
+          chatId: follower.target.chatId,
+          threadId: follower.target.threadId,
+        },
+        threadName: follower.threadName,
+      });
+    }
+    return targets;
+  };
+  const resolveTarget = (
+    selector: TelegramBusAgentTargetSelector,
+    sourceTarget?: TelegramTarget,
+  ): (TelegramTarget & { threadId: number }) | undefined => {
+    const allowedChatId = deps.getAllowedChatId();
+    const chatId = selector.chatId ?? allowedChatId;
+    if (chatId === undefined || chatId !== allowedChatId) return undefined;
+    const matches = listLiveTargets().filter((candidate) => {
+      if (candidate.target.chatId !== chatId) return false;
+      if (selector.threadId !== undefined) {
+        return candidate.target.threadId === selector.threadId;
+      }
+      const requestedName = selector.threadName?.trim().toLocaleLowerCase();
+      return (
+        requestedName !== undefined &&
+        requestedName.length > 0 &&
+        candidate.threadName?.trim().toLocaleLowerCase() === requestedName
+      );
+    });
+    if (matches.length !== 1) return undefined;
+    return sameTarget(matches[0]!.target, sourceTarget)
+      ? undefined
+      : matches[0]!.target;
+  };
+  return {
+    resolveTarget,
+    async route(input: {
+      sourceTarget?: TelegramTarget;
+      sourceThreadName?: string;
+      message: TelegramBusAgentMessage;
+    }): Promise<void> {
+      const target = resolveTarget(
+        {
+          chatId: input.message.target.chatId,
+          threadId: input.message.target.threadId,
+        },
+        input.sourceTarget,
+      );
+      if (!target) throw new Error("Telegram agent target is no longer live.");
+      const allowedChatId = deps.getAllowedChatId();
+      const ctx = deps.getContext();
+      if (allowedChatId === undefined || !ctx) {
+        throw new Error("Telegram agent turn routing is unavailable.");
+      }
+      const sourceLabel =
+        input.sourceThreadName
+          ?.replace(/[\r\n\[\]]+/g, " ")
+          .trim()
+          .slice(0, 64) || "Pi";
+      const message = {
+        message_id: input.message.messageId,
+        date: Math.floor(getNowMs() / 1000),
+        chat: { id: target.chatId, type: "private" as const },
+        from: { id: allowedChatId, is_bot: false, first_name: "Pi Agent" },
+        message_thread_id: target.threadId,
+        text: `[agent|from-thread:${sourceLabel}]\n\n${input.message.text}`,
+      } as TelegramRoutedMessage;
+      await deps.handleUpdate({ message } as TUpdate, ctx);
+    },
+  };
+}

package/lib/bindings.ts

@@ -121,6 +121,8 @@ interface TelegramCommandsAndToolsBindingDeps {
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
   getDefaultChatId: () => number | undefined;
   getDefaultTarget?: () => OutboundAttachments.TelegramQueuedOutboundAttachmentTurnView["target"];
+  resolveAgentTarget?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["resolveAgentTarget"];
+  routeAgentMessage?: OutboundAttachments.TelegramOutboundMessageToolRegistrationDeps["routeAgentMessage"];
   canSendDirect: () => boolean;
   updateStatus: TelegramBridgeStatusUpdater;
   recordRuntimeEvent: TelegramRuntimeEventRecorder;
@@ -143,6 +145,8 @@ export function registerTelegramCommandsAndTools({
   callMultipart,
   getDefaultChatId,
   getDefaultTarget,
+  resolveAgentTarget,
+  routeAgentMessage,
   canSendDirect,
   recordRuntimeEvent,
   updateStatus,
@@ -159,6 +163,8 @@ export function registerTelegramCommandsAndTools({
     getDefaultChatId,
     getDefaultTarget,
     getActiveTurn: activeTurnRuntime.get,
+    resolveAgentTarget,
+    routeAgentMessage,
     canSendDirect,
     planMessage:
       OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),

package/lib/bus-follower.ts

@@ -25,6 +25,8 @@ import {
   getTelegramBusSocketPath,
   resolveTelegramBusSocketPath,
   sendTelegramBusLocalEnvelope,
+  type TelegramBusAgentMessage,
+  type TelegramBusAgentTargetSelector,
   type TelegramBusEnvelope,
   type TelegramBusSocketPathSource,
 } from "./bus.ts";
@@ -736,6 +738,12 @@ export function createTelegramBusFollowerClientRuntime<
       getAuthSecret: deps.getApiAuthSecret,
       getRegistrationGeneration: deps.getRegistrationGeneration,
     }),
+    agentMessages: createTelegramBusAgentMessageClient({
+      ...sharedClientDeps,
+      instanceId: deps.instanceId,
+      getAuthSecret: deps.getApiAuthSecret,
+      getRegistrationGeneration: deps.getRegistrationGeneration,
+    }),
     foreignOwnedUpdateForwarder: createTelegramBusForeignOwnedUpdateForwarder<
       TContext,
       TReactionUpdate,
@@ -755,6 +763,79 @@ export function createTelegramBusFollowerClientRuntime<
   };
 }
 
+export function createTelegramBusAgentMessageClient(
+  deps: TelegramBusFollowerApiCallerDeps,
+): {
+  resolveTarget: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeMessage: (message: TelegramBusAgentMessage) => Promise<void>;
+} {
+  const getNowMs = deps.getNowMs ?? Date.now;
+  const timeoutMs =
+    deps.timeoutMs ?? TELEGRAM_BUS_FOLLOWER_CLIENT_TIMEOUT_MS;
+  const request = async (
+    envelope:
+      | Extract<TelegramBusEnvelope, { kind: "follower.resolveAgentTarget" }>
+      | Extract<TelegramBusEnvelope, { kind: "follower.routeAgentMessage" }>,
+  ): Promise<unknown> => {
+    const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+    const response = await sendTelegramBusLocalEnvelope({
+      socketPath,
+      timeoutMs,
+      retry: getTelegramBusTransportRetryPolicy({
+        endpoint: socketPath,
+        operation: "operation",
+      }),
+      envelope,
+    });
+    if (response?.kind === "bus.ack" && response.ok) return response.result;
+    throw new Error(
+      response?.kind === "bus.ack"
+        ? response.message ?? "Telegram bus agent message failed."
+        : "Telegram bus agent message did not return an acknowledgement.",
+    );
+  };
+  const registrationFields = () => ({
+    auth: deps.getAuthSecret?.(),
+    instanceId: deps.instanceId,
+    ...(deps.getRegistrationGeneration?.()
+      ? { registrationGeneration: deps.getRegistrationGeneration?.() }
+      : {}),
+  });
+  return {
+    async resolveTarget(selector) {
+      const result = await request({
+        kind: "follower.resolveAgentTarget",
+        requestId: deps.createRequestId(),
+        ...registrationFields(),
+        selector,
+        sentAtMs: getNowMs(),
+      });
+      if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new Error("Telegram bus returned an invalid agent target.");
+      }
+      const target = result as Record<string, unknown>;
+      if (
+        typeof target.chatId !== "number" ||
+        typeof target.threadId !== "number"
+      ) {
+        throw new Error("Telegram bus returned an invalid agent target.");
+      }
+      return { chatId: target.chatId, threadId: target.threadId };
+    },
+    async routeMessage(message) {
+      await request({
+        kind: "follower.routeAgentMessage",
+        requestId: deps.createRequestId(),
+        ...registrationFields(),
+        message,
+        sentAtMs: getNowMs(),
+      });
+    },
+  };
+}
+
 export function createTelegramBusFollowerApiCaller(
   deps: TelegramBusFollowerApiCallerDeps,
 ): (method: string, args: unknown[]) => Promise<unknown> {

package/lib/bus-leader.ts

@@ -258,6 +258,20 @@ export interface TelegramBusLeaderRuntimeDeps<TContext> {
     args: unknown[];
   }) => boolean;
   recordFollowerMessageOwnership?: TelegramBusFollowerMessageOwnershipRecorder;
+  resolveAgentTarget?: (
+    follower: TelegramBusFollowerView,
+    selector: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.resolveAgentTarget" }
+    >["selector"],
+  ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  routeAgentMessage?: (
+    follower: TelegramBusFollowerView,
+    message: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.routeAgentMessage" }
+    >["message"],
+  ) => Promise<void> | void;
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
   ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
@@ -1024,6 +1038,20 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
     args: unknown[];
   }) => boolean;
   recordFollowerMessageOwnership?: TelegramBusFollowerMessageOwnershipRecorder;
+  resolveAgentTarget?: (
+    follower: TelegramBusFollowerView,
+    selector: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.resolveAgentTarget" }
+    >["selector"],
+  ) => Promise<TelegramTarget | undefined> | TelegramTarget | undefined;
+  routeAgentMessage?: (
+    follower: TelegramBusFollowerView,
+    message: Extract<
+      TelegramBusEnvelope,
+      { kind: "follower.routeAgentMessage" }
+    >["message"],
+  ) => Promise<void> | void;
   provisionFollowerTarget?: (
     registration: TelegramBusInstanceRegistration,
   ) =>
@@ -1044,6 +1072,67 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
   const getNowMs = deps.getNowMs ?? Date.now;
   const runFollowerMutation =
     deps.runFollowerMutation ?? createTelegramBusFollowerMutationRunner();
+  const handleAgentRequest = async (
+    envelope: Extract<
+      TelegramBusEnvelope,
+      {
+        kind:
+          | "follower.resolveAgentTarget"
+          | "follower.routeAgentMessage";
+      }
+    >,
+  ): Promise<TelegramBusEnvelope> => {
+    const follower = deps.followerRegistry.get(envelope.instanceId);
+    if (!follower) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Unknown Telegram bus follower instance.",
+      };
+    }
+    if (
+      follower.registrationGeneration &&
+      envelope.registrationGeneration !== follower.registrationGeneration
+    ) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Stale Telegram bus follower registration generation.",
+      };
+    }
+    deps.followerRegistry.heartbeat(envelope.instanceId, getNowMs());
+    if (envelope.kind === "follower.resolveAgentTarget") {
+      const target = await deps.resolveAgentTarget?.(
+        follower,
+        envelope.selector,
+      );
+      return target
+        ? {
+            kind: "bus.ack",
+            requestId: envelope.requestId,
+            ok: true,
+            result: target,
+          }
+        : {
+            kind: "bus.ack",
+            requestId: envelope.requestId,
+            ok: false,
+            message: "Telegram agent target is unavailable or ambiguous.",
+          };
+    }
+    if (!deps.routeAgentMessage) {
+      return {
+        kind: "bus.ack",
+        requestId: envelope.requestId,
+        ok: false,
+        message: "Telegram agent message routing is unavailable.",
+      };
+    }
+    await deps.routeAgentMessage(follower, envelope.message);
+    return { kind: "bus.ack", requestId: envelope.requestId, ok: true };
+  };
   const forwardToFollower = async (
     envelope: Extract<
       TelegramBusEnvelope,
@@ -1251,6 +1340,9 @@ export function createTelegramBusLeaderEnvelopeHandler(deps: {
               message: "Unknown Telegram bus follower instance.",
             };
       }
+      case "follower.resolveAgentTarget":
+      case "follower.routeAgentMessage":
+        return handleAgentRequest(envelope);
       case "leader.forwardCallback":
       case "leader.forwardReaction":
       case "leader.forwardMessage":
@@ -1619,6 +1711,8 @@ export function createTelegramBusLeaderRuntime<TContext>(
       callApi: deps.callApi,
       authorizeFollowerApiCall: deps.authorizeFollowerApiCall,
       recordFollowerMessageOwnership: deps.recordFollowerMessageOwnership,
+      resolveAgentTarget: deps.resolveAgentTarget,
+      routeAgentMessage: deps.routeAgentMessage,
       provisionFollowerTarget: deps.provisionFollowerTarget,
       onFollowerDisconnected: deps.onFollowerDisconnected,
       getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,

package/lib/bus.ts

@@ -448,6 +448,18 @@ export function createTelegramFollowerApiCallAuthorizer(deps: {
     });
 }
 
+export interface TelegramBusAgentTargetSelector {
+  chatId?: number;
+  threadId?: number;
+  threadName?: string;
+}
+
+export interface TelegramBusAgentMessage {
+  target: TelegramTarget & { threadId: number };
+  messageId: number;
+  text: string;
+}
+
 export type TelegramBusEnvelope = (
   | {
       kind: "follower.register";
@@ -511,6 +523,22 @@ export type TelegramBusEnvelope = (
       reason: "thread-restore";
       sentAtMs: number;
     }
+  | {
+      kind: "follower.resolveAgentTarget";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration?: string;
+      selector: TelegramBusAgentTargetSelector;
+      sentAtMs: number;
+    }
+  | {
+      kind: "follower.routeAgentMessage";
+      requestId: string;
+      instanceId: string;
+      registrationGeneration?: string;
+      message: TelegramBusAgentMessage;
+      sentAtMs: number;
+    }
   | {
       kind: "follower.callApi";
       requestId: string;
@@ -605,6 +633,12 @@ export function parseTelegramBusEnvelope(
     case "leader.replaceFollowerTarget":
       envelope = parseReplaceFollowerTargetEnvelope(value, requestId);
       break;
+    case "follower.resolveAgentTarget":
+      envelope = parseResolveAgentTargetEnvelope(value, requestId);
+      break;
+    case "follower.routeAgentMessage":
+      envelope = parseRouteAgentMessageEnvelope(value, requestId);
+      break;
     case "follower.callApi":
       envelope = parseCallApiEnvelope(value, requestId);
       break;
@@ -1582,6 +1616,86 @@ function parseReplaceFollowerTargetEnvelope(
   };
 }
 
+function parseResolveAgentTargetEnvelope(
+  value: Record<string, unknown>,
+  requestId: string,
+): TelegramBusEnvelope | undefined {
+  const selectorValue = isRecord(value.selector) ? value.selector : undefined;
+  if (
+    typeof value.instanceId !== "string" ||
+    !selectorValue ||
+    typeof value.sentAtMs !== "number"
+  ) {
+    return undefined;
+  }
+  const chatId =
+    typeof selectorValue.chatId === "number" &&
+    Number.isInteger(selectorValue.chatId)
+      ? selectorValue.chatId
+      : undefined;
+  const threadId =
+    typeof selectorValue.threadId === "number" &&
+    Number.isInteger(selectorValue.threadId) &&
+    selectorValue.threadId > 0
+      ? selectorValue.threadId
+      : undefined;
+  const threadName =
+    typeof selectorValue.threadName === "string" &&
+    selectorValue.threadName.trim()
+      ? selectorValue.threadName.trim()
+      : undefined;
+  if ((threadId === undefined) === (threadName === undefined)) return undefined;
+  return {
+    kind: "follower.resolveAgentTarget",
+    requestId,
+    instanceId: value.instanceId,
+    ...(typeof value.registrationGeneration === "string"
+      ? { registrationGeneration: value.registrationGeneration }
+      : {}),
+    selector: {
+      ...(chatId !== undefined ? { chatId } : {}),
+      ...(threadId !== undefined ? { threadId } : {}),
+      ...(threadName !== undefined ? { threadName } : {}),
+    },
+    sentAtMs: value.sentAtMs,
+  };
+}
+
+function parseRouteAgentMessageEnvelope(
+  value: Record<string, unknown>,
+  requestId: string,
+): TelegramBusEnvelope | undefined {
+  const messageValue = isRecord(value.message) ? value.message : undefined;
+  const target = parseThreadTarget(messageValue?.target);
+  if (
+    typeof value.instanceId !== "string" ||
+    !messageValue ||
+    !target ||
+    typeof messageValue.messageId !== "number" ||
+    !Number.isInteger(messageValue.messageId) ||
+    messageValue.messageId <= 0 ||
+    typeof messageValue.text !== "string" ||
+    !messageValue.text.trim() ||
+    typeof value.sentAtMs !== "number"
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "follower.routeAgentMessage",
+    requestId,
+    instanceId: value.instanceId,
+    ...(typeof value.registrationGeneration === "string"
+      ? { registrationGeneration: value.registrationGeneration }
+      : {}),
+    message: {
+      target,
+      messageId: messageValue.messageId,
+      text: messageValue.text,
+    },
+    sentAtMs: value.sentAtMs,
+  };
+}
+
 function parseCallApiEnvelope(
   value: Record<string, unknown>,
   requestId: string,

package/lib/outbound-attachments.ts

@@ -9,6 +9,10 @@ import { basename } from "node:path";
 
 import { Type } from "@sinclair/typebox";
 
+import type {
+  TelegramBusAgentMessage,
+  TelegramBusAgentTargetSelector,
+} from "./bus.ts";
 import type { ExtensionAPI } from "./pi.ts";
 import {
   TELEGRAM_ATTACH_PROMPT_GUIDELINES,
@@ -84,6 +88,10 @@ export interface TelegramOutboundMessageToolRegistrationDeps extends TelegramOut
   getActiveTurn?: () =>
     | { chatId: number; target?: TelegramTarget }
     | undefined;
+  resolveAgentTarget?: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeAgentMessage?: (message: TelegramBusAgentMessage) => Promise<void>;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -515,6 +523,12 @@ export function registerTelegramOutboundMessageTool(
           description: "Optional Telegram topic thread id with chat_id",
         }),
       ),
+      thread: Type.Optional(
+        Type.Union([Type.String(), Type.Number()], {
+          description:
+            "Optional live Pi thread name or numeric id for visible delivery plus a target-agent turn",
+        }),
+      ),
     }),
     async execute(_toolCallId, params) {
       try {
@@ -522,9 +536,12 @@ export function registerTelegramOutboundMessageTool(
           text: params.text,
           chatId: params.chat_id,
           threadId: params.thread_id,
+          agentThread: params.thread,
           getDefaultChatId: deps.getDefaultChatId,
           getDefaultTarget: deps.getDefaultTarget,
           getActiveTurn: deps.getActiveTurn,
+          resolveAgentTarget: deps.resolveAgentTarget,
+          routeAgentMessage: deps.routeAgentMessage,
           canSendDirect: deps.canSendDirect,
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
@@ -736,12 +753,17 @@ export async function sendTelegramOutboundMessage(options: {
   text: string;
   chatId?: number;
   threadId?: number;
+  agentThread?: string | number;
   target?: TelegramTarget;
   getDefaultChatId?: () => number | undefined;
   getDefaultTarget?: () => TelegramTarget | undefined;
   getActiveTurn?: () =>
     | { chatId: number; target?: TelegramTarget }
     | undefined;
+  resolveAgentTarget?: (
+    selector: TelegramBusAgentTargetSelector,
+  ) => Promise<TelegramTarget & { threadId: number }>;
+  routeAgentMessage?: (message: TelegramBusAgentMessage) => Promise<void>;
   canSendDirect: () => boolean;
   planMessage: (markdown: string) => TelegramOutboundMessagePlan;
   sendMarkdownMessage: (
@@ -754,17 +776,41 @@ export async function sendTelegramOutboundMessage(options: {
   details: { chatId: number; messageId?: number };
 }> {
   assertTelegramDirectDeliveryAllowed(options.canSendDirect);
+  const activeTurn = options.getActiveTurn?.();
+  const requestedAgentSelector: TelegramBusAgentTargetSelector | undefined =
+    options.agentThread !== undefined
+      ? typeof options.agentThread === "number"
+        ? { chatId: options.chatId, threadId: options.agentThread }
+        : { chatId: options.chatId, threadName: options.agentThread }
+      : activeTurn &&
+          options.resolveAgentTarget &&
+          options.routeAgentMessage &&
+          ((options.target?.threadId !== undefined) ||
+            (options.chatId !== undefined && options.threadId !== undefined))
+        ? {
+            chatId: options.target?.chatId ?? options.chatId,
+            threadId: options.target?.threadId ?? options.threadId,
+          }
+        : undefined;
+  let agentTarget: (TelegramTarget & { threadId: number }) | undefined;
+  if (requestedAgentSelector) {
+    if (!options.resolveAgentTarget || !options.routeAgentMessage) {
+      throw new Error("Telegram agent turn routing is unavailable.");
+    }
+    agentTarget = await options.resolveAgentTarget(requestedAgentSelector);
+  }
   const { chatId, target } = resolveTelegramOutboundTarget({
-    chatId: options.chatId,
-    threadId: options.threadId,
-    target: options.target,
+    chatId: agentTarget?.chatId ?? options.chatId,
+    threadId: agentTarget?.threadId ?? options.threadId,
+    target: agentTarget ?? options.target,
     getDefaultChatId: options.getDefaultChatId,
     getDefaultTarget: options.getDefaultTarget,
   });
-  const activeTurn = options.getActiveTurn?.();
   if (activeTurn) {
     const hasExplicitTarget =
-      options.chatId !== undefined || options.target !== undefined;
+      options.chatId !== undefined ||
+      options.target !== undefined ||
+      options.agentThread !== undefined;
     const activeTarget = activeTurn.target ?? { chatId: activeTurn.chatId };
     const requestedTarget = target ?? { chatId };
     const targetsMatch =
@@ -781,6 +827,18 @@ export async function sendTelegramOutboundMessage(options: {
     replyMarkup: plan.replyMarkup,
     target,
   });
+  if (agentTarget) {
+    if (messageId === undefined) {
+      throw new Error(
+        "Telegram message was sent but no message id was returned for agent routing.",
+      );
+    }
+    await options.routeAgentMessage!({
+      target: agentTarget,
+      messageId,
+      text: options.text,
+    });
+  }
   return {
     content: [
       {

package/lib/prompts.ts

@@ -29,9 +29,9 @@ export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
   "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
 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.",
+  "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
-  "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.",
+  "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
 ] as const;
 
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([

package/package.json

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