totem-llm 0.1.0

package/server/utils/telegramBot/utils/media.js

@@ -0,0 +1,163 @@
+/**
+ * Download a file from Telegram by file ID.
+ * @param {TelegramBot} bot
+ * @param {string} fileId
+ * @returns {Promise<Buffer>}
+ */
+async function downloadTelegramFile(bot, fileId) {
+  const fileLink = await bot.getFileLink(fileId);
+  const response = await fetch(fileLink);
+  if (!response.ok) throw new Error("Failed to download file from Telegram");
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/**
+ * Get appropriate file extension from MIME type.
+ * @param {string} mimeType
+ * @returns {string}
+ */
+function getExtensionFromMime(mimeType) {
+  const mimeToExt = {
+    "audio/ogg": ".ogg",
+    "audio/oga": ".ogg",
+    "audio/opus": ".opus",
+    "audio/mp3": ".mp3",
+    "audio/mpeg": ".mp3",
+    "audio/wav": ".wav",
+    "audio/x-wav": ".wav",
+    "audio/mp4": ".m4a",
+    "audio/m4a": ".m4a",
+    "audio/webm": ".webm",
+    "audio/flac": ".flac",
+  };
+  return mimeToExt[mimeType] || ".ogg"; // Default to .ogg for unknown (common for Telegram mobile)
+}
+
+/**
+ * Transcribe an audio buffer using the configured whisper provider.
+ * Writes the audio to the collector hotdir and runs it through the
+ * same parse pipeline used for document processing.
+ * @param {Buffer} audioBuffer
+ * @param {string} [mimeType] - The MIME type of the audio (e.g., "audio/ogg")
+ * @returns {Promise<string>}
+ */
+async function transcribeAudio(audioBuffer, mimeType = "audio/ogg") {
+  const fs = require("fs");
+  const path = require("path");
+  const { CollectorApi } = require("../../collectorApi");
+  const { hotdirPath } = require("../../files");
+
+  if (!fs.existsSync(hotdirPath)) fs.mkdirSync(hotdirPath, { recursive: true });
+
+  const ext = getExtensionFromMime(mimeType);
+  const filename = `telegram-voice-${Date.now()}${ext}`;
+  fs.writeFileSync(path.join(hotdirPath, filename), audioBuffer);
+
+  const collector = new CollectorApi();
+  const result = await collector.parseDocument(filename);
+  if (!result?.success || !result.documents?.length) {
+    throw new Error(result?.reason || "Failed to transcribe audio.");
+  }
+  return result.documents[0].pageContent;
+}
+
+/**
+ * Parse a document buffer and extract its text content.
+ * Writes the document to the collector hotdir and runs it through
+ * the collector's parse pipeline.
+ * @param {Buffer} documentBuffer
+ * @param {string} originalFilename - The original filename with extension
+ * @returns {Promise<{text: string, filename: string}>}
+ */
+async function documentToText(documentBuffer, originalFilename) {
+  const fs = require("fs");
+  const path = require("path");
+  const { CollectorApi } = require("../../collectorApi");
+  const { hotdirPath } = require("../../files");
+
+  if (!fs.existsSync(hotdirPath)) fs.mkdirSync(hotdirPath, { recursive: true });
+
+  const sanitizedName = originalFilename.replace(/[^a-zA-Z0-9._-]/g, "_");
+  const filename = `telegram-doc-${Date.now()}-${sanitizedName}`;
+  fs.writeFileSync(path.join(hotdirPath, filename), documentBuffer);
+
+  const collector = new CollectorApi();
+  if (!(await collector.online())) {
+    throw new Error(
+      "Document processing is unavailable. The collector service is offline."
+    );
+  }
+
+  const result = await collector.parseDocument(filename);
+  if (!result?.success || !result.documents?.length) {
+    throw new Error(
+      result?.reason || `Failed to parse document: ${originalFilename}`
+    );
+  }
+
+  const text = result.documents.map((doc) => doc.pageContent).join("\n\n");
+  return { text, filename: originalFilename };
+}
+
+/**
+ * Download the largest photo from a Telegram photo array and return
+ * it as an attachment object compatible with the LLM chat pipeline.
+ * @param {TelegramBot} bot
+ * @param {Array} photos - Telegram PhotoSize array (ascending size)
+ * @returns {Promise<{name: string, mime: string, contentString: string}>}
+ */
+async function photoToAttachment(bot, photos) {
+  const largest = photos[photos.length - 1];
+  const buffer = await downloadTelegramFile(bot, largest.file_id);
+  const base64 = buffer.toString("base64");
+  return {
+    name: "telegram-photo.jpg",
+    mime: "image/jpeg",
+    contentString: `data:image/jpeg;base64,${base64}`,
+  };
+}
+
+/**
+ * Convert text to speech and send as an audio message in Telegram.
+ * Silently does nothing if TTS is not configured.
+ * @param {TelegramBot} bot
+ * @param {number} chatId
+ * @param {string} text
+ */
+/**
+ * @returns {Promise<boolean>} true if voice was sent, false if TTS failed
+ */
+async function sendVoiceResponse(bot, chatId, text) {
+  try {
+    const { getTTSProvider } = require("../../TextToSpeech");
+    const provider = getTTSProvider();
+    const buffer = await provider.ttsBuffer(text);
+    if (!buffer) return false;
+    await bot.sendAudio(
+      chatId,
+      buffer,
+      {},
+      {
+        filename: `${chatId}-response.mp3`,
+        contentType: "audio/mpeg",
+      }
+    );
+    return true;
+  } catch {
+    await bot
+      .sendMessage(
+        chatId,
+        "Voice responses require a text-to-speech provider. Set one up in Settings > Voice & Speech > Text-to-Speech Preference."
+      )
+      .catch(() => {});
+    return false;
+  }
+}
+
+module.exports = {
+  downloadTelegramFile,
+  transcribeAudio,
+  documentToText,
+  photoToAttachment,
+  sendVoiceResponse,
+};

package/server/utils/telegramBot/utils/messageQueue.js

@@ -0,0 +1,53 @@
+/**
+ * A simple per-key async message queue that ensures sequential processing.
+ * Reusable across any connector (Telegram, Discord, Slack, etc.)
+ * where concurrent messages from the same source must be processed in order.
+ *
+ * Usage:
+ *   const queue = new MessageQueue();
+ *   queue.enqueue(userId, async () => { ... });
+ */
+class MessageQueue {
+  #chains = new Map();
+
+  /**
+   * Enqueue an async handler to run after all prior handlers for this key complete.
+   * Different keys run in parallel; same key runs sequentially.
+   * @param {string|number} key - Unique identifier (e.g. chat ID, user ID)
+   * @param {() => Promise<void>} handler - Async function to execute
+   * @returns {Promise<void>}
+   */
+  enqueue(key, handler) {
+    const prev = this.#chains.get(key) || Promise.resolve();
+    const chain = prev
+      .then(handler)
+      .catch((err) =>
+        console.error(`[MessageQueue] Error processing key ${key}:`, err)
+      )
+      .finally(() => {
+        // Clean up if this is the last item in the chain
+        if (this.#chains.get(key) === chain) {
+          this.#chains.delete(key);
+        }
+      });
+    this.#chains.set(key, chain);
+    return chain;
+  }
+
+  /**
+   * Clear all pending chains. Does not cancel in-flight work.
+   */
+  clear() {
+    this.#chains.clear();
+  }
+
+  /**
+   * Number of active keys being processed.
+   * @returns {number}
+   */
+  get size() {
+    return this.#chains.size;
+  }
+}
+
+module.exports = { MessageQueue };

package/server/utils/telegramBot/utils/navigation/callbacks/handleBackSources.js

@@ -0,0 +1,16 @@
+const { showSourcesMenu } = require("../../commands/handlers/handleProof");
+
+/**
+ * Handle back to sources - returns to the sources menu.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ */
+async function handleBackSources({ ctx, chatId, query, messageId } = {}) {
+  await showSourcesMenu(ctx, chatId, 0, messageId);
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleBackSources };

package/server/utils/telegramBot/utils/navigation/callbacks/handleBackWorkspaces.js

@@ -0,0 +1,18 @@
+const {
+  showWorkspaceMenu,
+} = require("../../commands/handlers/showWorkspaceMenu");
+
+/**
+ * Handle back navigation to workspace menu.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ */
+async function handleBackWorkspaces({ ctx, chatId, query, messageId } = {}) {
+  await showWorkspaceMenu(ctx, chatId, 0, messageId);
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleBackWorkspaces };

package/server/utils/telegramBot/utils/navigation/callbacks/handleModelCancel.js

@@ -0,0 +1,14 @@
+/**
+ * Handle model selection cancellation.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ */
+async function handleModelCancel({ ctx, chatId, query, messageId } = {}) {
+  await ctx.bot.deleteMessage(chatId, messageId);
+  await ctx.bot.answerCallbackQuery(query.id, { text: "Cancelled" });
+}
+
+module.exports = { handleModelCancel };

package/server/utils/telegramBot/utils/navigation/callbacks/handleModelPagination.js

@@ -0,0 +1,24 @@
+const { showModelMenu } = require("../../commands/handlers/showModelMenu");
+
+/**
+ * Handle model menu pagination.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ * @param {string} params.data
+ */
+async function handleModelPagination({
+  ctx,
+  chatId,
+  query,
+  messageId,
+  data,
+} = {}) {
+  const page = parseInt(data.slice(6), 10);
+  await showModelMenu(ctx, chatId, page, messageId);
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleModelPagination };

package/server/utils/telegramBot/utils/navigation/callbacks/handleModelSelect.js

@@ -0,0 +1,52 @@
+const { Workspace } = require("../../../../../models/workspace");
+const { getCustomModels } = require("../../../../helpers/customModels");
+const { resolveWorkspaceProvider } = require("../../index");
+
+/**
+ * Handle model selection for a workspace.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ * @param {string} params.data
+ */
+async function handleModelSelect({ ctx, chatId, query, messageId, data } = {}) {
+  const parts = data.slice(4).split(":");
+  const workspaceId = parseInt(parts[0], 10);
+  const modelIdPrefix = parts.slice(1).join(":");
+
+  const workspace = await Workspace.get({ id: workspaceId });
+  if (!workspace) {
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Workspace not found.",
+    });
+    return;
+  }
+
+  const { provider } = resolveWorkspaceProvider(workspace);
+  const { models } = await getCustomModels(provider);
+  const selectedModel = models?.find((m) => {
+    const id = m.id || m.name;
+    return id === modelIdPrefix || id.startsWith(modelIdPrefix);
+  });
+
+  if (!selectedModel) {
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Model not found.",
+    });
+    return;
+  }
+
+  const modelId = selectedModel.id || selectedModel.name;
+  await Workspace.update(workspace.id, { chatModel: modelId });
+
+  await ctx.bot.answerCallbackQuery(query.id, { text: "Model updated!" });
+  await ctx.bot.deleteMessage(chatId, messageId);
+  await ctx.bot.sendMessage(
+    chatId,
+    `Model changed to "${selectedModel.name || modelId}" in "${workspace.name}".`
+  );
+}
+
+module.exports = { handleModelSelect };

package/server/utils/telegramBot/utils/navigation/callbacks/handleSourcePagination.js

@@ -0,0 +1,24 @@
+const { showSourcesMenu } = require("../../commands/handlers/handleProof");
+
+/**
+ * Handle source pagination - navigates between source pages.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ * @param {string} params.data
+ */
+async function handleSourcePagination({
+  ctx,
+  chatId,
+  query,
+  messageId,
+  data,
+} = {}) {
+  const page = parseInt(data.slice(6), 10);
+  await showSourcesMenu(ctx, chatId, page, messageId);
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleSourcePagination };

package/server/utils/telegramBot/utils/navigation/callbacks/handleSourceSelect.js

@@ -0,0 +1,106 @@
+const { escapeHTML } = require("../../format");
+const {
+  isWebSource,
+  getSourceTitle,
+} = require("../../commands/handlers/handleProof");
+
+/**
+ * Truncate source text for display.
+ * @param {string} text
+ * @param {number} maxLength
+ * @returns {string}
+ */
+function truncateSourceText(text, maxLength = 3500) {
+  if (!text) return "(No content available)";
+  if (text.length <= maxLength) return text;
+  return text.substring(0, maxLength - 20) + "\n\n[...truncated]";
+}
+
+/**
+ * Extract URL from a web source.
+ * @param {object} source
+ * @returns {string|null}
+ */
+function extractWebUrl(source) {
+  if (!source?.chunkSource?.startsWith("link://")) return null;
+  return source.chunkSource.replace("link://", "");
+}
+
+/**
+ * Handle source selection - shows source content or prompts to open web link.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ * @param {string} params.data
+ */
+async function handleSourceSelect({
+  ctx,
+  chatId,
+  query,
+  messageId,
+  data,
+} = {}) {
+  // Handle close action
+  if (data === "src:close") {
+    await ctx.bot.deleteMessage(chatId, messageId);
+    await ctx.bot.answerCallbackQuery(query.id);
+    return;
+  }
+
+  const sourceIdx = parseInt(data.slice(4), 10);
+  const state = ctx.getState(chatId);
+  const sources = state._proofSources;
+
+  if (!sources || sourceIdx < 0 || sourceIdx >= sources.length) {
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Source not found. Please try /proof again.",
+    });
+    return;
+  }
+
+  const source = sources[sourceIdx];
+  const title = getSourceTitle(source, sourceIdx);
+
+  if (isWebSource(source)) {
+    const url = extractWebUrl(source);
+    if (!url) {
+      await ctx.bot.answerCallbackQuery(query.id, {
+        text: "Invalid web source URL.",
+      });
+      return;
+    }
+
+    const text = `🌐 <b>${escapeHTML(title)}</b>\n\n${url}`;
+    await ctx.bot.editMessageText(text, {
+      chat_id: chatId,
+      message_id: messageId,
+      parse_mode: "HTML",
+      reply_markup: {
+        inline_keyboard: [
+          [{ text: "🔗 Open in Browser", url }],
+          [{ text: "← Back to Sources", callback_data: "src:back" }],
+        ],
+      },
+    });
+  } else {
+    const content = truncateSourceText(source.text);
+    const text = `📄 <b>${escapeHTML(title)}</b>\n\n<blockquote expandable>${escapeHTML(content)}</blockquote>`;
+
+    await ctx.bot.editMessageText(text, {
+      chat_id: chatId,
+      message_id: messageId,
+      parse_mode: "HTML",
+      reply_markup: {
+        inline_keyboard: [
+          [{ text: "← Back to Sources", callback_data: "src:back" }],
+        ],
+      },
+    });
+  }
+
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleSourceSelect };

package/server/utils/telegramBot/utils/navigation/callbacks/handleThreadPagination.js

@@ -0,0 +1,26 @@
+const { showThreadMenu } = require("../../commands/handlers/showThreadMenu");
+
+/**
+ * Handle thread menu pagination.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {number} params.messageId
+ * @param {string} params.data
+ */
+async function handleThreadPagination({
+  ctx,
+  chatId,
+  query,
+  messageId,
+  data,
+} = {}) {
+  const parts = data.slice(5).split(":");
+  const workspaceId = parseInt(parts[0], 10);
+  const page = parseInt(parts[1], 10);
+  await showThreadMenu(ctx, chatId, workspaceId, page, messageId);
+  await ctx.bot.answerCallbackQuery(query.id);
+}
+
+module.exports = { handleThreadPagination };

package/server/utils/telegramBot/utils/navigation/callbacks/handleThreadSelect.js

@@ -0,0 +1,43 @@
+const { Workspace } = require("../../../../../models/workspace");
+const { WorkspaceThread } = require("../../../../../models/workspaceThread");
+
+/**
+ * Handle thread selection - sets active workspace and thread.
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {string} params.data
+ */
+async function handleThreadSelect({ ctx, chatId, query, data } = {}) {
+  const parts = data.slice(3).split(":");
+  const workspaceId = parseInt(parts[0], 10);
+  const threadId = parseInt(parts[1], 10);
+
+  const workspace = await Workspace.get({ id: workspaceId });
+  if (!workspace) {
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Workspace not found.",
+    });
+    return;
+  }
+
+  let threadSlug = null;
+  let threadName = "Default";
+  if (threadId !== 0) {
+    const thread = await WorkspaceThread.get({ id: threadId });
+    if (thread) {
+      threadSlug = thread.slug;
+      threadName = thread.name;
+    }
+  }
+
+  ctx.setState(chatId, { workspaceSlug: workspace.slug, threadSlug });
+  await ctx.bot.answerCallbackQuery(query.id, { text: "Switched!" });
+  await ctx.bot.sendMessage(
+    chatId,
+    `Switched to "${workspace.name}" → ${threadName}`
+  );
+}
+
+module.exports = { handleThreadSelect };

package/server/utils/telegramBot/utils/navigation/callbacks/handleToolApproval.js

@@ -0,0 +1,104 @@
+/**
+ * Handle tool approval callback from an inline keyboard button.
+ * This handler requires access to the pending tool approvals map from TelegramBotService.
+ *
+ * @param {object} params
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query
+ * @param {string} params.data
+ * @param {Map} params.pendingToolApprovals - Map of pending tool approval requests
+ * @param {Function} [params.log] - Logging function (falls back to ctx.log)
+ */
+async function handleToolApproval({
+  ctx,
+  chatId,
+  query,
+  data,
+  pendingToolApprovals,
+  log,
+} = {}) {
+  const _log = log || ctx.log;
+  _log(`Tool approval callback received: ${data}`);
+
+  try {
+    const parts = data.split(":");
+    if (parts.length !== 3) {
+      _log(`Invalid callback data format: ${data}`);
+      await ctx.bot.answerCallbackQuery(query.id, {
+        text: "Invalid request format.",
+      });
+      return;
+    }
+
+    const action = parts[1]; // "approve" or "deny"
+    const requestId = parts[2];
+
+    const pending = pendingToolApprovals.get(requestId);
+    if (!pending) {
+      _log(`No pending approval found for requestId: ${requestId}`);
+      await ctx.bot.answerCallbackQuery(query.id, {
+        text: "This approval request has expired.",
+      });
+      return;
+    }
+
+    const { worker, messageId, skillName } = pending;
+    const approved = action === "approve";
+
+    _log(`Processing ${approved ? "approval" : "denial"} for ${skillName}`);
+
+    // Send response back to worker (Bree workers use send(), raw worker_threads use postMessage())
+    try {
+      const response = {
+        type: "toolApprovalResponse",
+        requestId,
+        approved,
+      };
+
+      if (worker && typeof worker.send === "function") {
+        worker.send(response);
+        _log(
+          `Sent tool approval response to worker via send(): ${approved ? "approved" : "denied"}`
+        );
+      } else if (worker && typeof worker.postMessage === "function") {
+        worker.postMessage(response);
+        _log(
+          `Sent tool approval response to worker via postMessage(): ${approved ? "approved" : "denied"}`
+        );
+      } else {
+        _log(
+          `Worker not available to send approval response (send: ${typeof worker?.send}, postMessage: ${typeof worker?.postMessage})`
+        );
+      }
+    } catch (err) {
+      _log(`Failed to send approval response: ${err.message}`);
+    }
+
+    pendingToolApprovals.delete(requestId);
+
+    // Update the message to show the result
+    const resultText = approved
+      ? `✅ <b>${skillName}</b> was approved.`
+      : `❌ <b>${skillName}</b> was denied.`;
+
+    await ctx.bot
+      .editMessageText(resultText, {
+        chat_id: chatId,
+        message_id: messageId,
+        parse_mode: "HTML",
+      })
+      .catch((err) => _log(`Failed to edit message: ${err.message}`));
+
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: approved ? "Approved!" : "Denied.",
+    });
+  } catch (error) {
+    _log(`Error handling tool approval callback: ${error.message}`);
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Something went wrong.",
+    });
+  }
+}
+
+module.exports = { handleToolApproval };

package/server/utils/telegramBot/utils/navigation/callbacks/handleWorkspaceCreate.js

@@ -0,0 +1,33 @@
+const { Workspace } = require("../../../../../models/workspace");
+
+/**
+ * Handle the creation of a new workspace.
+ * @param {object} params - The parameters for the function
+ * @param {import("../../commands/index").BotContext} params.ctx
+ * @param {number} params.chatId
+ * @param {{id: string}} params.query - Telegram callback query object
+ */
+async function handleWorkspaceCreate({ ctx, chatId, query } = {}) {
+  const botName = ctx.config.bot_username || "Bot";
+  const wsName = `${botName} Workspace`;
+  const { workspace, message: error } = await Workspace.new(wsName, null, {
+    chatMode: "automatic",
+  });
+  if (error || !workspace) {
+    await ctx.bot.answerCallbackQuery(query.id, {
+      text: "Failed to create workspace.",
+    });
+    return;
+  }
+
+  ctx.setState(chatId, { workspaceSlug: workspace.slug, threadSlug: null });
+  await ctx.bot.answerCallbackQuery(query.id, {
+    text: "Workspace created!",
+  });
+  await ctx.bot.sendMessage(
+    chatId,
+    `Created and switched to "${workspace.name}". You can start chatting now!`
+  );
+}
+
+module.exports = { handleWorkspaceCreate };