paperclip-plugin-telegram 0.2.0 → 0.2.2

package/src/manifest.ts

@@ -1,246 +0,0 @@
-import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
-import { DEFAULT_CONFIG, PLUGIN_ID, PLUGIN_VERSION, MAX_AGENTS_PER_THREAD } from "./constants.js";
-
-const manifest: PaperclipPluginManifestV1 = {
-  id: PLUGIN_ID,
-  apiVersion: 1,
-  version: PLUGIN_VERSION,
-  displayName: "Telegram Bot",
-  description:
-    "Bidirectional Telegram integration: push notifications, bot commands, escalation to humans, multi-agent sessions (native + ACP), media pipeline with transcription, custom workflow commands, and proactive suggestion watches.",
-  author: "mvanhorn",
-  categories: ["connector", "automation"],
-  capabilities: [
-    "companies.read",
-    "issues.read",
-    "issues.create",
-    "agents.read",
-    "agents.invoke",
-    "agent.sessions.create",
-    "agent.sessions.list",
-    "agent.sessions.send",
-    "agent.sessions.close",
-    "agent.tools.register",
-    "events.subscribe",
-    "events.emit",
-    "plugin.state.read",
-    "plugin.state.write",
-    "http.outbound",
-    "secrets.read-ref",
-    "activity.log.write",
-    "metrics.write",
-    "jobs.schedule",
-  ],
-  entrypoints: {
-    worker: "./dist/worker.js",
-  },
-  instanceConfigSchema: {
-    type: "object",
-    properties: {
-      telegramBotTokenRef: {
-        type: "string",
-        title: "Telegram Bot Token (secret reference)",
-        description:
-          "Reference to the Telegram Bot token stored in your secret provider. Get one from @BotFather.",
-        default: DEFAULT_CONFIG.telegramBotTokenRef,
-      },
-      defaultChatId: {
-        type: "string",
-        title: "Default Chat ID",
-        description:
-          "Telegram chat ID to send notifications to. Use a group chat ID (negative number) or a user chat ID.",
-        default: DEFAULT_CONFIG.defaultChatId,
-      },
-      approvalsChatId: {
-        type: "string",
-        title: "Approvals Chat ID",
-        description:
-          "Chat ID for approval requests. Falls back to default chat.",
-        default: DEFAULT_CONFIG.approvalsChatId,
-      },
-      errorsChatId: {
-        type: "string",
-        title: "Errors Chat ID",
-        description:
-          "Chat ID for agent error notifications. Falls back to default chat.",
-        default: DEFAULT_CONFIG.errorsChatId,
-      },
-      notifyOnIssueCreated: {
-        type: "boolean",
-        title: "Notify on issue created",
-        default: DEFAULT_CONFIG.notifyOnIssueCreated,
-      },
-      notifyOnIssueDone: {
-        type: "boolean",
-        title: "Notify on issue completed",
-        default: DEFAULT_CONFIG.notifyOnIssueDone,
-      },
-      notifyOnApprovalCreated: {
-        type: "boolean",
-        title: "Notify on approval requested",
-        default: DEFAULT_CONFIG.notifyOnApprovalCreated,
-      },
-      notifyOnAgentError: {
-        type: "boolean",
-        title: "Notify on agent error",
-        default: DEFAULT_CONFIG.notifyOnAgentError,
-      },
-      enableCommands: {
-        type: "boolean",
-        title: "Enable bot commands",
-        description:
-          "Allow users to interact with Paperclip via Telegram bot commands (/status, /issues, /agents).",
-        default: DEFAULT_CONFIG.enableCommands,
-      },
-      enableInbound: {
-        type: "boolean",
-        title: "Enable inbound message routing",
-        description:
-          "Route Telegram messages to Paperclip issue comments. Messages sent in reply to a notification get attached to that issue.",
-        default: DEFAULT_CONFIG.enableInbound,
-      },
-      dailyDigestEnabled: {
-        type: "boolean",
-        title: "Daily digest",
-        description: "Send a daily summary of agent activity.",
-        default: DEFAULT_CONFIG.dailyDigestEnabled,
-      },
-      dailyDigestTime: {
-        type: "string",
-        title: "Digest time (HH:MM UTC)",
-        description: "Time to send the daily digest in UTC.",
-        default: DEFAULT_CONFIG.dailyDigestTime,
-      },
-      topicRouting: {
-        type: "boolean",
-        title: "Forum topic routing",
-        description:
-          "Map Telegram forum topics to Paperclip projects. Requires the bot to be in a group with forum topics enabled.",
-        default: DEFAULT_CONFIG.topicRouting,
-      },
-      paperclipBaseUrl: {
-        type: "string",
-        title: "Paperclip Base URL",
-        description:
-          "Base URL of the Paperclip API server.",
-        default: DEFAULT_CONFIG.paperclipBaseUrl,
-      },
-      escalationChatId: {
-        type: "string",
-        title: "Escalation Chat ID",
-        description:
-          "Telegram chat ID where escalations are sent for human review. If empty, escalations are logged but not forwarded.",
-        default: DEFAULT_CONFIG.escalationChatId,
-      },
-      escalationTimeoutMs: {
-        type: "number",
-        title: "Escalation Timeout (ms)",
-        description:
-          "How long to wait for a human response before taking the default action. Default: 900000 (15 minutes).",
-        default: DEFAULT_CONFIG.escalationTimeoutMs,
-      },
-      escalationDefaultAction: {
-        type: "string",
-        title: "Escalation Default Action",
-        description:
-          "What to do when an escalation times out: defer (do nothing), auto_reply (send suggested reply), or close.",
-        enum: ["defer", "auto_reply", "close"],
-        default: DEFAULT_CONFIG.escalationDefaultAction,
-      },
-      escalationHoldMessage: {
-        type: "string",
-        title: "Escalation Hold Message",
-        description:
-          "Message sent to the user when their conversation is escalated to a human.",
-        default: DEFAULT_CONFIG.escalationHoldMessage,
-      },
-      maxAgentsPerThread: {
-        type: "number",
-        title: "Max Agents Per Thread",
-        description:
-          "Maximum number of concurrent agent sessions allowed in a single thread.",
-        default: MAX_AGENTS_PER_THREAD,
-      },
-      briefAgentId: {
-        type: "string",
-        title: "Brief Agent ID",
-        description: "Agent ID for processing media intake briefs. Leave empty to disable media pipeline.",
-        default: DEFAULT_CONFIG.briefAgentId,
-      },
-      briefAgentChatIds: {
-        type: "array",
-        items: { type: "string" },
-        title: "Brief Agent Intake Chat IDs",
-        description: "Telegram chat IDs where media is routed to the Brief Agent. Media in other chats goes to active agent sessions.",
-        default: DEFAULT_CONFIG.briefAgentChatIds,
-      },
-      transcriptionApiKeyRef: {
-        type: "string",
-        title: "Transcription API Key (secret reference)",
-        description: "Reference to OpenAI API key for Whisper transcription of voice/audio messages.",
-        default: DEFAULT_CONFIG.transcriptionApiKeyRef,
-      },
-      maxSuggestionsPerHourPerCompany: {
-        type: "number",
-        title: "Max Suggestions per Hour per Company",
-        description: "Rate limit for proactive watch suggestions.",
-        default: DEFAULT_CONFIG.maxSuggestionsPerHourPerCompany,
-      },
-      watchDeduplicationWindowMs: {
-        type: "number",
-        title: "Watch Deduplication Window (ms)",
-        description: "Suppress duplicate watch suggestions for the same entity within this window. Default: 86400000 (24 hours).",
-        default: DEFAULT_CONFIG.watchDeduplicationWindowMs,
-      },
-    },
-    required: ["telegramBotTokenRef", "defaultChatId"],
-  },
-  jobs: [
-    {
-      jobKey: "telegram-daily-digest",
-      displayName: "Telegram Daily Digest",
-      description: "Send a daily summary of agent activity to Telegram.",
-      schedule: "0 9 * * *",
-    },
-    {
-      jobKey: "check-escalation-timeouts",
-      displayName: "Check Escalation Timeouts",
-      description: "Check for timed-out escalations and apply default actions.",
-      schedule: "* * * * *",
-    },
-    {
-      jobKey: "check-watches",
-      displayName: "Check Proactive Watches",
-      description: "Evaluate registered watches and send suggestions when conditions are met.",
-      schedule: "*/15 * * * *",
-    },
-  ],
-  tools: [
-    {
-      name: "escalate_to_human",
-      displayName: "Escalate to Human",
-      description: "Escalate a conversation to a human when you cannot handle it confidently",
-      parametersSchema: { type: "object" },
-    },
-    {
-      name: "handoff_to_agent",
-      displayName: "Handoff to Agent",
-      description: "Hand off work to another agent in this thread",
-      parametersSchema: { type: "object" },
-    },
-    {
-      name: "discuss_with_agent",
-      displayName: "Discuss with Agent",
-      description: "Start a back-and-forth conversation with another agent",
-      parametersSchema: { type: "object" },
-    },
-    {
-      name: "register_watch",
-      displayName: "Register Watch",
-      description: "Register a proactive watch that monitors entities and sends suggestions",
-      parametersSchema: { type: "object" },
-    },
-  ],
-};
-
-export default manifest;

package/src/media-pipeline.ts

@@ -1,234 +0,0 @@
-import type { PluginContext } from "@paperclipai/plugin-sdk";
-import { sendMessage, escapeMarkdownV2, sendChatAction } from "./telegram-api.js";
-import { METRIC_NAMES } from "./constants.js";
-import { getSessions } from "./acp-bridge.js";
-
-const TELEGRAM_API = "https://api.telegram.org";
-
-type MediaConfig = {
-  briefAgentId: string;
-  briefAgentChatIds: string[];
-  transcriptionApiKeyRef: string;
-};
-
-type TelegramMediaMessage = {
-  message_id: number;
-  chat: { id: number };
-  message_thread_id?: number;
-  from?: { id: number; username?: string; first_name?: string };
-  voice?: { file_id: string; duration: number; mime_type?: string };
-  audio?: { file_id: string; duration: number; title?: string; mime_type?: string };
-  video_note?: { file_id: string; duration: number };
-  document?: { file_id: string; file_name?: string; mime_type?: string };
-  photo?: Array<{ file_id: string; width: number; height: number }>;
-  caption?: string;
-};
-
-export async function handleMediaMessage(
-  ctx: PluginContext,
-  token: string,
-  msg: TelegramMediaMessage,
-  config: MediaConfig,
-  companyId: string,
-): Promise<boolean> {
-  const chatId = String(msg.chat.id);
-  const threadId = msg.message_thread_id;
-
-  // Determine if this is an intake channel (brief agent) or an agent thread
-  const isIntakeChannel = config.briefAgentChatIds.includes(chatId);
-  const hasActiveSession = threadId
-    ? (await getSessions(ctx, chatId, threadId)).some((s) => s.status === "active")
-    : false;
-
-  if (!isIntakeChannel && !hasActiveSession) {
-    return false; // Not a media-relevant context
-  }
-
-  await sendChatAction(ctx, token, chatId);
-
-  // Extract media file info
-  const fileId = extractFileId(msg);
-  if (!fileId) return false;
-
-  const isAudio = !!(msg.voice || msg.audio || msg.video_note);
-
-  let textContent = msg.caption ?? "";
-
-  // Transcribe audio/voice if applicable
-  if (isAudio && config.transcriptionApiKeyRef) {
-    try {
-      const transcription = await transcribeAudio(ctx, token, fileId, config.transcriptionApiKeyRef);
-      if (transcription) {
-        textContent = transcription;
-
-        // Send transcription preview
-        await sendMessage(
-          ctx,
-          token,
-          chatId,
-          `${escapeMarkdownV2("\ud83c\udfa4")} *Transcription:*\n${escapeMarkdownV2(textContent.slice(0, 500))}${textContent.length > 500 ? escapeMarkdownV2("...") : ""}`,
-          {
-            parseMode: "MarkdownV2",
-            messageThreadId: threadId,
-            replyToMessageId: msg.message_id,
-          },
-        );
-      }
-    } catch (err) {
-      ctx.logger.error("Transcription failed", { error: String(err) });
-      textContent = msg.caption ?? "[Audio - transcription failed]";
-    }
-  }
-
-  if (isIntakeChannel && config.briefAgentId) {
-    // Route to Brief Agent via one-shot invocation
-    try {
-      const prompt = buildBriefPrompt(msg, textContent);
-      const { runId } = await ctx.agents.invoke(config.briefAgentId, companyId, {
-        prompt,
-        reason: "media_intake",
-      });
-
-      await sendMessage(
-        ctx,
-        token,
-        chatId,
-        `${escapeMarkdownV2("\ud83d\udcdd")} Media sent to Brief Agent \\(run: \`${escapeMarkdownV2(runId)}\`\\)`,
-        {
-          parseMode: "MarkdownV2",
-          messageThreadId: threadId,
-          replyToMessageId: msg.message_id,
-        },
-      );
-
-      ctx.logger.info("Media routed to brief agent", { runId, briefAgentId: config.briefAgentId });
-    } catch (err) {
-      ctx.logger.error("Failed to invoke brief agent", { error: String(err) });
-      await sendMessage(
-        ctx,
-        token,
-        chatId,
-        `Failed to route media to brief agent: ${String(err)}`,
-        { messageThreadId: threadId },
-      );
-    }
-  } else if (hasActiveSession && threadId) {
-    // Route to the active agent in the thread
-    const sessions = await getSessions(ctx, chatId, threadId);
-    const activeSessions = sessions.filter((s) => s.status === "active");
-    const target = activeSessions.sort(
-      (a, b) => new Date(b.lastActivityAt).getTime() - new Date(a.lastActivityAt).getTime(),
-    )[0];
-
-    if (target) {
-      const mediaLabel = isAudio ? "Audio message" : msg.photo ? "Photo" : "Document";
-      const prompt = `[${mediaLabel}] ${textContent || "(no caption)"}`;
-
-      if (target.transport === "native") {
-        try {
-          await ctx.agents.sessions.sendMessage(target.sessionId, companyId, {
-            prompt,
-            reason: "media_message",
-          });
-        } catch (err) {
-          ctx.logger.error("Failed to send media to native session", { error: String(err) });
-        }
-      } else {
-        ctx.events.emit("acp-spawn", companyId, {
-          type: "message",
-          sessionId: target.sessionId,
-          chatId,
-          threadId,
-          text: prompt,
-        });
-      }
-    }
-  }
-
-  await ctx.metrics.write(METRIC_NAMES.mediaProcessed, 1);
-  return true;
-}
-
-function extractFileId(msg: TelegramMediaMessage): string | null {
-  if (msg.voice) return msg.voice.file_id;
-  if (msg.audio) return msg.audio.file_id;
-  if (msg.video_note) return msg.video_note.file_id;
-  if (msg.document) return msg.document.file_id;
-  if (msg.photo && msg.photo.length > 0) {
-    // Use the largest photo
-    return msg.photo.sort((a, b) => b.width * b.height - a.width * a.height)[0]!.file_id;
-  }
-  return null;
-}
-
-async function transcribeAudio(
-  ctx: PluginContext,
-  botToken: string,
-  fileId: string,
-  transcriptionApiKeyRef: string,
-): Promise<string | null> {
-  // 1. Get file path from Telegram
-  const fileRes = await ctx.http.fetch(
-    `${TELEGRAM_API}/bot${botToken}/getFile?file_id=${fileId}`,
-    { method: "GET" },
-  );
-  const fileData = (await fileRes.json()) as {
-    ok: boolean;
-    result?: { file_path: string };
-  };
-
-  if (!fileData.ok || !fileData.result?.file_path) {
-    ctx.logger.error("Failed to get file path from Telegram", { fileId });
-    return null;
-  }
-
-  // 2. Download the file
-  const downloadUrl = `${TELEGRAM_API}/file/bot${botToken}/${fileData.result.file_path}`;
-  const audioRes = await ctx.http.fetch(downloadUrl, { method: "GET" });
-  const audioBlob = await audioRes.blob();
-
-  // 3. Send to Whisper API
-  const apiKey = await ctx.secrets.resolve(transcriptionApiKeyRef);
-  const formData = new FormData();
-  formData.append("file", audioBlob, "audio.ogg");
-  formData.append("model", "whisper-1");
-
-  const whisperRes = await ctx.http.fetch(
-    "https://api.openai.com/v1/audio/transcriptions",
-    {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-      },
-      body: formData,
-    },
-  );
-
-  const whisperData = (await whisperRes.json()) as { text?: string };
-  return whisperData.text ?? null;
-}
-
-function buildBriefPrompt(msg: TelegramMediaMessage, textContent: string): string {
-  const parts: string[] = [];
-
-  if (msg.voice) {
-    parts.push(`[Voice message, ${msg.voice.duration}s]`);
-  } else if (msg.audio) {
-    parts.push(`[Audio: ${msg.audio.title ?? "untitled"}, ${msg.audio.duration}s]`);
-  } else if (msg.video_note) {
-    parts.push(`[Video note, ${msg.video_note.duration}s]`);
-  } else if (msg.document) {
-    parts.push(`[Document: ${msg.document.file_name ?? "unknown"}]`);
-  } else if (msg.photo) {
-    parts.push("[Photo]");
-  }
-
-  if (textContent) {
-    parts.push(textContent);
-  }
-
-  const sender = msg.from?.username ?? msg.from?.first_name ?? "unknown";
-  parts.push(`\nFrom: ${sender}`);
-
-  return parts.join("\n");
-}

package/src/telegram-api.ts

@@ -1,202 +0,0 @@
-import type { PluginContext } from "@paperclipai/plugin-sdk";
-import { METRIC_NAMES } from "./constants.js";
-
-const TELEGRAM_API = "https://api.telegram.org";
-
-type InlineButton = {
-  text: string;
-  callback_data?: string;
-  url?: string;
-};
-
-type InlineKeyboard = InlineButton[][];
-
-export type SendMessageOptions = {
-  parseMode?: "MarkdownV2" | "HTML";
-  replyToMessageId?: number;
-  messageThreadId?: number;
-  inlineKeyboard?: InlineKeyboard;
-  disableNotification?: boolean;
-};
-
-export async function sendMessage(
-  ctx: PluginContext,
-  token: string,
-  chatId: string,
-  text: string,
-  options: SendMessageOptions = {},
-): Promise<number | null> {
-  const body: Record<string, unknown> = {
-    chat_id: chatId,
-    text,
-  };
-
-  if (options.parseMode) body.parse_mode = options.parseMode;
-  if (options.replyToMessageId) body.reply_to_message_id = options.replyToMessageId;
-  if (options.messageThreadId) body.message_thread_id = options.messageThreadId;
-  if (options.disableNotification) body.disable_notification = true;
-
-  if (options.inlineKeyboard) {
-    body.reply_markup = {
-      inline_keyboard: options.inlineKeyboard,
-    };
-  }
-
-  for (let attempt = 0; attempt < 3; attempt++) {
-    try {
-      const res = await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/sendMessage`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(body),
-      });
-
-      const data = (await res.json()) as {
-        ok: boolean;
-        result?: { message_id: number };
-        description?: string;
-        parameters?: { retry_after?: number };
-      };
-
-      if (!data.ok) {
-        if (data.parameters?.retry_after && attempt < 2) {
-          const wait = data.parameters.retry_after * 1000;
-          ctx.logger.warn("Telegram rate limited, retrying", { retryAfter: data.parameters.retry_after, attempt });
-          await new Promise((r) => setTimeout(r, wait));
-          continue;
-        }
-
-        if (options.parseMode === "MarkdownV2") {
-          ctx.logger.warn("MarkdownV2 send failed, retrying as plain text", {
-            error: data.description,
-          });
-          return sendMessage(ctx, token, chatId, stripMarkdown(text), {
-            ...options,
-            parseMode: undefined,
-          });
-        }
-        ctx.logger.error("Telegram sendMessage failed", { error: data.description });
-        await ctx.metrics.write(METRIC_NAMES.failed, 1);
-        return null;
-      }
-
-      await ctx.metrics.write(METRIC_NAMES.sent, 1);
-      return data.result?.message_id ?? null;
-    } catch (err) {
-      ctx.logger.error("Telegram API error", { error: String(err) });
-      await ctx.metrics.write(METRIC_NAMES.failed, 1);
-      return null;
-    }
-  }
-  return null;
-}
-
-export async function editMessage(
-  ctx: PluginContext,
-  token: string,
-  chatId: string,
-  messageId: number,
-  text: string,
-  options: { parseMode?: "MarkdownV2" | "HTML"; inlineKeyboard?: InlineKeyboard } = {},
-): Promise<boolean> {
-  const body: Record<string, unknown> = {
-    chat_id: chatId,
-    message_id: messageId,
-    text,
-  };
-
-  if (options.parseMode) body.parse_mode = options.parseMode;
-  if (options.inlineKeyboard) {
-    body.reply_markup = { inline_keyboard: options.inlineKeyboard };
-  } else {
-    body.reply_markup = { inline_keyboard: [] };
-  }
-
-  try {
-    const res = await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/editMessageText`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    });
-    const data = (await res.json()) as { ok: boolean };
-    return data.ok;
-  } catch (err) {
-    ctx.logger.error("Telegram editMessage failed", { error: String(err) });
-    return false;
-  }
-}
-
-export async function answerCallbackQuery(
-  ctx: PluginContext,
-  token: string,
-  callbackQueryId: string,
-  text: string,
-): Promise<void> {
-  try {
-    await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/answerCallbackQuery`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        callback_query_id: callbackQueryId,
-        text,
-      }),
-    });
-  } catch (err) {
-    ctx.logger.error("Telegram answerCallbackQuery failed", { error: String(err) });
-  }
-}
-
-export async function setMyCommands(
-  ctx: PluginContext,
-  token: string,
-  commands: Array<{ command: string; description: string }>,
-): Promise<boolean> {
-  try {
-    const res = await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/setMyCommands`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ commands }),
-    });
-    const data = (await res.json()) as { ok: boolean };
-    return data.ok;
-  } catch (err) {
-    ctx.logger.error("Telegram setMyCommands failed", { error: String(err) });
-    return false;
-  }
-}
-
-export async function sendChatAction(
-  ctx: PluginContext,
-  token: string,
-  chatId: string,
-  action: "typing" = "typing",
-): Promise<void> {
-  try {
-    await ctx.http.fetch(`${TELEGRAM_API}/bot${token}/sendChatAction`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ chat_id: chatId, action }),
-    });
-  } catch {
-    // Typing indicator failures are non-critical
-  }
-}
-
-// MarkdownV2 requires escaping these characters
-const MD_ESCAPE_CHARS = /([_*\[\]()~`>#+\-=|{}.!\\])/g;
-
-export function escapeMarkdownV2(text: string): string {
-  return text.replace(MD_ESCAPE_CHARS, "\\$1");
-}
-
-export function truncateAtWord(text: string, maxLen: number): string {
-  if (text.length <= maxLen) return text;
-  const truncated = text.slice(0, maxLen);
-  const lastSpace = truncated.lastIndexOf(" ");
-  return (lastSpace > maxLen * 0.7 ? truncated.slice(0, lastSpace) : truncated) + "...";
-}
-
-function stripMarkdown(text: string): string {
-  return text
-    .replace(/\\([_*\[\]()~`>#+\-=|{}.!\\])/g, "$1")
-    .replace(/[*_`~]/g, "");
-}