@llblab/pi-telegram 0.9.6 → 0.9.8

package/BACKLOG.md

@@ -2,13 +2,9 @@
 
 ## Open Work
 
-- Implement Telegram Extension Sections Platform for the 0.10.0 line.
+- [ ] Implement Telegram Extension Sections Platform for the 0.10.0 line.
   - Exit: Runtime registry, main-menu integration, `section:` callback routing, safe section context ports, diagnostics, docs, and at least one small demo/fixture prove ordinary pi extensions can add Telegram menu sections without owning a second poller.
-- Explore always-available outbound Telegram tools for queued artifacts and controls.
+- [ ] Explore always-available outbound Telegram tools for queued artifacts and controls.
   - Priority: Low.
   - Idea: Provide tools such as `telegram_attach_file` and `telegram_attach_button` that can be called outside an active Telegram turn, using the paired chat/session as the delivery target when safe.
   - Exit: Design note defines active-turn versus ambient delivery semantics, safety constraints, failure modes, and whether the current `telegram_attach` contract should stay turn-scoped or gain an ambient companion.
-- Tighten dependency posture for reproducible extension development.
-  - Priority: Medium.
-  - Idea: Replace broad peer dependency `*` ranges and dev dependency `latest` ranges with explicit compatible ranges once the supported pi/Node/TypeScript matrix is clear.
-  - Exit: `package.json` documents the supported Node expectation and compatible pi package ranges without over-constraining early-stage extension iteration.

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.9.8: Guest Mode Context
+
+- `[Guest Mode]` Extended the [telegram] prefix with |from:user (sender) and |guest:GroupName (source chat for group guest messages) so the agent sees who sent the message and where from. Private guest chats omit the guest: suffix.
+- `[Guest Mode]` Added |from:user to the [reply] block so the agent knows the original author of a replied-to message in guest mode.
+- `[Guest Mode]` Formatted guest prompt text identically to regular DMs through buildTelegramTurnPrompt, including [attachments] and [outputs] sections with file downloads and inbound handler processing.
+- `[Prompts]` Added compact agent guidance explaining guest-mode prefix suffixes (|from:, |guest:) and reply-from context.
+
+## 0.9.7: Bot API 10.0 Alignment
+
+- `[Dependencies]` Migrated peer dependencies and imports from `@mariozechner/*` to `@earendil-works/*` (`pi-agent-core`, `pi-ai`, `pi-coding-agent`). Impact: the extension now tracks the new `@earendil-works` package scope; transitive `@mariozechner` packages remain in the lockfile until their upstreams migrate.
+- `[Package]` Added `engines: { "node": ">=22.0.0" }` to document the supported Node expectation while keeping dev dependencies on `latest` for early-stage iteration. Impact: users know the minimum Node version without constraining the development dependency matrix prematurely.
+- `[Polling]` Added `"guest_message"` to `TELEGRAM_ALLOWED_UPDATES` so the bot receives guest-mode updates. Impact: without this, guest mentions are silently ignored by Telegram.
+- `[Telegram API]` Updated `sendMessageDraft` wrapper for Bot API 10.0 semantics: removed the empty-text guard, made `text` optional, and added optional `parse_mode`, `entities`, and `message_thread_id` parameters. Impact: preview can now show a "Thinking…" placeholder with empty text, and callers can pass rich formatting through `parse_mode` or `entities`.
+- `[Telegram API]` Added `answerGuestQuery` to the API runtime for Bot API 10.0 Guest Mode support. Impact: callers can reply to guest queries in chats where the bot is not a member. Uses `InlineQueryResultArticle` as the result payload per Bot API 10.0 contract.
+- `[Updates]` Extended inbound update routing to recognize `guest_message` updates. Added `getAuthorizedTelegramGuestMessage`, guest flow action, execution plan, runtime handler, and prompt enqueue support. Unauthorized guest queries receive an "Access denied." reply via `answerGuestQuery`. Guest turns customize the agent-end delivery to use `answerGuestQuery` instead of normal reply transport. Impact: the bridge can now receive and route guest-mode mentions in group chats while preserving the existing private-message authorization model.
+- `[Runtime]` Added typing-loop skip for guest turns (`chatId === 0`) to avoid spurious `sendChatAction` errors in the status bar.
+- `[Tests]` Added regression tests for empty-text draft delivery, undefined-text draft delivery, rich preview with `parse_mode` and `entities`, guest query answers, guest extraction, guest flow classification, guest execution plan, guest deny reply, and guest message routing through the runtime.
+- `[Preview]` Updated `sendDraft` interface in `lib/preview.ts` to accept optional text and formatting options, keeping the preview pipeline aligned with the new API wrapper.
+
 ## 0.9.6: Runtime Adapter Positioning
 
 - `[Package]` Bumped package metadata to `0.9.6` and repositioned the package description from "Better Telegram DM bridge extension for π" to "Telegram Runtime Adapter for π". Impact: package metadata now reflects the runtime adapter/operator-console role rather than a narrow pipe metaphor.

package/README.md

@@ -6,7 +6,7 @@
 
 `pi-telegram` turns a private Telegram DM into a session-local operator console for π. It admits work, preserves context, streams readable replies, keeps busy sessions usable through queues, lets other extensions share one bot, and turns assistant-authored intent into native Telegram artifacts.
 
-This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008460b6c1ca036d92322f69d87f626be0fc`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
+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.
 
 ## Install
 
@@ -61,24 +61,11 @@ The first user to message the bot becomes the exclusive owner of the adapter. Me
 Most day-to-day controls live in the Telegram menu or π commands. A few important runtime knobs intentionally stay in environment variables because they affect bootstrap, networking, or transport limits before a menu can help:
 
 - **Bot token bootstrap**: `/telegram-setup` can prefill from `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY` when no token is already saved.
-- **HTTP/HTTPS proxy**: native `fetch` can use `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` when Node's environment proxy mode is enabled. Use `NODE_USE_ENV_PROXY=1` or start Node with `--use-env-proxy`.
+- **HTTP/HTTPS proxy**: native `fetch` can use `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` when Node's environment proxy mode is enabled. Use `NODE_USE_ENV_PROXY=1` or start Node with `--use-env-proxy`. SOCKS5 is not part of the zero-dependency core. If you need it, run a local HTTP-to-SOCKS bridge or system tunnel and point `HTTP_PROXY` / `HTTPS_PROXY` at the HTTP endpoint.
 - **Agent data root / temp location**: `PI_CODING_AGENT_DIR` changes the base agent directory used for `telegram.json`, locks, generated outbound-handler artifacts, and Telegram temp files. When unset, the adapter uses `~/.pi/agent`, so inbound Telegram files land in `~/.pi/agent/tmp/telegram`.
 - **Inbound file limit**: `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES` or `TELEGRAM_MAX_FILE_SIZE_BYTES` changes the default 50 MiB Telegram download limit.
 - **Outbound attachment limit**: `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` changes the default 50 MiB `telegram_attach` delivery limit.
 
-Proxy example:
-
-```bash
-export HTTPS_PROXY="http://127.0.0.1:8083"
-export HTTP_PROXY="http://127.0.0.1:8083"
-export NO_PROXY="localhost,127.0.0.1"
-export NODE_USE_ENV_PROXY=1
-
-pi
-```
-
-SOCKS5 is not part of the zero-dependency core. If you need it, run a local HTTP-to-SOCKS bridge or system tunnel and point `HTTP_PROXY` / `HTTPS_PROXY` at the HTTP endpoint.
-
 ## Use
 
 Once paired, chat with your bot in Telegram. Text, images, files, replies, edits, media groups, and configured handler output are forwarded into π as Telegram-originated turns.
@@ -134,7 +121,7 @@ The inline application menu is the primary operator surface. It exposes status,
 
 Messages sent while π is busy enter the prompt queue and are processed in order. Control actions and model-switch continuation turns use higher-priority lanes so operational commands can resume before normal prompts.
 
-The menu is the primary way to inspect and mutate the queue. Reactions are an extra shortcut when Telegram delivers `message_reaction` updates for the chat: `👍`, `⚡️`, `❤️`, `🕊`, and `🔥` promote waiting work; `👎`, `👻`, `💔`, `💩`, and `🗑` remove it. The set intentionally includes common default reactions first; premium-only reactions such as `🗑` are optional convenience, not the core queue UI. The same rules apply to text, voice, files, images, and media groups.
+The menu is the primary way to inspect and mutate the queue. Reactions are an extra shortcut when Telegram delivers `message_reaction` updates for the chat: `👍`, `⚡️`, `❤️`, `🕊`, and `🔥` promote waiting work; `👎`, `👻`, `💔`, `💩`, and `🗑` remove it. The same rules apply to text, voice, files, images, and media groups.
 
 ### Streaming and Telegram HTML rendering
 

package/docs/extension-sections.md

@@ -114,7 +114,7 @@ unregister();
 Sections are registered by normal pi extensions:
 
 ```ts
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerTelegramSection } from "@llblab/pi-telegram/lib/extension-sections.ts";
 
 export default function (pi: ExtensionAPI) {

package/index.ts

@@ -148,6 +148,7 @@ export default function (pi: Pi.ExtensionAPI) {
     downloadFile: downloadTelegramBridgeFile,
     editMessageText: editTelegramMessageText,
     answerCallbackQuery,
+    answerGuestQuery,
     prepareTempDir,
   } = Api.createDefaultTelegramBridgeApiRuntime({
     getBotToken: configStore.getBotToken,
@@ -333,6 +334,7 @@ export default function (pi: Pi.ExtensionAPI) {
     updateStatus,
     dispatchNextQueuedTelegramTurn,
     answerCallbackQuery,
+    answerGuestQuery,
     sendTextReply,
     setMyCommands,
     getCommands,
@@ -494,6 +496,7 @@ export default function (pi: Pi.ExtensionAPI) {
     sendMarkdownReply,
     sendTextReply,
     sendQueuedAttachments: queuedAttachmentSender,
+    answerGuestQuery,
     planOutboundReply: outboundReplyPlanner,
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     isCurrentOwner: lockOwnershipGuard.ownsContext,

package/lib/api.ts

@@ -151,12 +151,26 @@ export interface TelegramMessageReactionUpdated {
   date: number;
 }
 
+export interface TelegramGuestMessage {
+  message_id: number;
+  from?: TelegramUser;
+  chat: TelegramChat;
+  date: number;
+  text?: string;
+  caption?: string;
+  guest_query_id: string;
+  guest_bot_caller_user?: TelegramUser;
+  guest_bot_caller_chat?: TelegramChat;
+  reply_to_message?: TelegramMessage;
+}
+
 export interface TelegramUpdate {
   update_id: number;
   message?: TelegramMessage;
   edited_message?: TelegramMessage;
   callback_query?: TelegramCallbackQuery;
   message_reaction?: TelegramMessageReactionUpdated;
+  guest_message?: TelegramGuestMessage;
   deleted_business_messages?: { message_ids?: unknown };
 }
 
@@ -184,6 +198,15 @@ export type TelegramEditMessageTextBody = Record<string, unknown> & {
   parse_mode?: "HTML";
 };
 
+export type TelegramSendMessageDraftBody = Record<string, unknown> & {
+  chat_id: number;
+  draft_id: number;
+  text?: string;
+  parse_mode?: string;
+  entities?: unknown[];
+  message_thread_id?: number;
+};
+
 interface TelegramApiResponse<T> {
   ok: boolean;
   result?: T;
@@ -233,6 +256,7 @@ export interface TelegramApiClient {
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  answerGuestQuery?: (guestQueryId: string, text?: string) => Promise<void>;
 }
 
 export interface TelegramBridgeApiRuntimeDeps {
@@ -275,7 +299,12 @@ export interface TelegramBridgeApiRuntime {
   sendMessageDraft: (
     chatId: number,
     draftId: number,
-    text: string,
+    text?: string,
+    options?: {
+      parse_mode?: string;
+      entities?: unknown[];
+      message_thread_id?: number;
+    },
   ) => Promise<boolean>;
   sendMessage: (body: TelegramSendMessageBody) => Promise<TelegramSentMessage>;
   editMessageText: (
@@ -285,6 +314,7 @@ export interface TelegramBridgeApiRuntime {
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   prepareTempDir: () => Promise<number>;
 }
 
@@ -534,9 +564,7 @@ export async function fetchTelegramBotIdentity(
   botToken: string,
   fetchImpl: typeof fetch = fetch,
 ): Promise<TelegramBotIdentityResponse> {
-  const response = await fetchImpl(
-    `${TELEGRAM_API_BASE}/bot${botToken}/getMe`,
-  );
+  const response = await fetchImpl(`${TELEGRAM_API_BASE}/bot${botToken}/getMe`);
   return response.json() as Promise<TelegramBotIdentityResponse>;
 }
 
@@ -559,14 +587,11 @@ export async function callTelegramMultipart<TResponse>(
         form.set(key, value);
       }
       form.set(fileField, fileBlob, fileName);
-      return fetch(
-        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
-        {
-          method: "POST",
-          body: form,
-          signal: options?.signal,
-        },
-      );
+      return fetch(`${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`, {
+        method: "POST",
+        body: form,
+        signal: options?.signal,
+      });
     },
     options,
   );
@@ -732,13 +757,18 @@ export function createTelegramBridgeApiRuntime(
         }),
       "typing",
     ),
-    sendMessageDraft: (chatId, draftId, text) => {
-      if (text.length === 0) return Promise.resolve(false);
-      return callRecorded<boolean>("sendMessageDraft", {
+    sendMessageDraft: (chatId, draftId, text, options) => {
+      const body: Record<string, unknown> = {
         chat_id: chatId,
         draft_id: draftId,
-        text,
-      });
+      };
+      if (text !== undefined) body.text = text;
+      if (options?.parse_mode !== undefined)
+        body.parse_mode = options.parse_mode;
+      if (options?.entities !== undefined) body.entities = options.entities;
+      if (options?.message_thread_id !== undefined)
+        body.message_thread_id = options.message_thread_id;
+      return callRecorded<boolean>("sendMessageDraft", body);
     },
     sendMessage: (body) =>
       callRecorded<TelegramSentMessage>("sendMessage", body),
@@ -755,6 +785,18 @@ export function createTelegramBridgeApiRuntime(
     answerCallbackQuery: (callbackQueryId, text) => {
       return deps.client.answerCallbackQuery(callbackQueryId, text);
     },
+    answerGuestQuery: (guestQueryId, text) => {
+      const body: Record<string, unknown> = { guest_query_id: guestQueryId };
+      if (text !== undefined) {
+        body.result = {
+          type: "article",
+          id: "1",
+          title: text.length > 64 ? text.slice(0, 61) + "..." : text,
+          input_message_content: { message_text: text },
+        };
+      }
+      return callRecorded<void>("answerGuestQuery", body);
+    },
     prepareTempDir: () =>
       prepareTelegramTempDir(deps.tempDir, deps.tempFileMaxAgeMs),
   };

package/lib/pi.ts

@@ -15,7 +15,7 @@ import {
   type SessionStartEvent,
   type SlashCommandInfo,
   SettingsManager,
-} from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-coding-agent";
 
 export type {
   AgentEndEvent,

package/lib/polling.ts

@@ -20,6 +20,7 @@ export const TELEGRAM_ALLOWED_UPDATES = [
   "edited_message",
   "callback_query",
   "message_reaction",
+  "guest_message",
 ] as const;
 
 export function buildTelegramInitialSyncRequest(): {

package/lib/preview.ts

@@ -61,7 +61,12 @@ export interface TelegramPreviewRuntimeDeps<
   sendDraft: (
     chatId: number,
     draftId: number,
-    text: string,
+    text?: string,
+    options?: {
+      parse_mode?: string;
+      entities?: unknown[];
+      message_thread_id?: number;
+    },
   ) => Promise<unknown>;
   sendMessage: (
     chatId: number,
@@ -158,7 +163,12 @@ export interface TelegramPreviewControllerDeps<
   sendDraft: (
     chatId: number,
     draftId: number,
-    text: string,
+    text?: string,
+    options?: {
+      parse_mode?: string;
+      entities?: unknown[];
+      message_thread_id?: number;
+    },
   ) => Promise<unknown>;
   sendMessage: (
     chatId: number,

package/lib/prompts.ts

@@ -12,8 +12,8 @@ const SYSTEM_PROMPT_SUFFIX = `
 Telegram bridge extension is active.
 
 Inbound context:
-- \`[telegram]\` marks Telegram-originated messages.
-- \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
+- \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
+- \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
 - Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
 

package/lib/queue.ts

@@ -66,6 +66,7 @@ export interface TelegramQueueItemBase {
   kind: TelegramQueueItemKind;
   chatId: number;
   replyToMessageId: number;
+  guestQueryId?: string;
   queueOrder: number;
   queueLane: TelegramQueueLane;
   laneOrder: number;
@@ -113,6 +114,7 @@ export interface TelegramActiveTurnStore<
   clear: () => void;
   getChatId: () => number | undefined;
   getReplyToMessageId: () => number | undefined;
+  getGuestQueryId: () => string | undefined;
   getSourceMessageIds: () => number[] | undefined;
 }
 
@@ -203,6 +205,7 @@ export function createTelegramActiveTurnStore<
     },
     getChatId: () => activeTurn?.chatId,
     getReplyToMessageId: () => activeTurn?.replyToMessageId,
+    getGuestQueryId: () => activeTurn?.guestQueryId,
     getSourceMessageIds: () => activeTurn?.sourceMessageIds,
   };
 }
@@ -785,6 +788,7 @@ export interface TelegramAgentEndRuntimeDeps<
     text: string,
   ) => Promise<unknown>;
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  answerGuestQuery?: (guestQueryId: string, text?: string) => Promise<void>;
   planOutboundReply?: (
     markdown: string,
   ) => TelegramAgentEndOutboundReplyPlan<TReplyMarkup>;
@@ -832,6 +836,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   >["sendMarkdownReply"];
   sendTextReply: TelegramAgentEndRuntimeDeps<TTurn>["sendTextReply"];
   sendQueuedAttachments: (turn: TTurn) => Promise<void>;
+  answerGuestQuery?: TelegramAgentEndRuntimeDeps<TTurn>["answerGuestQuery"];
   planOutboundReply?: TelegramAgentEndRuntimeDeps<
     TTurn,
     TReplyMarkup
@@ -952,6 +957,7 @@ export function createTelegramAgentEndHook<
       sendMarkdownReply: deps.sendMarkdownReply,
       sendTextReply: deps.sendTextReply,
       sendQueuedAttachments: deps.sendQueuedAttachments,
+      answerGuestQuery: deps.answerGuestQuery,
       planOutboundReply: deps.planOutboundReply,
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
       getDefaultChatId: deps.getDefaultChatId,
@@ -1007,6 +1013,25 @@ export async function handleTelegramAgentEndRuntime<
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
     return;
   }
+  if (turn.guestQueryId) {
+    if (deps.isCurrentOwner && !deps.isCurrentOwner()) {
+      if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+      return;
+    }
+    if (assistant.errorMessage) {
+      await deps.answerGuestQuery?.(
+        turn.guestQueryId,
+        "Telegram bridge: π failed while processing the request.",
+      );
+      if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+      return;
+    }
+    if (finalText) {
+      await deps.answerGuestQuery?.(turn.guestQueryId, finalText);
+    }
+    if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
+    return;
+  }
   if (endPlan.shouldClearPreview) {
     await deps.clearPreview(turn.chatId);
   }

package/lib/routing.ts

@@ -6,6 +6,7 @@
 
 import * as OutboundHandlers from "./outbound-handlers.ts";
 import * as Commands from "./commands.ts";
+import { readFile } from "node:fs/promises";
 import type { TelegramConfigStore } from "./config.ts";
 import type { TelegramInboundHandlerRuntime } from "./inbound-handlers.ts";
 import * as Media from "./media.ts";
@@ -17,6 +18,7 @@ import type { TelegramBridgeRuntime } from "./runtime.ts";
 import * as TextGroups from "./text-groups.ts";
 import * as Turns from "./turns.ts";
 import * as Updates from "./updates.ts";
+import type { TelegramUser } from "./updates.ts";
 
 export type TelegramRoutedMessage = Updates.TelegramUpdateMessage &
   Media.TelegramMediaMessage &
@@ -80,6 +82,7 @@ export interface TelegramInboundRouteRuntimeDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   sendTextReply: (
     chatId: number,
     replyToMessageId: number,
@@ -364,6 +367,103 @@ export function createTelegramInboundRouteRuntime<
     ...deps.telegramQueueStore,
     updateStatus: deps.updateStatus,
   });
+  const handleAuthorizedTelegramGuestMessage = async (
+    guestMessage: Updates.TelegramGuestMessage & { from: TelegramUser },
+    ctx: TContext,
+  ): Promise<void> => {
+    const text = guestMessage.text ?? "";
+    const gm = guestMessage as unknown as Record<string, unknown>;
+    // Build telegram prefix with guest context
+    const fromRaw = gm.from as Record<string, unknown> | undefined;
+    const fromName =
+      (fromRaw?.username as string) ||
+      (fromRaw?.first_name as string) ||
+      "";
+    const chatRaw = gm.chat as Record<string, unknown>;
+    const chatTitle = chatRaw?.title as string | undefined;
+    const chatType = chatRaw?.type as string;
+    const prefixParts = ["telegram"];
+    if (fromName) prefixParts.push(`from:${fromName}`);
+    if (chatType !== "private" && chatTitle) {
+      prefixParts.push(`guest:${chatTitle}`);
+    }
+    const telegramPrefix = `[${prefixParts.join("|")}]`;
+    // Extract reply context
+    const replyMsg = gm.reply_to_message as Record<string, unknown> | undefined;
+    const replyText =
+      replyMsg
+        ? ((replyMsg.text as string) || (replyMsg.caption as string) || "").trim()
+        : "";
+    const replyFrom =
+      replyMsg
+        ? (replyMsg.from as Record<string, unknown> | undefined)?.username as string | undefined
+        : undefined;
+    // Download files, run inbound handlers
+    const guestMsg = guestMessage as unknown as Media.TelegramMediaMessage;
+    const files = await Media.downloadTelegramMessageFiles([guestMsg], {
+      downloadFile: deps.downloadFile,
+    });
+    const processed = await deps.inboundHandlerRuntime.process(files, text, ctx);
+    let rawText = processed.rawText || text;
+    // Append reply context after handler processing
+    if (replyText) {
+      const replyBlock = replyFrom
+        ? `[reply|from:${replyFrom}] ${replyText}`
+        : `[reply] ${replyText}`;
+      rawText = `${rawText}\n\n${replyBlock}`;
+    }
+    const promptText = Turns.buildTelegramTurnPrompt({
+      telegramPrefix,
+      rawText,
+      files,
+      promptFiles: processed.promptFiles,
+      handlerOutputs: processed.handlerOutputs,
+    });
+    const order = deps.bridgeRuntime.queue.allocateItemOrder();
+    const content: Queue.TelegramPromptContent[] = [
+      { type: "text", text: promptText },
+    ];
+    for (const file of processed.promptFiles) {
+      if (file.isImage && file.mimeType) {
+        try {
+          const buffer = await readFile(file.path);
+          content.push({
+            type: "image",
+            data: Buffer.from(buffer).toString("base64"),
+            mimeType: file.mimeType,
+          });
+        } catch {
+          // skip unreadable files
+        }
+      }
+    }
+    const guestTurn: Queue.PendingTelegramTurn = {
+      kind: "prompt",
+      chatId: 0,
+      replyToMessageId: 0,
+      guestQueryId: guestMessage.guest_query_id,
+      sourceMessageIds: [],
+      queueOrder: order,
+      queueLane: "default",
+      laneOrder: order,
+      queuedAttachments: [],
+      content,
+      historyText: Turns.formatTelegramTurnStatusSummary(
+        processed.rawText || text,
+        processed.promptFiles,
+        processed.handlerOutputs,
+      ),
+      statusSummary: Turns.truncateTelegramQueueSummary(
+        processed.rawText || text,
+      ),
+    };
+    const items = deps.telegramQueueStore.getQueuedItems();
+    deps.telegramQueueStore.setQueuedItems(
+      Queue.appendTelegramQueueItem(items, guestTurn),
+    );
+    deps.updateStatus(ctx);
+    deps.dispatchNextQueuedTelegramTurn(ctx);
+  };
   return Updates.createTelegramPairedUpdateRuntime<TContext, TUpdate>({
     getAllowedUserId: deps.configStore.getAllowedUserId,
     setAllowedUserId: deps.configStore.setAllowedUserId,
@@ -377,9 +477,11 @@ export function createTelegramInboundRouteRuntime<
     prioritizeQueuedTelegramTurnByMessageId:
       deps.queueMutationRuntime.prioritizeByMessageId,
     answerCallbackQuery: deps.answerCallbackQuery,
+    answerGuestQuery: deps.answerGuestQuery,
     handleAuthorizedTelegramCallbackQuery: callbackHandler,
     sendTextReply: deps.sendTextReply,
     handleAuthorizedTelegramMessage: textDispatch.handleMessage,
     handleAuthorizedTelegramEditedMessage: editRuntime.updateFromEditedMessage,
+    handleAuthorizedTelegramGuestMessage,
   });
 }

package/lib/runtime.ts

@@ -365,7 +365,8 @@ export function startTelegramTypingLoop(
   state: TelegramBridgeRuntimeState,
   deps: TelegramTypingLoopDeps,
 ): boolean {
-  if (state.typingInterval || deps.chatId === undefined) return false;
+  if (state.typingInterval || deps.chatId === undefined || deps.chatId === 0)
+    return false;
   const sendTyping = (): void => {
     void deps.sendTypingAction(deps.chatId as number);
   };

package/lib/updates.ts

@@ -130,10 +130,20 @@ export interface TelegramCallbackQuery {
   message?: TelegramUpdateMessage;
 }
 
+export interface TelegramGuestMessage {
+  guest_query_id: string;
+  chat: TelegramChat;
+  from?: TelegramUser;
+  message_id?: number;
+  text?: string;
+  reply_to_message?: TelegramUpdateMessage;
+}
+
 export interface TelegramUpdateRouting {
   message?: TelegramUpdateMessage;
   edited_message?: TelegramUpdateMessage;
   callback_query?: TelegramCallbackQuery;
+  guest_message?: TelegramGuestMessage;
 }
 
 export function getAuthorizedTelegramCallbackQuery(
@@ -178,6 +188,16 @@ export function getAuthorizedTelegramEditedMessage(
   return message;
 }
 
+export function getAuthorizedTelegramGuestMessage(
+  update: TelegramUpdateRouting,
+): TelegramGuestMessage | undefined {
+  const guestMessage = update.guest_message;
+  if (!guestMessage || !guestMessage.from || guestMessage.from.is_bot) {
+    return undefined;
+  }
+  return guestMessage;
+}
+
 // --- Flow ---
 
 export interface TelegramMessageReactionUpdated {
@@ -198,6 +218,7 @@ export type TelegramUpdateFlowAction<
     TelegramMessageReactionUpdated,
   TCallbackQuery extends TelegramCallbackQuery = TelegramCallbackQuery,
   TMessage extends TelegramUpdateMessage = TelegramUpdateMessage,
+  TGuestMessage extends TelegramGuestMessage = TelegramGuestMessage,
 > =
   | { kind: "ignore" }
   | { kind: "deleted"; messageIds: number[] }
@@ -216,6 +237,11 @@ export type TelegramUpdateFlowAction<
       kind: "edited-message";
       message: TMessage & { from: TelegramUser };
       authorization: TelegramAuthorizationState;
+    }
+  | {
+      kind: "guest";
+      guestMessage: TGuestMessage & { from: TelegramUser };
+      authorization: TelegramAuthorizationState;
     };
 
 export function buildTelegramUpdateFlowAction<
@@ -226,7 +252,8 @@ export function buildTelegramUpdateFlowAction<
 ): TelegramUpdateFlowAction<
   NonNullable<TUpdate["message_reaction"]>,
   NonNullable<TUpdate["callback_query"]>,
-  NonNullable<TUpdate["message"] | TUpdate["edited_message"]>
+  NonNullable<TUpdate["message"] | TUpdate["edited_message"]>,
+  NonNullable<TUpdate["guest_message"]>
 > {
   const deletedMessageIds = extractDeletedTelegramMessageIds(update);
   if (deletedMessageIds.length > 0) {
@@ -272,6 +299,19 @@ export function buildTelegramUpdateFlowAction<
       ),
     };
   }
+  const guestMessage = getAuthorizedTelegramGuestMessage(update);
+  if (guestMessage?.from) {
+    return {
+      kind: "guest",
+      guestMessage: guestMessage as NonNullable<TUpdate["guest_message"]> & {
+        from: TelegramUser;
+      },
+      authorization: getTelegramAuthorizationState(
+        guestMessage.from.id,
+        allowedUserId,
+      ),
+    };
+  }
   return { kind: "ignore" };
 }
 
@@ -282,6 +322,7 @@ export type TelegramUpdateExecutionPlan<
     TelegramMessageReactionUpdated,
   TCallbackQuery extends TelegramCallbackQuery = TelegramCallbackQuery,
   TMessage extends TelegramUpdateMessage = TelegramUpdateMessage,
+  TGuestMessage extends TelegramGuestMessage = TelegramGuestMessage,
 > =
   | { kind: "ignore" }
   | { kind: "deleted"; messageIds: number[] }
@@ -307,15 +348,31 @@ export type TelegramUpdateExecutionPlan<
       message: TMessage & { from: TelegramUser };
       shouldPair: boolean;
       shouldDeny: boolean;
+    }
+  | {
+      kind: "guest";
+      guestMessage: TGuestMessage & { from: TelegramUser };
+      shouldDeny: boolean;
     };
 
 export function buildTelegramUpdateExecutionPlan<
   TReactionUpdate extends TelegramMessageReactionUpdated,
   TCallbackQuery extends TelegramCallbackQuery,
   TMessage extends TelegramUpdateMessage,
+  TGuestMessage extends TelegramGuestMessage,
 >(
-  action: TelegramUpdateFlowAction<TReactionUpdate, TCallbackQuery, TMessage>,
-): TelegramUpdateExecutionPlan<TReactionUpdate, TCallbackQuery, TMessage> {
+  action: TelegramUpdateFlowAction<
+    TReactionUpdate,
+    TCallbackQuery,
+    TMessage,
+    TGuestMessage
+  >,
+): TelegramUpdateExecutionPlan<
+  TReactionUpdate,
+  TCallbackQuery,
+  TMessage,
+  TGuestMessage
+> {
   switch (action.kind) {
     case "ignore":
       return { kind: "ignore" };
@@ -345,6 +402,12 @@ export function buildTelegramUpdateExecutionPlan<
         shouldPair: action.authorization.kind === "pair",
         shouldDeny: action.authorization.kind === "deny",
       };
+    case "guest":
+      return {
+        kind: "guest",
+        guestMessage: action.guestMessage,
+        shouldDeny: action.authorization.kind === "deny",
+      };
   }
 }
 
@@ -387,6 +450,7 @@ export interface TelegramUpdateRuntimeDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -404,6 +468,10 @@ export interface TelegramUpdateRuntimeDeps<
     message: TMessage,
     ctx: TContext,
   ) => unknown;
+  handleAuthorizedTelegramGuestMessage?: (
+    guestMessage: TelegramGuestMessage & { from: TelegramUser },
+    ctx: TContext,
+  ) => Promise<void>;
 }
 
 export interface TelegramUpdateRuntimeControllerDeps<
@@ -431,6 +499,7 @@ export interface TelegramUpdateRuntimeControllerDeps<
     callbackQueryId: string,
     text?: string,
   ) => Promise<void>;
+  answerGuestQuery: (guestQueryId: string, text?: string) => Promise<void>;
   handleAuthorizedTelegramCallbackQuery: (
     query: TCallbackQuery,
     ctx: TContext,
@@ -448,6 +517,10 @@ export interface TelegramUpdateRuntimeControllerDeps<
     message: TMessage,
     ctx: TContext,
   ) => unknown;
+  handleAuthorizedTelegramGuestMessage?: (
+    guestMessage: TelegramGuestMessage & { from: TelegramUser },
+    ctx: TContext,
+  ) => Promise<void>;
 }
 
 export interface TelegramUpdateRuntimeController<
@@ -536,12 +609,15 @@ export function createTelegramPairedUpdateRuntime<
       updateStatus: deps.updateStatus,
     }).pairIfNeeded,
     answerCallbackQuery: deps.answerCallbackQuery,
+    answerGuestQuery: deps.answerGuestQuery,
     handleAuthorizedTelegramCallbackQuery:
       deps.handleAuthorizedTelegramCallbackQuery,
     sendTextReply: deps.sendTextReply,
     handleAuthorizedTelegramMessage: deps.handleAuthorizedTelegramMessage,
     handleAuthorizedTelegramEditedMessage:
       deps.handleAuthorizedTelegramEditedMessage,
+    handleAuthorizedTelegramGuestMessage:
+      deps.handleAuthorizedTelegramGuestMessage,
   });
 }
 
@@ -582,12 +658,15 @@ export function createTelegramUpdateRuntime<
         handleAuthorizedTelegramReactionUpdate: handleAuthorizedReactionUpdate,
         pairTelegramUserIfNeeded: deps.pairTelegramUserIfNeeded,
         answerCallbackQuery: deps.answerCallbackQuery,
+        answerGuestQuery: deps.answerGuestQuery,
         handleAuthorizedTelegramCallbackQuery:
           deps.handleAuthorizedTelegramCallbackQuery,
         sendTextReply: deps.sendTextReply,
         handleAuthorizedTelegramMessage: deps.handleAuthorizedTelegramMessage,
         handleAuthorizedTelegramEditedMessage:
           deps.handleAuthorizedTelegramEditedMessage,
+        handleAuthorizedTelegramGuestMessage:
+          deps.handleAuthorizedTelegramGuestMessage,
       }),
   };
 }
@@ -712,6 +791,22 @@ export async function executeTelegramUpdatePlan<
     await deps.handleAuthorizedTelegramCallbackQuery(plan.query, deps.ctx);
     return;
   }
+  if (plan.kind === "guest") {
+    if (plan.shouldDeny) {
+      await deps.answerGuestQuery(
+        plan.guestMessage.guest_query_id,
+        "Access denied.",
+      );
+      return;
+    }
+    if (deps.handleAuthorizedTelegramGuestMessage) {
+      await deps.handleAuthorizedTelegramGuestMessage(
+        plan.guestMessage,
+        deps.ctx,
+      );
+    }
+    return;
+  }
   const pairedNow = plan.shouldPair
     ? await deps.pairTelegramUserIfNeeded(plan.message.from.id, deps.ctx)
     : false;

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Telegram Runtime Adapter for π",
   "type": "module",
   "keywords": [
@@ -20,6 +23,9 @@
   "bugs": {
     "url": "https://github.com/llblab/pi-telegram/issues"
   },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "scripts": {
     "test": "node --experimental-strip-types --test tests/*.test.ts",
     "typecheck": "tsc --noEmit",
@@ -37,9 +43,6 @@
     "docs/",
     "screenshot.png"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -47,9 +50,9 @@
     "image": "https://github.com/llblab/pi-telegram/raw/main/screenshot.png"
   },
   "peerDependencies": {
-    "@mariozechner/pi-agent-core": "*",
-    "@mariozechner/pi-ai": "*",
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {