@llblab/pi-telegram 0.20.5 → 0.21.0

package/lib/lifecycle.ts

@@ -6,10 +6,13 @@
 
 import type {
   AgentEndEvent,
+  AgentSettledEvent,
   AgentStartEvent,
+  AssistantMessageEvent,
   BeforeAgentStartEvent,
   ExtensionAPI,
   ExtensionContext,
+  InputEvent,
   SessionBeforeCompactEvent,
   SessionCompactEvent,
   SessionShutdownEvent,
@@ -47,6 +50,7 @@ type TelegramLifecycleModel = ExtensionContext["model"];
 type TelegramLifecycleMessage = AgentEndEvent["messages"][number];
 
 export interface TelegramLifecycleRegistrationDeps {
+  onInput?: (event: InputEvent, ctx: ExtensionContext) => Promise<void> | void;
   onSessionStart: (
     event: SessionStartEvent,
     ctx: ExtensionContext,
@@ -92,10 +96,17 @@ export interface TelegramLifecycleRegistrationDeps {
     ctx: ExtensionContext,
   ) => Promise<void>;
   onMessageUpdate: (
-    event: { message: TelegramLifecycleMessage },
+    event: {
+      message: TelegramLifecycleMessage;
+      assistantMessageEvent?: AssistantMessageEvent;
+    },
     ctx: ExtensionContext,
   ) => Promise<void>;
   onAgentEnd: (event: AgentEndEvent, ctx: ExtensionContext) => Promise<void>;
+  onAgentSettled?: (
+    event: AgentSettledEvent,
+    ctx: ExtensionContext,
+  ) => Promise<void> | void;
 }
 
 export interface TelegramSessionLifecycleHooks {
@@ -160,6 +171,7 @@ export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   ) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
   recordRuntimeEvent?: (category: string, error: unknown) => void;
+  onCompactionAbandoned?: () => void;
   timeoutMs?: number;
   setTimer?: (callback: () => void, ms: number) => TelegramLifecycleTimer;
   clearTimer?: (timer: TelegramLifecycleTimer) => void;
@@ -210,6 +222,7 @@ export function createTelegramCompactionObserverRuntime<TContext>(
           "compact",
           new Error("Compaction observer timed out"),
         );
+        deps.onCompactionAbandoned?.();
         requestDispatch();
       }, timeoutMs);
       unrefTelegramLifecycleTimer(fallbackTimer);
@@ -253,11 +266,11 @@ export function createTelegramMessageActivityTypingHooks<
   const ensureTyping = (ctx: TContext): void => {
     if (deps.hasActiveTurn()) deps.startTypingLoop(ctx);
   };
-  const handleMessageActivity = async (
+  const handleMessageActivity = async <TEvent>(
     phase: "start" | "update",
-    event: Parameters<TelegramLifecycleRegistrationDeps["onMessageStart"]>[0],
+    event: TEvent,
     ctx: ExtensionContext,
-    inner: TelegramLifecycleRegistrationDeps["onMessageStart"],
+    inner: (event: TEvent, ctx: ExtensionContext) => Promise<void>,
   ): Promise<void> => {
     const typedCtx = ctx as TContext;
     ensureTyping(typedCtx);
@@ -318,6 +331,9 @@ export function registerTelegramLifecycleHooks(
   pi: ExtensionAPI,
   deps: TelegramLifecycleRegistrationDeps,
 ): void {
+  pi.on("input", async (event, ctx) => {
+    await deps.onInput?.(event, ctx);
+  });
   pi.on("session_start", async (event, ctx) => {
     await deps.onSessionStart(event, ctx);
   });
@@ -357,4 +373,7 @@ export function registerTelegramLifecycleHooks(
   pi.on("agent_end", async (event, ctx) => {
     await deps.onAgentEnd(event, ctx);
   });
+  pi.on("agent_settled", async (event, ctx) => {
+    await deps.onAgentSettled?.(event, ctx);
+  });
 }

package/lib/model.ts

@@ -20,7 +20,8 @@ export type ThinkingLevel =
   | "low"
   | "medium"
   | "high"
-  | "xhigh";
+  | "xhigh"
+  | "max";
 
 export interface ScopedTelegramModel<TModel extends MenuModel = MenuModel> {
   model: TModel;
@@ -34,6 +35,7 @@ export const THINKING_LEVELS: readonly ThinkingLevel[] = [
   "medium",
   "high",
   "xhigh",
+  "max",
 ];
 
 export interface CurrentModelStore<

package/lib/outbound-markup.ts

@@ -64,6 +64,36 @@ function isTopLevelClosingFence(
   );
 }
 
+function collectPairedTelegramVoiceActionBody(
+  markdown: string,
+  bodyStart: number,
+  commentContent: string,
+): { content: string; end: number } | undefined {
+  const normalizedContent = commentContent.trim();
+  if (
+    !normalizedContent.startsWith("telegram_voice") ||
+    !isTelegramActionCommentContent(commentContent)
+  ) {
+    return undefined;
+  }
+  let offset = bodyStart;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    if (line === "<!-- /telegram_voice -->") {
+      const body = markdown.slice(bodyStart, offset).trim();
+      if (!body) return undefined;
+      return {
+        content: `${commentContent.trimEnd()}\n${body}`,
+        end: lineEnd,
+      };
+    }
+    if (line.startsWith("<!--")) return undefined;
+    offset = lineEnd;
+  }
+  return undefined;
+}
+
 function collectInlineClosedTelegramActionBody(
   markdown: string,
   bodyStart: number,
@@ -117,14 +147,19 @@ export function collectTopLevelHtmlComments(markdown: string): {
       const closesOnOpeningLine = closeIndex < lineEnd;
       const hasOnlyWhitespaceAfterClose =
         line.slice(closeColumn + 3).trim() === "";
-      const inlineBody =
+      const pairedVoiceBody =
         closesOnOpeningLine && hasOnlyWhitespaceAfterClose
+          ? collectPairedTelegramVoiceActionBody(markdown, lineEnd, content)
+          : undefined;
+      const inlineBody =
+        !pairedVoiceBody && closesOnOpeningLine && hasOnlyWhitespaceAfterClose
           ? collectInlineClosedTelegramActionBody(markdown, lineEnd, content)
           : undefined;
-      if (inlineBody) {
-        end = inlineBody.end;
+      const recoveredBody = pairedVoiceBody ?? inlineBody;
+      if (recoveredBody) {
+        end = recoveredBody.end;
         raw = markdown.slice(offset, end);
-        content = inlineBody.content;
+        content = recoveredBody.content;
       }
       comments.push({ raw, content, start: offset, end });
       offset = getMarkdownLineEnd(markdown, end);

package/lib/pi.ts

@@ -4,13 +4,16 @@
  * Owns direct pi SDK imports and exposes narrow bridge-facing helpers/types for the extension composition layer
  */
 
+import type { AssistantMessageEvent } from "@earendil-works/pi-ai";
 import {
   type AgentEndEvent,
+  type AgentSettledEvent,
   type AgentStartEvent,
   type BeforeAgentStartEvent,
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
+  type InputEvent,
   type SessionBeforeCompactEvent,
   type SessionCompactEvent,
   type SessionShutdownEvent,
@@ -21,11 +24,14 @@ import {
 
 export type {
   AgentEndEvent,
+  AgentSettledEvent,
   AgentStartEvent,
+  AssistantMessageEvent,
   BeforeAgentStartEvent,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,
+  InputEvent,
   SessionBeforeCompactEvent,
   SessionCompactEvent,
   SessionShutdownEvent,
@@ -68,10 +74,7 @@ export type PiRunMode = "tui" | "rpc" | "json" | "print";
 
 function isPiRunMode(value: unknown): value is PiRunMode {
   return (
-    value === "tui" ||
-    value === "rpc" ||
-    value === "json" ||
-    value === "print"
+    value === "tui" || value === "rpc" || value === "json" || value === "print"
   );
 }
 
@@ -99,6 +102,18 @@ export function formatPollingStartBlockedByRunMode(ctx: unknown): string {
     : "Telegram polling is unavailable in this Pi run mode.";
 }
 
+export function getSessionCompactionReason(
+  event: unknown,
+): "manual" | "threshold" | "overflow" | "unknown" {
+  const reason =
+    event && typeof event === "object" && "reason" in event
+      ? (event as { reason?: unknown }).reason
+      : undefined;
+  return reason === "manual" || reason === "threshold" || reason === "overflow"
+    ? reason
+    : "unknown";
+}
+
 export type PiSendUserMessageOptions = NonNullable<
   Parameters<ExtensionAPI["sendUserMessage"]>[1]
 >;
@@ -124,7 +139,8 @@ export function createExtensionApiRuntimePorts(
   >,
 ): PiExtensionApiRuntimePorts {
   return {
-    sendUserMessage: (content, options) => api.sendUserMessage(content, options),
+    sendUserMessage: (content, options) =>
+      api.sendUserMessage(content, options),
     exec: (command, args, options) => api.exec(command, args, options),
     getCommands: () => api.getCommands(),
     getThinkingLevel: () => api.getThinkingLevel(),

package/lib/prompts.ts

@@ -16,7 +16,7 @@ Telegram bridge available. Do not use it from local/TUI prompts unless explicitl
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload.`;
+Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload. For voice use a top-level HTML action: \`<!-- telegram_voice: Speak this. -->\`, multiline \`<!-- telegram_voice lang=ru\nSpeak this.\n-->\`, or paired \`<!-- telegram_voice lang=ru -->\nSpeak this.\n<!-- /telegram_voice -->\`.`;
 
 function buildTelegramHelpText(profileName?: string): string {
   const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
@@ -37,7 +37,8 @@ How to answer Telegram turns:
 Assistant-authored Telegram actions:
 - \`telegram_voice\` and \`telegram_button\` are hidden top-level HTML comments, not Pi tools.
 - Put action comments at column zero, outside code, quotes, lists, and indented examples.
-- Voice forms: \`<!-- telegram_voice text="Short summary" -->\` or \`<!-- telegram_voice: Short summary -->\`.
+- Voice forms: \`<!-- telegram_voice text="Short summary" -->\`, \`<!-- telegram_voice: Short summary -->\`, multiline \`<!-- telegram_voice lang=ru\nShort summary.\n-->\`, or paired \`<!-- telegram_voice lang=ru -->\nShort summary.\n<!-- /telegram_voice -->\`.
+- Keep the complete action at top level and include a non-empty voice payload.
 - Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
 - Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
 - Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.

package/lib/routing.ts

@@ -21,10 +21,82 @@ import * as TextGroups from "./text-groups.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import * as Turns from "./turns.ts";
 
-function formatTelegramPromptPeer(user: { id?: unknown; username?: unknown } | undefined): string | undefined {
-  if (!user) return undefined;
-  if (typeof user.username === "string" && user.username.length > 0) return user.username;
-  return typeof user.id === "number" ? String(user.id) : undefined;
+interface TelegramPromptPeerView {
+  id?: unknown;
+  is_bot?: unknown;
+  username?: unknown;
+  first_name?: unknown;
+  last_name?: unknown;
+  title?: unknown;
+}
+
+function formatTelegramPromptPeer(
+  peer: TelegramPromptPeerView | undefined,
+): string | undefined {
+  if (!peer) return undefined;
+  if (typeof peer.username === "string" && peer.username.length > 0) {
+    return peer.username;
+  }
+  const displayName = [peer.first_name, peer.last_name]
+    .filter(
+      (part): part is string =>
+        typeof part === "string" && part.length > 0,
+    )
+    .join(" ");
+  if (displayName) return displayName;
+  if (typeof peer.title === "string" && peer.title.length > 0) {
+    return peer.title;
+  }
+  return typeof peer.id === "number" ? String(peer.id) : undefined;
+}
+
+function isTelegramPromptOwnerPeer(
+  peer: TelegramPromptPeerView | undefined,
+  ownerUserId: number | undefined,
+): boolean {
+  return ownerUserId !== undefined && peer?.id === ownerUserId;
+}
+
+function isTelegramPromptBotPeer(
+  peer: TelegramPromptPeerView | undefined,
+): boolean {
+  return peer?.is_bot === true;
+}
+
+export function resolveTelegramGuestPromptPeer(input: {
+  chatType?: string;
+  chat?: TelegramPromptPeerView;
+  from?: TelegramPromptPeerView;
+  replyFrom?: TelegramPromptPeerView;
+  guestBotCallerUser?: TelegramPromptPeerView;
+  guestBotCallerChat?: TelegramPromptPeerView;
+  ownerUserId?: number;
+}): string | undefined {
+  if (input.chatType !== "private") {
+    return formatTelegramPromptPeer(input.chat);
+  }
+  if (
+    !isTelegramPromptOwnerPeer(input.from, input.ownerUserId) &&
+    !isTelegramPromptBotPeer(input.from)
+  ) {
+    return formatTelegramPromptPeer(input.from);
+  }
+  for (const candidate of [
+    input.chat,
+    input.guestBotCallerUser,
+    input.guestBotCallerChat,
+    input.replyFrom,
+  ]) {
+    if (
+      isTelegramPromptOwnerPeer(candidate, input.ownerUserId) ||
+      isTelegramPromptBotPeer(candidate)
+    ) {
+      continue;
+    }
+    const peer = formatTelegramPromptPeer(candidate);
+    if (peer) return peer;
+  }
+  return undefined;
 }
 
 function appendTelegramSourceAttachmentSection(
@@ -1812,22 +1884,43 @@ export function createTelegramInboundRouteRuntime<
     const gm = guestMessage as unknown as Record<string, unknown>;
     // Build telegram prefix with guest context
     const chatRaw = gm.chat as Record<string, unknown>;
-    const chatTitle = chatRaw?.title as string | undefined;
     const chatType = chatRaw?.type as string;
     const fromRaw = gm.from as Record<string, unknown> | undefined;
     const replyMsg = gm.reply_to_message as Record<string, unknown> | undefined;
     const replyFromRaw = replyMsg?.from as Record<string, unknown> | undefined;
-    const fromPeer = formatTelegramPromptPeer(fromRaw);
+    const guestBotCallerUser = gm.guest_bot_caller_user as
+      | Record<string, unknown>
+      | undefined;
+    const guestBotCallerChat = gm.guest_bot_caller_chat as
+      | Record<string, unknown>
+      | undefined;
+    const ownerUserId = deps.configStore.getAllowedUserId();
     const replyPeer = formatTelegramPromptPeer(replyFromRaw);
-    const fromIsOwner = fromRaw?.id === deps.configStore.getAllowedUserId();
-    const guestPeer = chatType === "private" && fromIsOwner && replyPeer
-      ? replyPeer
-      : fromPeer;
+    const guestPeer = resolveTelegramGuestPromptPeer({
+      chatType,
+      chat: chatRaw,
+      from: fromRaw,
+      replyFrom: replyFromRaw,
+      guestBotCallerUser,
+      guestBotCallerChat,
+      ownerUserId,
+    });
     const prefixParts = ["telegram"];
-    if (chatType !== "private" && chatTitle) {
-      prefixParts.push(`guest:${chatTitle}`);
-    } else if (chatType === "private" && guestPeer) {
+    if (guestPeer) {
       prefixParts.push(`guest:${guestPeer}`);
+    } else if (chatType === "private") {
+      deps.recordRuntimeEvent?.(
+        "guest",
+        new Error("Private Guest Mode remote peer could not be resolved"),
+        {
+          phase: "peer-attribution",
+          chatId: typeof chatRaw?.id === "number" ? chatRaw.id : undefined,
+          fromId: typeof fromRaw?.id === "number" ? fromRaw.id : undefined,
+          hasReplyFrom: !!replyFromRaw,
+          hasCallerUser: !!guestBotCallerUser,
+          hasCallerChat: !!guestBotCallerChat,
+        },
+      );
     }
     const telegramPrefix = `[${prefixParts.join("|")}]`;
     // Extract reply context

package/lib/sections.ts

@@ -25,7 +25,7 @@ export type TelegramSectionCallbackResult = "handled" | "pass";
 export interface TelegramSectionView {
   text: string;
   /**
-   * Source format for companion section content.
+   * Source format for extension-provided section content.
    * Defaults to "html" for explicit Telegram UI markup; use "markdown"
    * when a section naturally owns Markdown content, or "plain" for text.
    */

package/lib/status.ts

@@ -428,10 +428,10 @@ function getOrCreateTelegramStatusLineProviderRegistry(): Map<
 }
 
 /**
- * Register a compact companion-extension line for the Telegram status menu.
+ * Register a compact extension-provided line for the Telegram status menu.
  *
  * Providers are synchronous and should return undefined when their line is not
- * relevant for the active model. Errors are isolated so optional companion
+ * relevant for the active model. Errors are isolated so optional extension
  * status cannot break the core Telegram menu.
  */
 export function registerTelegramStatusLineProvider(

package/lib/updates.ts

@@ -1248,7 +1248,7 @@ export interface TelegramUpdateHandlerRegistry {
   /**
    * Run all registered handlers against an update.
    *
-   * Used by pi-telegram's polling runtime; companion extensions should call
+   * Used by pi-telegram's polling runtime; extension consumers should call
    * {@link registerTelegramUpdateHandler} or `add` instead of dispatching directly.
    */
   dispatch: (update: unknown) => Promise<TelegramUpdateHandlerVerdict>;
@@ -1297,7 +1297,7 @@ function getOrCreateUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
 
 /**
  * Called by pi-telegram's own runtime to obtain the registry it dispatches
- * through. Companion extensions should not call this; use
+ * through. Extension consumers should not call this; use
  * {@link registerTelegramUpdateHandler} instead.
  */
 export function getTelegramUpdateHandlerRegistry(): TelegramUpdateHandlerRegistry {
@@ -1328,8 +1328,8 @@ export function createTelegramUpdateHandle<TUpdate, TContext>(
  * Register a handler that runs before pi-telegram routes a Telegram update
  * through its built-in handlers.
  *
- * This is the low-level public surface for companion extensions that share
- * the same bot and pi process with pi-telegram.
+ * This is the low-level public surface for extensions that share the same bot
+ * and Pi process with pi-telegram.
  */
 export function registerTelegramUpdateHandler(
   handler: TelegramUpdateHandler,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -48,6 +48,8 @@
     ".": "./index.ts",
     "./inbound": "./api/inbound.ts",
     "./outbound": "./api/outbound.ts",
+    "./delivery": "./api/delivery.ts",
+    "./activity": "./api/activity.ts",
     "./updates": "./api/updates.ts",
     "./commands": "./api/commands.ts",
     "./sections": "./api/sections.ts",
@@ -62,9 +64,9 @@
     "image": "https://github.com/llblab/pi-telegram/raw/main/screenshot.png"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": "*",
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-agent-core": ">=0.80.6",
+    "@earendil-works/pi-ai": ">=0.80.6",
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {