@llblab/pi-telegram 0.2.0

package/lib/replies.ts

@@ -0,0 +1,313 @@
+/**
+ * Telegram reply and preview domain helpers
+ * Owns preview text decisions, preview runtime behavior, rendered-message delivery, and plain or markdown reply sending
+ */
+
+import type { TelegramRenderedChunk, TelegramRenderMode } from "./rendering.ts";
+
+// --- Preview ---
+
+export interface TelegramPreviewStateLike {
+  mode: "draft" | "message";
+  draftId?: number;
+  messageId?: number;
+  pendingText: string;
+  lastSentText: string;
+}
+
+export interface TelegramPreviewRuntimeState extends TelegramPreviewStateLike {
+  flushTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface TelegramPreviewRuntimeDeps {
+  getState: () => TelegramPreviewRuntimeState | undefined;
+  setState: (state: TelegramPreviewRuntimeState | undefined) => void;
+  clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
+  maxMessageLength: number;
+  renderPreviewText: (markdown: string) => string;
+  getDraftSupport: () => "unknown" | "supported" | "unsupported";
+  setDraftSupport: (support: "unknown" | "supported" | "unsupported") => void;
+  allocateDraftId: () => number;
+  sendDraft: (chatId: number, draftId: number, text: string) => Promise<void>;
+  sendMessage: (
+    chatId: number,
+    text: string,
+  ) => Promise<TelegramSentMessageLike>;
+  editMessageText: (
+    chatId: number,
+    messageId: number,
+    text: string,
+  ) => Promise<void>;
+  renderTelegramMessage: (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) => TelegramRenderedChunk[];
+  sendRenderedChunks: (
+    chatId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+  editRenderedMessage: (
+    chatId: number,
+    messageId: number,
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+}
+
+export function buildTelegramPreviewFlushText(options: {
+  state: TelegramPreviewStateLike;
+  maxMessageLength: number;
+  renderPreviewText: (markdown: string) => string;
+}): string | undefined {
+  const rawText = options.state.pendingText.trim();
+  const previewText = options.renderPreviewText(rawText).trim();
+  if (!previewText || previewText === options.state.lastSentText) {
+    return undefined;
+  }
+  return previewText.length > options.maxMessageLength
+    ? previewText.slice(0, options.maxMessageLength)
+    : previewText;
+}
+
+export function buildTelegramPreviewFinalText(
+  state: TelegramPreviewStateLike,
+): string | undefined {
+  const finalText = (state.pendingText.trim() || state.lastSentText).trim();
+  return finalText || undefined;
+}
+
+export function shouldUseTelegramDraftPreview(options: {
+  draftSupport: "unknown" | "supported" | "unsupported";
+}): boolean {
+  return options.draftSupport !== "unsupported";
+}
+
+export async function clearTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  deps.clearScheduledFlush(state);
+  deps.setState(undefined);
+  if (state.mode !== "draft" || state.draftId === undefined) return;
+  try {
+    await deps.sendDraft(chatId, state.draftId, "");
+  } catch {
+    // ignore
+  }
+}
+
+export async function flushTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<void> {
+  const state = deps.getState();
+  if (!state) return;
+  state.flushTimer = undefined;
+  const truncated = buildTelegramPreviewFlushText({
+    state,
+    maxMessageLength: deps.maxMessageLength,
+    renderPreviewText: deps.renderPreviewText,
+  });
+  if (!truncated) return;
+  if (shouldUseTelegramDraftPreview({ draftSupport: deps.getDraftSupport() })) {
+    const draftId = state.draftId ?? deps.allocateDraftId();
+    state.draftId = draftId;
+    try {
+      await deps.sendDraft(chatId, draftId, truncated);
+      deps.setDraftSupport("supported");
+      state.mode = "draft";
+      state.lastSentText = truncated;
+      return;
+    } catch {
+      deps.setDraftSupport("unsupported");
+    }
+  }
+  if (state.messageId === undefined) {
+    const sent = await deps.sendMessage(chatId, truncated);
+    state.messageId = sent.message_id;
+    state.mode = "message";
+    state.lastSentText = truncated;
+    return;
+  }
+  await deps.editMessageText(chatId, state.messageId, truncated);
+  state.mode = "message";
+  state.lastSentText = truncated;
+}
+
+export async function finalizeTelegramPreview(
+  chatId: number,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const finalText = buildTelegramPreviewFinalText(state);
+  if (!finalText) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendMessage(chatId, finalText);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  deps.setState(undefined);
+  return state.messageId !== undefined;
+}
+
+export async function finalizeTelegramMarkdownPreview(
+  chatId: number,
+  markdown: string,
+  deps: TelegramPreviewRuntimeDeps,
+): Promise<boolean> {
+  const state = deps.getState();
+  if (!state) return false;
+  await flushTelegramPreview(chatId, deps);
+  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
+  if (chunks.length === 0) {
+    await clearTelegramPreview(chatId, deps);
+    return false;
+  }
+  if (state.mode === "draft") {
+    await deps.sendRenderedChunks(chatId, chunks);
+    await clearTelegramPreview(chatId, deps);
+    return true;
+  }
+  if (state.messageId === undefined) return false;
+  await deps.editRenderedMessage(chatId, state.messageId, chunks);
+  deps.setState(undefined);
+  return true;
+}
+
+// --- Delivery ---
+
+export interface TelegramSentMessageLike {
+  message_id: number;
+}
+
+export interface TelegramReplyDeliveryDeps<TReplyMarkup> {
+  sendMessage: (body: {
+    chat_id: number;
+    text: string;
+    parse_mode?: "HTML";
+    reply_markup?: TReplyMarkup;
+  }) => Promise<TelegramSentMessageLike>;
+  editMessage: (body: {
+    chat_id: number;
+    message_id: number;
+    text: string;
+    parse_mode?: "HTML";
+    reply_markup?: TReplyMarkup;
+  }) => Promise<void>;
+}
+
+export interface TelegramReplyTransport<TReplyMarkup> {
+  sendRenderedChunks: (
+    chatId: number,
+    chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>;
+  editRenderedMessage: (
+    chatId: number,
+    messageId: number,
+    chunks: TelegramRenderedChunk[],
+    options?: { replyMarkup?: TReplyMarkup },
+  ) => Promise<number | undefined>;
+}
+
+export function buildTelegramReplyTransport<TReplyMarkup>(
+  deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
+): TelegramReplyTransport<TReplyMarkup> {
+  return {
+    sendRenderedChunks: async (chatId, chunks, options) => {
+      return sendTelegramRenderedChunks(chatId, chunks, deps, options);
+    },
+    editRenderedMessage: async (chatId, messageId, chunks, options) => {
+      return editTelegramRenderedMessage(
+        chatId,
+        messageId,
+        chunks,
+        deps,
+        options,
+      );
+    },
+  };
+}
+
+export async function sendTelegramRenderedChunks<TReplyMarkup>(
+  chatId: number,
+  chunks: TelegramRenderedChunk[],
+  deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
+  options?: { replyMarkup?: TReplyMarkup },
+): Promise<number | undefined> {
+  let lastMessageId: number | undefined;
+  for (const [index, chunk] of chunks.entries()) {
+    const sent = await deps.sendMessage({
+      chat_id: chatId,
+      text: chunk.text,
+      parse_mode: chunk.parseMode,
+      reply_markup:
+        index === chunks.length - 1 ? options?.replyMarkup : undefined,
+    });
+    lastMessageId = sent.message_id;
+  }
+  return lastMessageId;
+}
+
+export async function editTelegramRenderedMessage<TReplyMarkup>(
+  chatId: number,
+  messageId: number,
+  chunks: TelegramRenderedChunk[],
+  deps: TelegramReplyDeliveryDeps<TReplyMarkup>,
+  options?: { replyMarkup?: TReplyMarkup },
+): Promise<number | undefined> {
+  if (chunks.length === 0) return messageId;
+  const [firstChunk, ...remainingChunks] = chunks;
+  await deps.editMessage({
+    chat_id: chatId,
+    message_id: messageId,
+    text: firstChunk.text,
+    parse_mode: firstChunk.parseMode,
+    reply_markup:
+      remainingChunks.length === 0 ? options?.replyMarkup : undefined,
+  });
+  if (remainingChunks.length > 0) {
+    return sendTelegramRenderedChunks(chatId, remainingChunks, deps, options);
+  }
+  return messageId;
+}
+
+// --- Reply Runtime ---
+
+export interface TelegramReplyRuntimeDeps {
+  renderTelegramMessage: (
+    text: string,
+    options?: { mode?: TelegramRenderMode },
+  ) => TelegramRenderedChunk[];
+  sendRenderedChunks: (
+    chunks: TelegramRenderedChunk[],
+  ) => Promise<number | undefined>;
+}
+
+export async function sendTelegramPlainReply(
+  text: string,
+  deps: TelegramReplyRuntimeDeps,
+  options?: { parseMode?: "HTML" },
+): Promise<number | undefined> {
+  const chunks = deps.renderTelegramMessage(text, {
+    mode: options?.parseMode === "HTML" ? "html" : "plain",
+  });
+  return deps.sendRenderedChunks(chunks);
+}
+
+export async function sendTelegramMarkdownReply(
+  markdown: string,
+  deps: TelegramReplyRuntimeDeps,
+): Promise<number | undefined> {
+  const chunks = deps.renderTelegramMessage(markdown, { mode: "markdown" });
+  if (chunks.length === 0) {
+    return sendTelegramPlainReply(markdown, deps);
+  }
+  return deps.sendRenderedChunks(chunks);
+}

package/lib/setup.ts

@@ -0,0 +1,41 @@
+/**
+ * Telegram setup prompt helpers
+ * Computes token-prefill defaults and prompt mode selection for /telegram-setup
+ */
+
+export interface TelegramBotTokenPromptSpec {
+  method: "input" | "editor";
+  value: string;
+}
+
+export const TELEGRAM_BOT_TOKEN_INPUT_PLACEHOLDER = "123456:ABCDEF...";
+export const TELEGRAM_BOT_TOKEN_ENV_VARS = [
+  "TELEGRAM_BOT_TOKEN",
+  "TELEGRAM_BOT_KEY",
+  "TELEGRAM_TOKEN",
+  "TELEGRAM_KEY",
+] as const;
+
+export function getTelegramBotTokenInputDefault(
+  env: NodeJS.ProcessEnv = process.env,
+  configToken?: string,
+): string {
+  const trimmedConfigToken = configToken?.trim();
+  if (trimmedConfigToken) return trimmedConfigToken;
+  for (const key of TELEGRAM_BOT_TOKEN_ENV_VARS) {
+    const value = env[key]?.trim();
+    if (value) return value;
+  }
+  return TELEGRAM_BOT_TOKEN_INPUT_PLACEHOLDER;
+}
+
+export function getTelegramBotTokenPromptSpec(
+  env: NodeJS.ProcessEnv = process.env,
+  configToken?: string,
+): TelegramBotTokenPromptSpec {
+  const value = getTelegramBotTokenInputDefault(env, configToken);
+  return {
+    method: value === TELEGRAM_BOT_TOKEN_INPUT_PLACEHOLDER ? "input" : "editor",
+    value,
+  };
+}

package/lib/status.ts

@@ -0,0 +1,109 @@
+/**
+ * Telegram status rendering helpers
+ * Builds usage, cost, and context summaries for the interactive Telegram status view
+ */
+
+import type { Model } from "@mariozechner/pi-ai";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export interface TelegramUsageStats {
+  totalInput: number;
+  totalOutput: number;
+  totalCacheRead: number;
+  totalCacheWrite: number;
+  totalCost: number;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`;
+  return `${Math.round(count / 1000000)}M`;
+}
+
+export function collectUsageStats(ctx: ExtensionContext): TelegramUsageStats {
+  const stats: TelegramUsageStats = {
+    totalInput: 0,
+    totalOutput: 0,
+    totalCacheRead: 0,
+    totalCacheWrite: 0,
+    totalCost: 0,
+  };
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type !== "message" || entry.message.role !== "assistant") {
+      continue;
+    }
+    stats.totalInput += entry.message.usage.input;
+    stats.totalOutput += entry.message.usage.output;
+    stats.totalCacheRead += entry.message.usage.cacheRead;
+    stats.totalCacheWrite += entry.message.usage.cacheWrite;
+    stats.totalCost += entry.message.usage.cost.total;
+  }
+  return stats;
+}
+
+function buildStatusRow(label: string, value: string): string {
+  return `<b>${escapeHtml(label)}:</b> <code>${escapeHtml(value)}</code>`;
+}
+
+function buildUsageSummary(stats: TelegramUsageStats): string | undefined {
+  const tokenParts: string[] = [];
+  if (stats.totalInput) tokenParts.push(`↑${formatTokens(stats.totalInput)}`);
+  if (stats.totalOutput) tokenParts.push(`↓${formatTokens(stats.totalOutput)}`);
+  if (stats.totalCacheRead)
+    tokenParts.push(`R${formatTokens(stats.totalCacheRead)}`);
+  if (stats.totalCacheWrite)
+    tokenParts.push(`W${formatTokens(stats.totalCacheWrite)}`);
+  return tokenParts.length > 0 ? tokenParts.join(" ") : undefined;
+}
+
+function buildCostSummary(
+  stats: TelegramUsageStats,
+  usesSubscription: boolean,
+): string | undefined {
+  if (!stats.totalCost && !usesSubscription) return undefined;
+  return `$${stats.totalCost.toFixed(3)}${usesSubscription ? " (sub)" : ""}`;
+}
+
+function buildContextSummary(
+  ctx: ExtensionContext,
+  activeModel: Model<any> | undefined,
+): string {
+  const usage = ctx.getContextUsage();
+  if (!usage) return "unknown";
+  const contextWindow = usage.contextWindow ?? activeModel?.contextWindow ?? 0;
+  const percent = usage.percent !== null ? `${usage.percent.toFixed(1)}%` : "?";
+  return `${percent}/${formatTokens(contextWindow)}`;
+}
+
+export function buildStatusHtml(
+  ctx: ExtensionContext,
+  activeModel: Model<any> | undefined,
+): string {
+  const stats = collectUsageStats(ctx);
+  const usesSubscription = activeModel
+    ? ctx.modelRegistry.isUsingOAuth(activeModel)
+    : false;
+  const lines: string[] = [];
+  const usageSummary = buildUsageSummary(stats);
+  const costSummary = buildCostSummary(stats, usesSubscription);
+  if (usageSummary) {
+    lines.push(buildStatusRow("Usage", usageSummary));
+  }
+  if (costSummary) {
+    lines.push(buildStatusRow("Cost", costSummary));
+  }
+  lines.push(buildStatusRow("Context", buildContextSummary(ctx, activeModel)));
+  if (lines.length === 0) {
+    lines.push(buildStatusRow("Status", "No usage data yet."));
+  }
+  return lines.join("\n");
+}

package/lib/turns.ts

@@ -0,0 +1,144 @@
+/**
+ * Telegram turn-building helpers
+ * Owns prompt-turn summary and content construction so queued Telegram turns are assembled consistently
+ */
+
+import { basename } from "node:path";
+
+import type { ImageContent, TextContent } from "@mariozechner/pi-ai";
+
+import {
+  collectTelegramMessageIds,
+  formatTelegramHistoryText,
+} from "./media.ts";
+import type { PendingTelegramTurn } from "./queue.ts";
+
+export interface TelegramTurnMessageLike {
+  message_id: number;
+  chat: { id: number };
+}
+
+export interface DownloadedTelegramTurnFileLike {
+  path: string;
+  fileName: string;
+  isImage: boolean;
+  mimeType?: string;
+}
+
+export function truncateTelegramQueueSummary(
+  text: string,
+  maxWords = 5,
+  maxLength = 40,
+): string {
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (!normalized) return "";
+  const words = normalized.split(" ");
+  let summary = words.slice(0, maxWords).join(" ");
+  if (summary.length === 0) summary = normalized;
+  if (summary.length > maxLength) {
+    summary = summary.slice(0, maxLength).trimEnd();
+  }
+  return summary.length < normalized.length || words.length > maxWords
+    ? `${summary}…`
+    : summary;
+}
+
+export function formatTelegramTurnStatusSummary(
+  rawText: string,
+  files: DownloadedTelegramTurnFileLike[],
+): string {
+  const textSummary = truncateTelegramQueueSummary(rawText);
+  if (textSummary) return textSummary;
+  if (files.length === 1) {
+    const fileName = basename(
+      files[0]?.fileName || files[0]?.path || "attachment",
+    );
+    return `📎 ${truncateTelegramQueueSummary(fileName, 4, 32) || "attachment"}`;
+  }
+  if (files.length > 1) return `📎 ${files.length} attachments`;
+  return "(empty message)";
+}
+
+export function buildTelegramTurnPrompt(options: {
+  telegramPrefix: string;
+  rawText: string;
+  files: DownloadedTelegramTurnFileLike[];
+  historyTurns?: Pick<PendingTelegramTurn, "historyText">[];
+}): string {
+  let prompt = options.telegramPrefix;
+  if ((options.historyTurns?.length ?? 0) > 0) {
+    prompt +=
+      "\n\nEarlier Telegram messages arrived after an aborted turn. Treat them as prior user messages, in order:";
+    for (const [index, turn] of (options.historyTurns ?? []).entries()) {
+      prompt += `\n\n${index + 1}. ${turn.historyText}`;
+    }
+    prompt += "\n\nCurrent Telegram message:";
+  }
+  if (options.rawText.length > 0) {
+    prompt +=
+      (options.historyTurns?.length ?? 0) > 0
+        ? `\n${options.rawText}`
+        : ` ${options.rawText}`;
+  }
+  if (options.files.length > 0) {
+    prompt += "\n\nTelegram attachments were saved locally:";
+    for (const file of options.files) {
+      prompt += `\n- ${file.path}`;
+    }
+  }
+  return prompt;
+}
+
+export async function buildTelegramPromptTurn(options: {
+  telegramPrefix: string;
+  messages: TelegramTurnMessageLike[];
+  historyTurns?: PendingTelegramTurn[];
+  queueOrder: number;
+  rawText: string;
+  files: DownloadedTelegramTurnFileLike[];
+  readBinaryFile: (path: string) => Promise<Uint8Array>;
+  inferImageMimeType: (path: string) => string | undefined;
+}): Promise<PendingTelegramTurn> {
+  const firstMessage = options.messages[0];
+  if (!firstMessage) {
+    throw new Error("Missing Telegram message for turn creation");
+  }
+  const content: Array<TextContent | ImageContent> = [
+    {
+      type: "text",
+      text: buildTelegramTurnPrompt({
+        telegramPrefix: options.telegramPrefix,
+        rawText: options.rawText,
+        files: options.files,
+        historyTurns: options.historyTurns,
+      }),
+    },
+  ];
+  for (const file of options.files) {
+    if (!file.isImage) continue;
+    const mediaType = file.mimeType || options.inferImageMimeType(file.path);
+    if (!mediaType) continue;
+    const buffer = await options.readBinaryFile(file.path);
+    content.push({
+      type: "image",
+      data: Buffer.from(buffer).toString("base64"),
+      mimeType: mediaType,
+    });
+  }
+  return {
+    kind: "prompt",
+    chatId: firstMessage.chat.id,
+    replyToMessageId: firstMessage.message_id,
+    sourceMessageIds: collectTelegramMessageIds(options.messages),
+    queueOrder: options.queueOrder,
+    queueLane: "default",
+    laneOrder: options.queueOrder,
+    queuedAttachments: [],
+    content,
+    historyText: formatTelegramHistoryText(options.rawText, options.files),
+    statusSummary: formatTelegramTurnStatusSummary(
+      options.rawText,
+      options.files,
+    ),
+  };
+}