pi-telegram-plus 0.0.1

package/lib/text-split.ts

@@ -0,0 +1,59 @@
+/**
+ * Split text for Telegram's 4096-byte message limit.
+ * Handles UTF-8 boundaries safely and prefers word/newline breaks.
+ */
+
+const TELEGRAM_TEXT_LIMIT = 4096;
+const SAFE_TEXT_CHUNK = 3600;
+
+export function stripHtml(text: string): string {
+  return text
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+export function takeUtf8Prefix(text: string, maxBytes: number): { head: string; tail: string } {
+  let bytes = 0;
+  let end = 0;
+  for (const char of text) {
+    const next = bytes + Buffer.byteLength(char, "utf8");
+    if (next > maxBytes) break;
+    bytes = next;
+    end += char.length;
+  }
+  return { head: text.slice(0, end), tail: text.slice(end) };
+}
+
+export function splitTelegramText(text: string): string[] {
+  if (byteLength(text) <= TELEGRAM_TEXT_LIMIT) return [text];
+  const chunks: string[] = [];
+  let rest = text;
+
+  while (byteLength(rest) > TELEGRAM_TEXT_LIMIT) {
+    const { head: safeHead } = takeUtf8Prefix(rest, SAFE_TEXT_CHUNK);
+    let cut = Math.max(safeHead.lastIndexOf("\n"), safeHead.lastIndexOf(" "));
+    if (cut < 500) cut = safeHead.length;
+
+    let head = rest.slice(0, cut);
+    let tail = rest.slice(cut);
+    // Final guard: even after choosing a delimiter, keep the chunk byte-safe.
+    if (byteLength(head) > TELEGRAM_TEXT_LIMIT) {
+      const split = takeUtf8Prefix(rest, SAFE_TEXT_CHUNK);
+      head = split.head;
+      tail = split.tail;
+    }
+    chunks.push(head);
+    // Preserve exact content across chunks; do not trim leading whitespace/newlines.
+    rest = tail;
+  }
+  if (rest) chunks.push(rest);
+  return chunks;
+}

package/lib/types.ts

@@ -0,0 +1,123 @@
+import type { AgentSession, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+export type TelegramRenderLevel = "hidden" | "brief" | "full";
+export type TelegramMessageMode = "queue" | "steer";
+
+export const RENDER_LEVELS: readonly TelegramRenderLevel[] = ["hidden", "brief", "full"] as const;
+export const MODE_VALUES: readonly TelegramMessageMode[] = ["queue", "steer"] as const;
+
+export type TelegramConfigStore = {
+  version: 2;
+  global?: TelegramConfig;
+  workspaces?: TelegramWorkspaceConfig[];
+};
+
+export type TelegramWorkspaceConfig = {
+  path: string;
+  config: TelegramConfig;
+};
+
+export type ResolvedTelegramConfig = {
+  store: TelegramConfigStore;
+  scope: "global" | "workspace";
+  workspacePath?: string;
+  config: TelegramConfig;
+};
+
+export type TelegramConfig = {
+  botToken?: string;
+  botUsername?: string;
+  telegramEnabled?: boolean;
+  allowedUserId?: number;
+  /** Last chat that interacted with the bot. */
+  activeChatId?: number;
+  lastUpdateId?: number;
+  /** How to render tool executions in Telegram. */
+  tool?: TelegramRenderLevel;
+  /** How to render thinking blocks in Telegram. */
+  thinking?: TelegramRenderLevel;
+  /** How to handle incoming messages while the agent is running.
+   *  "steer" — messages inject into the current turn via streamingBehavior (default).
+   *  "queue" — messages wait for the current turn to finish.
+   */
+  messageMode?: TelegramMessageMode;
+  /** Number of retries for failed Telegram API calls (0 = no retry, default 3). */
+  retryCount?: number;
+};
+
+export type TelegramPhotoSize = {
+  file_id: string;
+  file_size?: number;
+};
+
+export type TelegramDocument = {
+  file_id: string;
+  file_name?: string;
+  mime_type?: string;
+};
+
+export type TelegramMessage = {
+  message_id: number;
+  text?: string;
+  caption?: string;
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  video?: TelegramDocument;
+  audio?: TelegramDocument;
+  voice?: TelegramDocument;
+  animation?: TelegramDocument;
+  sticker?: TelegramDocument;
+  chat?: { id?: number };
+  from?: { id?: number };
+  reply_to_message?: { message_id?: number };
+};
+
+export type TelegramCallbackQuery = {
+  id: string;
+  data?: string;
+  message?: TelegramMessage;
+  from?: { id?: number };
+};
+
+export type TelegramUpdate = {
+  update_id: number;
+  message?: TelegramMessage;
+  callback_query?: TelegramCallbackQuery;
+};
+
+export type TelegramButton = { text: string; value: string };
+export type PendingInputResolver = (value: string | boolean | undefined) => void;
+
+export type TelegramSentMessage = { message_id: number };
+
+export type TelegramTurn = {
+  chatId: number;
+  /** Message to edit in-place for callback-button initiated turns. */
+  replaceMessageId?: number;
+  queuedAttachments: Array<{ path: string; fileName: string }>;
+  attachmentsSent?: boolean;
+};
+
+export type TelegramTransport = {
+  removeInlineKeyboard(chatId: number, messageId: number): Promise<void>;
+  sendText(chatId: number, text: string): Promise<TelegramSentMessage[]>;
+  sendButtons(
+    chatId: number,
+    text: string,
+    rows: TelegramButton[][],
+  ): Promise<TelegramSentMessage>;
+  editText(chatId: number, messageId: number, text: string): Promise<void>;
+  editButtons(chatId: number, messageId: number, text: string, rows: TelegramButton[][]): Promise<void>;
+  answerCallbackQuery(callbackQueryId: string, text?: string): Promise<void>;
+  deleteMessage(chatId: number, messageId: number): Promise<void>;
+  sendDocument(chatId: number, path: string, caption?: string, signal?: AbortSignal): Promise<void>;
+  sendPhoto(chatId: number, data: string, caption?: string, isPath?: boolean, signal?: AbortSignal): Promise<void>;
+  sendChatAction(chatId: number, action: string): Promise<void>;
+};
+
+export type CapturedAgentSession = AgentSession & {
+  extensionRunner: AgentSession["extensionRunner"] & {
+    getUIContext(): ExtensionUIContext;
+    setUIContext(ui?: ExtensionUIContext): void;
+  };
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json.schemastore.org/package",
+  "name": "pi-telegram-plus",
+  "version": "0.0.1",
+  "description": "Full Telegram control of pi coding agent — commands, menus, interactive UI, model management, and more",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "telegram",
+    "coding-agent",
+    "remote-control"
+  ],
+  "license": "MIT",
+  "author": "jalyfeng",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "index.ts",
+    "lib/**/*.ts",
+    "!lib/__tests__/",
+    "pi-host.d.ts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "image": "https://pi.dev/logo-auto.svg",
+    "video": ""
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jalyfeng/pi-telegram-plus"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "dependencies": {
+    "marked": "^18.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/pi-host.d.ts

@@ -0,0 +1,8 @@
+declare module "@earendil-works/pi-ai" {
+  export type Model = {
+    id: string;
+    name?: string;
+    provider?: string;
+    [key: string]: unknown;
+  };
+}