@llblab/pi-telegram 0.27.4 → 0.27.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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/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).
 

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/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.5",
   "private": false,
   "publishConfig": {
     "access": "public"