@llblab/pi-telegram 0.12.0 → 0.13.0

package/lib/locks.ts

@@ -125,7 +125,10 @@ export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, "utf8");
+    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
     renameSync(tempPath, path);
   } catch (error) {
     try {

package/lib/outbound-buttons.ts

@@ -0,0 +1,226 @@
+/**
+ * Telegram outbound button helpers
+ * Zones: telegram outbound, assistant markup, callback routing
+ * Owns assistant-authored telegram_button extraction, button action storage, callback handling, and prompt-turn construction
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
+import {
+  parseTelegramCommentAttributes,
+  parseTopLevelTelegramComment,
+  replaceTopLevelHtmlComments,
+} from "./outbound-markup.ts";
+import {
+  type PendingTelegramTurn,
+  truncateTelegramQueueSummary,
+} from "./queue.ts";
+
+const TELEGRAM_BUTTON_CALLBACK_PREFIX = "tgbtn";
+const TELEGRAM_BUTTON_ACTION_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface TelegramOutboundButtonAction {
+  text: string;
+  prompt: string;
+}
+
+export interface TelegramOutboundButtonStoredAction extends TelegramOutboundButtonAction {
+  createdAt: number;
+}
+
+export type TelegramOutboundButtonMarkup = TelegramInlineKeyboardMarkup;
+
+export interface TelegramButtonReplyPlan {
+  markdown: string;
+  replyMarkup?: TelegramOutboundButtonMarkup;
+}
+
+export interface TelegramButtonActionStore {
+  register: (action: TelegramOutboundButtonAction) => string;
+  resolve: (
+    callbackData: string | undefined,
+  ) => TelegramOutboundButtonAction | undefined;
+}
+
+export interface TelegramButtonCallbackQuery {
+  id: string;
+  data?: string;
+  message?: {
+    message_id?: number;
+    chat?: { id?: number };
+  };
+}
+
+export interface TelegramButtonCallbackHandlerDeps<TContext = unknown> {
+  resolveAction: (
+    callbackData: string | undefined,
+  ) => TelegramOutboundButtonAction | undefined;
+  answerCallbackQuery: (
+    callbackQueryId: string,
+    text?: string,
+  ) => Promise<void>;
+  enqueueButtonPrompt: (
+    query: TelegramButtonCallbackQuery,
+    action: TelegramOutboundButtonAction,
+    ctx: TContext,
+  ) => void;
+}
+
+function nowMs(): number {
+  return Date.now();
+}
+
+function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
+  return markdown.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function parseButtonsCommentAttributes(input: string): {
+  label?: string;
+  prompt?: string;
+} {
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.label ? { label: attributes.label } : {}),
+    ...(attributes.prompt ? { prompt: attributes.prompt } : {}),
+  };
+}
+
+function parseButtonsCommentRows(
+  head: string,
+  body: string | undefined,
+): TelegramOutboundButtonAction[][] {
+  const trimmedHead = head.trim();
+
+  if (body === undefined) {
+    if (trimmedHead.startsWith(":")) {
+      const label = trimmedHead.slice(1).trim();
+      return label ? [[{ text: label, prompt: label }]] : [];
+    }
+    const attributes = parseButtonsCommentAttributes(head);
+    return attributes.label && attributes.prompt
+      ? [[{ text: attributes.label, prompt: attributes.prompt }]]
+      : [];
+  }
+
+  const label = parseButtonsCommentAttributes(head).label;
+  const prompt = body.trim();
+  if (!label || !prompt) return [];
+  return [[{ text: label, prompt }]];
+}
+
+export function createTelegramButtonActionStore(
+  options: { ttlMs?: number } = {},
+): TelegramButtonActionStore {
+  const ttlMs = options.ttlMs ?? TELEGRAM_BUTTON_ACTION_TTL_MS;
+  const actions = new Map<string, TelegramOutboundButtonStoredAction>();
+  function cleanup(currentTime: number): void {
+    for (const [key, action] of actions) {
+      if (currentTime - action.createdAt > ttlMs) actions.delete(key);
+    }
+  }
+  return {
+    register: (action) => {
+      const currentTime = nowMs();
+      cleanup(currentTime);
+      const key = `${TELEGRAM_BUTTON_CALLBACK_PREFIX}:${randomUUID().slice(0, 8)}`;
+      actions.set(key, { ...action, createdAt: currentTime });
+      return key;
+    },
+    resolve: (callbackData) => {
+      if (!callbackData?.startsWith(`${TELEGRAM_BUTTON_CALLBACK_PREFIX}:`)) {
+        return undefined;
+      }
+      const currentTime = nowMs();
+      cleanup(currentTime);
+      const action = actions.get(callbackData);
+      if (!action) return undefined;
+      return { text: action.text, prompt: action.prompt };
+    },
+  };
+}
+
+export function planTelegramButtonReply(
+  markdown: string,
+  deps: { registerAction: (action: TelegramOutboundButtonAction) => string },
+): TelegramButtonReplyPlan {
+  const keyboard: TelegramOutboundButtonMarkup["inline_keyboard"] = [];
+  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+    const command = parseTopLevelTelegramComment(comment, "telegram_button");
+    if (!command) return comment.raw;
+    const rows = parseButtonsCommentRows(command.head, command.body);
+    for (const row of rows) {
+      keyboard.push(
+        row.map((button) => ({
+          text: button.text,
+          callback_data: deps.registerAction(button),
+        })),
+      );
+    }
+    return "";
+  });
+  return {
+    markdown: normalizeMarkdownAfterButtonExtraction(stripped),
+    ...(keyboard.length > 0
+      ? { replyMarkup: { inline_keyboard: keyboard } }
+      : {}),
+  };
+}
+
+export function createTelegramButtonReplyPlanner(
+  store: Pick<TelegramButtonActionStore, "register">,
+): (markdown: string) => TelegramButtonReplyPlan {
+  return (markdown) =>
+    planTelegramButtonReply(markdown, { registerAction: store.register });
+}
+
+export function createTelegramButtonPromptTurn(options: {
+  chatId: number;
+  replyToMessageId: number;
+  queueOrder: number;
+  action: TelegramOutboundButtonAction;
+}): PendingTelegramTurn {
+  const prompt = `[telegram] ${options.action.prompt}`;
+  return {
+    kind: "prompt",
+    chatId: options.chatId,
+    replyToMessageId: options.replyToMessageId,
+    sourceMessageIds: [options.replyToMessageId],
+    queueOrder: options.queueOrder,
+    queueLane: "default",
+    laneOrder: options.queueOrder,
+    queuedAttachments: [],
+    content: [{ type: "text", text: prompt }],
+    historyText: options.action.prompt,
+    statusSummary: truncateTelegramQueueSummary(
+      options.action.text || options.action.prompt,
+    ),
+  };
+}
+
+export async function handleTelegramButtonCallbackQuery<TContext = unknown>(
+  query: TelegramButtonCallbackQuery,
+  ctx: TContext,
+  deps: TelegramButtonCallbackHandlerDeps<TContext>,
+): Promise<boolean> {
+  const action = deps.resolveAction(query.data);
+
+  if (!action) {
+    if (query.data?.startsWith(`${TELEGRAM_BUTTON_CALLBACK_PREFIX}:`)) {
+      await deps.answerCallbackQuery(query.id, "Button action expired.");
+      return true;
+    }
+    return false;
+  }
+
+  const chatId = query.message?.chat?.id;
+  const messageId = query.message?.message_id;
+  if (typeof chatId !== "number" || typeof messageId !== "number") {
+    await deps.answerCallbackQuery(query.id, "Button action expired.");
+    return true;
+  }
+
+  deps.enqueueButtonPrompt(query, action, ctx);
+  await deps.answerCallbackQuery(query.id, "Queued.");
+  return true;
+}

package/lib/outbound-markup.ts

@@ -0,0 +1,357 @@
+/**
+ * Telegram outbound markup parsing helpers
+ * Zones: telegram outbound, assistant markup
+ * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
+ */
+
+export interface TelegramTopLevelHtmlComment {
+  raw: string;
+  content: string;
+  start: number;
+  end: number;
+}
+
+interface TelegramTopLevelFenceState {
+  marker: "`" | "~";
+  length: number;
+}
+
+function isTelegramActionCommentContent(content: string): boolean {
+  const normalizedContent = content.replace(/^\s+/, "");
+  const [head = ""] = normalizedContent.split(/\r?\n/, 1);
+  return ["telegram_voice", "telegram_button"].some((command) => {
+    if (!head.startsWith(command)) return false;
+    const nextChar = head[command.length];
+    return nextChar === undefined || /\s|:/.test(nextChar);
+  });
+}
+
+function getMarkdownLineEnd(markdown: string, offset: number): number {
+  const newlineIndex = markdown.indexOf("\n", offset);
+  return newlineIndex === -1 ? markdown.length : newlineIndex + 1;
+}
+
+function getMarkdownLineText(
+  markdown: string,
+  offset: number,
+  end: number,
+): string {
+  return markdown.slice(offset, end).replace(/\r?\n$/, "");
+}
+
+function getTopLevelOpeningFence(
+  line: string,
+): TelegramTopLevelFenceState | undefined {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+  const sequence = match?.[1];
+  if (!sequence) return undefined;
+  return {
+    marker: sequence[0] as "`" | "~",
+    length: sequence.length,
+  };
+}
+
+function isTopLevelClosingFence(
+  line: string,
+  fence: TelegramTopLevelFenceState,
+): boolean {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+  const sequence = match?.[1];
+  return (
+    !!sequence &&
+    sequence[0] === fence.marker &&
+    sequence.length >= fence.length
+  );
+}
+
+function collectInlineClosedTelegramActionBody(
+  markdown: string,
+  bodyStart: number,
+  commentContent: string,
+): { content: string; end: number } | undefined {
+  const bodyLineEnd = getMarkdownLineEnd(markdown, bodyStart);
+  const bodyLine = getMarkdownLineText(markdown, bodyStart, bodyLineEnd);
+  const closeLineEnd = getMarkdownLineEnd(markdown, bodyLineEnd);
+  const closeLine = getMarkdownLineText(markdown, bodyLineEnd, closeLineEnd);
+  const hasRecoverableBody =
+    isTelegramActionCommentContent(commentContent) &&
+    bodyLine.trim() !== "" &&
+    !bodyLine.startsWith("<!--") &&
+    !bodyLine.startsWith("-->") &&
+    closeLine === "-->";
+  if (!hasRecoverableBody) return undefined;
+  return {
+    content: `${commentContent.trimEnd()}\n${bodyLine}`,
+    end: bodyLineEnd + 3,
+  };
+}
+
+export function collectTopLevelHtmlComments(markdown: string): {
+  comments: TelegramTopLevelHtmlComment[];
+  openCommentStart?: number;
+} {
+  const comments: TelegramTopLevelHtmlComment[] = [];
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
+      offset = lineEnd;
+      continue;
+    }
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
+      offset = lineEnd;
+      continue;
+    }
+    if (line.startsWith("<!--")) {
+      const closeIndex = markdown.indexOf("-->", offset + 4);
+      if (closeIndex === -1) return { comments, openCommentStart: offset };
+      let end = closeIndex + 3;
+      let raw = markdown.slice(offset, end);
+      let content = raw.slice(4, -3);
+      const closeColumn = closeIndex - offset;
+      const closesOnOpeningLine = closeIndex < lineEnd;
+      const hasOnlyWhitespaceAfterClose =
+        line.slice(closeColumn + 3).trim() === "";
+      const inlineBody =
+        closesOnOpeningLine && hasOnlyWhitespaceAfterClose
+          ? collectInlineClosedTelegramActionBody(markdown, lineEnd, content)
+          : undefined;
+      if (inlineBody) {
+        end = inlineBody.end;
+        raw = markdown.slice(offset, end);
+        content = inlineBody.content;
+      }
+      comments.push({ raw, content, start: offset, end });
+      offset = getMarkdownLineEnd(markdown, end);
+      continue;
+    }
+    offset = lineEnd;
+  }
+  return { comments };
+}
+
+export function replaceTopLevelHtmlComments(
+  markdown: string,
+  replacer: (comment: TelegramTopLevelHtmlComment) => string,
+): string {
+  const { comments } = collectTopLevelHtmlComments(markdown);
+  if (comments.length === 0) return markdown;
+  let result = "";
+  let offset = 0;
+  for (const comment of comments) {
+    result += markdown.slice(offset, comment.start);
+    result += replacer(comment);
+    offset = comment.end;
+  }
+  return result + markdown.slice(offset);
+}
+
+export function findTopLevelOpenOrPartialHtmlCommentIndex(
+  markdown: string,
+): number {
+  const { openCommentStart } = collectTopLevelHtmlComments(markdown);
+  if (openCommentStart !== undefined) return openCommentStart;
+  let offset = 0;
+  let fence: TelegramTopLevelFenceState | undefined;
+  while (offset < markdown.length) {
+    const lineEnd = getMarkdownLineEnd(markdown, offset);
+    const line = getMarkdownLineText(markdown, offset, lineEnd);
+    const isLastLine = lineEnd >= markdown.length;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
+      offset = lineEnd;
+      continue;
+    }
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
+      offset = lineEnd;
+      continue;
+    }
+    if (isLastLine && (line === "<" || line === "<!" || line === "<!-")) {
+      return offset;
+    }
+    offset = lineEnd;
+  }
+  return -1;
+}
+
+export function parseTopLevelTelegramComment(
+  comment: TelegramTopLevelHtmlComment,
+  command: string,
+): { head: string; body?: string } | undefined {
+  let normalizedContent = comment.content.replace(/^\s+/, "");
+  normalizedContent = normalizedContent.replace(/^!/, "");
+  const [rawHead = "", ...bodyLines] = normalizedContent.split(/\r?\n/);
+  let head = rawHead.trimStart();
+  if (!head.startsWith(command)) return undefined;
+  const nextChar = head[command.length];
+  if (nextChar !== undefined && !/\s|:/.test(nextChar)) return undefined;
+  return {
+    head: head.slice(command.length),
+    ...(bodyLines.length > 0 ? { body: bodyLines.join("\n") } : {}),
+  };
+}
+
+export function parseTelegramCommentAttributes(
+  input: string,
+): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of input.matchAll(
+    /([A-Za-z_][A-Za-z0-9_-]*)=(?:"([^"]*)"|'([^']*)'|(\S+))/g,
+  )) {
+    const key = match[1];
+    const value = (match[2] ?? match[3] ?? match[4] ?? "").trim();
+    if (value) attributes[key] = value;
+  }
+  return attributes;
+}
+
+export function normalizeMarkdownAfterVoiceExtraction(
+  markdown: string,
+): string {
+  return markdown.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+export function stripTelegramCommentMarkupForPreview(markdown: string): string {
+  const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+  const previewMarkdown =
+    openBlockIndex >= 0
+      ? withoutClosedBlocks.slice(0, openBlockIndex)
+      : withoutClosedBlocks;
+  return normalizeMarkdownAfterVoiceExtraction(previewMarkdown);
+}
+
+export function stripTelegramCommentMarkupForDelivery(
+  markdown: string,
+): string {
+  const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
+  const deliveryMarkdown =
+    openBlockIndex >= 0
+      ? withoutClosedBlocks.slice(0, openBlockIndex)
+      : withoutClosedBlocks;
+  return normalizeMarkdownAfterVoiceExtraction(deliveryMarkdown);
+}
+
+export function stripTelegramVoiceMarkupForPreview(markdown: string): string {
+  return stripTelegramCommentMarkupForPreview(markdown);
+}
+
+export interface TelegramVoiceReplyItem {
+  text: string;
+  lang?: string;
+  rate?: string;
+}
+
+export interface TelegramVoiceReplyPlan {
+  markdown: string;
+  voiceText?: string;
+  voiceReplies?: TelegramVoiceReplyItem[];
+  lang?: string;
+  rate?: string;
+}
+
+function parseVoiceReplyAttributes(input: string): {
+  lang?: string;
+  rate?: string;
+  text?: string;
+} {
+  const attributes = parseTelegramCommentAttributes(input);
+  return {
+    ...(attributes.lang ? { lang: attributes.lang } : {}),
+    ...(attributes.rate ? { rate: attributes.rate } : {}),
+    ...(attributes.text ? { text: attributes.text } : {}),
+  };
+}
+
+function parseVoiceCommentBody(
+  head: string,
+  body: string | undefined,
+): {
+  attrs: string;
+  text: string;
+} {
+  const trimmedHead = head.trim();
+  if (body !== undefined) {
+    return { attrs: trimmedHead.replace(/^:/, "").trim(), text: body.trim() };
+  }
+  let colonIndex = -1;
+  let inQuote = false;
+  let quoteChar = "";
+  for (let i = 0; i < trimmedHead.length; i++) {
+    const char = trimmedHead[i];
+    if (inQuote) {
+      if (char === quoteChar) inQuote = false;
+    } else {
+      if (char === '"' || char === "'") {
+        inQuote = true;
+        quoteChar = char;
+      } else if (char === ":") {
+        colonIndex = i;
+        break;
+      }
+    }
+  }
+  if (colonIndex > 0) {
+    const attrsPart = trimmedHead.slice(0, colonIndex).trim();
+    const textPart = trimmedHead.slice(colonIndex + 1).trim();
+    const attrs = parseVoiceReplyAttributes(attrsPart);
+    return { attrs: attrsPart, text: textPart || attrs.text || "", ...attrs };
+  }
+  if (trimmedHead.startsWith(":")) {
+    return { attrs: "", text: trimmedHead.slice(1).trim() };
+  }
+  const attrs = parseVoiceReplyAttributes(trimmedHead);
+  return { attrs: trimmedHead, text: attrs.text ?? "" };
+}
+
+export function planTelegramVoiceReply(
+  markdown: string,
+): TelegramVoiceReplyPlan {
+  const voiceReplies: TelegramVoiceReplyItem[] = [];
+  let lang: string | undefined;
+  let rate: string | undefined;
+  const stripped = replaceTopLevelHtmlComments(markdown, (comment) => {
+    let command = parseTopLevelTelegramComment(comment, "telegram_voice");
+    if (!command) {
+      let content = comment.content.replace(/^\s+/, "").replace(/^!/, "");
+      if (content.startsWith("telegram_voice")) {
+        const headPart = content.slice("telegram_voice".length).trim();
+        command = { head: headPart, body: undefined };
+      }
+    }
+    if (!command) return "";
+    const parsed = parseVoiceCommentBody(command.head, command.body);
+    const attrs = parseVoiceReplyAttributes(parsed.attrs);
+    if (parsed.text) {
+      voiceReplies.push({
+        text: parsed.text,
+        ...(attrs.lang ? { lang: attrs.lang } : {}),
+        ...(attrs.rate ? { rate: attrs.rate } : {}),
+      });
+    }
+    if (attrs.lang) lang = attrs.lang;
+    if (attrs.rate) rate = attrs.rate;
+    return "";
+  });
+  const voiceText = voiceReplies
+    .map((reply) => reply.text)
+    .join("\n\n")
+    .trim();
+  return {
+    markdown: stripTelegramCommentMarkupForDelivery(stripped),
+    ...(voiceText ? { voiceText } : {}),
+    ...(voiceReplies.length > 0 ? { voiceReplies } : {}),
+    ...(lang ? { lang } : {}),
+    ...(rate ? { rate } : {}),
+  };
+}