@agentprojectcontext/apx 1.32.0 → 1.32.2

package/src/host/daemon/index.js

@@ -14,17 +14,17 @@ import {
   LOG_PATH,
   APX_HOME,
   TOKEN_PATH,
-} from "../../core/config.js";
+} from "#core/config/index.js";
 import { ProjectManager } from "./db.js";
-import { McpRegistry } from "../../core/mcp/runner.js";
+import { McpRegistry } from "#core/mcp/runner.js";
 import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
 import { registerDesktopClient } from "./desktop-ws.js";
-import { log as logToUnified } from "../../core/logging.js";
-import { initMemory, stopMemory } from "../../core/memory/index.js";
+import { log as logToUnified } from "#core/logging.js";
+import { initMemory, stopMemory } from "#core/memory/index.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);

package/src/host/daemon/plugins/{desktop.js → desktop/index.js}

@@ -21,11 +21,13 @@ import {
   broadcastDesktop,
   sendToClient,
   setDesktopMessageHandler,
-} from "../desktop-ws.js";
-import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
-import { appendGlobalMessage } from "../../../core/messages-store.js";
+} from "../../desktop-ws.js";
+import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
 
-const CHANNEL = "desktop";
+const CHANNEL = CHANNELS.DESKTOP;
 
 export default {
   id: "desktop",
@@ -128,12 +130,15 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
 
     log(`desktop: super-agent turn start — model=${cfg.model || config?.super_agent?.model || "(default)"} text="${text.slice(0, 60)}"`);
     const t0 = Date.now();
+    const slashed = tryResolveSkillCommand(text);
+    const slashedPrompt = slashed.handled ? slashed.prompt : text;
     const result = await runSuperAgent({
       globalConfig: config,
       projects,
       plugins,
-      prompt: text,
-      channel: "desktop",
+      prompt: slashedPrompt,
+      channel: CHANNELS.DESKTOP,
+      ...(slashed.handled ? { contextNote: slashed.contextNote } : {}),
       channelMeta: { voice: true }, // desktop module is voice-first → spoken mode
       previousMessages: history.slice(0, -1),
       overrideModel: cfg.model || null,

package/src/host/daemon/plugins/index.js

@@ -12,8 +12,8 @@
 //
 // Plugins are discovered by static import here. Adding a new plugin = importing
 // it and pushing into PLUGINS.
-import telegramPlugin from "./telegram.js";
-import desktopPlugin from "./desktop.js";
+import telegramPlugin from "./telegram/index.js";
+import desktopPlugin from "./desktop/index.js";
 
 export const PLUGINS = [telegramPlugin, desktopPlugin];
 

package/src/host/daemon/plugins/{telegram.js → telegram/index.js}

@@ -29,23 +29,26 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { TELEGRAM_STATE_PATH, APX_HOME } from "../../../core/config.js";
-import { callEngine } from "../../../core/engines/index.js";
-import { runSuperAgent, isSuperAgentEnabled } from "../super-agent.js";
-import { stripThinking } from "../thinking.js";
-import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "../../../core/messages-store.js";
-import { compactChannelIfNeeded } from "../../../core/memory/index.js";
-import { readAgents } from "../../../core/parser.js";
-import { buildAgentSystem } from "../../../core/agent-system.js";
-import { transcribe as transcribeAudioFile } from "../transcription.js";
-import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "../../../core/identity.js";
-import { registerSender, resolveAllowedTools } from "../../../core/telegram-identity.js";
-import { buildRelationshipBlock } from "../../../core/agent/index.js";
-import { getConfirmationStore as getConfirmStore } from "../../../core/confirmation/pending-store.js";
-import { createTelegramConfirmAdapter } from "../../../core/confirmation/adapters/telegram.js";
-import * as askFlow from "./telegram-ask.js";
-
-const API_BASE = "https://api.telegram.org";
+import { TELEGRAM_STATE_PATH, APX_HOME } from "#core/config/index.js";
+import { callEngine } from "#core/engines/index.js";
+import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
+import { stripThinking } from "../../thinking.js";
+import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
+import { compactChannelIfNeeded } from "#core/memory/index.js";
+import { readAgents } from "#core/apc/parser.js";
+import { buildAgentSystem } from "#core/agent/build-agent-system.js";
+import { transcribe as transcribeAudioFile } from "../../transcription.js";
+import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+import { registerSender, resolveAllowedTools } from "#core/identity/telegram.js";
+import { buildRelationshipBlock } from "#core/agent/index.js";
+import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { tryResolveSkillCommand } from "#core/agent/skills/trigger.js";
+import { isLikelyDuplicate } from "#core/util/text-similarity.js";
+import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
+import * as askFlow from "./ask.js";
+
+// API_BASE re-imported from ./media.js below
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
 // Build the channelMeta passed to the super-agent loop. The prompt template at
@@ -85,159 +88,9 @@ function buildTelegramMeta({ channelName, author, chatId, target, routeToAgent }
   };
 }
 
-// ---------- media sending helpers -------------------------------------------
-
-/**
- * Send a photo to a Telegram chat.
- * @param {string} token     Bot token
- * @param {string|number} chatId  Telegram chat_id
- * @param {string|Buffer} photo   Absolute file path OR Buffer of image data
- * @param {object} [opts]
- * @param {string} [opts.caption]
- * @param {string} [opts.parse_mode]  "HTML" | "Markdown" | "MarkdownV2"
- */
-export async function sendPhoto(token, chatId, photo, { caption, parse_mode } = {}) {
-  const url = `${API_BASE}/bot${token}/sendPhoto`;
-  const form = new FormData();
-  form.append("chat_id", String(chatId));
-  if (caption) form.append("caption", caption);
-  if (parse_mode) form.append("parse_mode", parse_mode);
-
-  if (typeof photo === "string" && photo.startsWith("http")) {
-    // Public URL — send as string
-    form.append("photo", photo);
-  } else {
-    // Local file path or Buffer
-    const buf = Buffer.isBuffer(photo) ? photo : fs.readFileSync(photo);
-    const name = typeof photo === "string" ? path.basename(photo) : "photo.jpg";
-    const blob = new Blob([buf], { type: name.endsWith(".png") ? "image/png" : "image/jpeg" });
-    form.append("photo", blob, name);
-  }
-
-  const res = await fetch(url, { method: "POST", body: form });
-  const json = await res.json();
-  if (!json.ok) throw new Error(`sendPhoto failed: ${json.description || res.status}`);
-  return json.result;
-}
-
-/**
- * Send a voice message (OGG/Opus preferred by Telegram).
- * @param {string} token
- * @param {string|number} chatId
- * @param {string|Buffer} audio  Path or Buffer
- * @param {object} [opts]
- * @param {string} [opts.caption]
- * @param {number} [opts.duration]
- */
-export async function sendVoice(token, chatId, audio, { caption, duration } = {}) {
-  const url = `${API_BASE}/bot${token}/sendVoice`;
-  const form = new FormData();
-  form.append("chat_id", String(chatId));
-  if (caption) form.append("caption", caption);
-  if (duration) form.append("duration", String(duration));
-
-  const buf = Buffer.isBuffer(audio) ? audio : fs.readFileSync(audio);
-  const name = typeof audio === "string" ? path.basename(audio) : "voice.ogg";
-  const blob = new Blob([buf], { type: "audio/ogg" });
-  form.append("voice", blob, name);
-
-  const res = await fetch(url, { method: "POST", body: form });
-  const json = await res.json();
-  if (!json.ok) throw new Error(`sendVoice failed: ${json.description || res.status}`);
-  return json.result;
-}
-
-/**
- * Send an audio file (MP3, M4A, etc — shown in Telegram music player).
- * @param {string} token
- * @param {string|number} chatId
- * @param {string|Buffer} audio  Path or Buffer
- * @param {object} [opts]
- * @param {string} [opts.caption]
- * @param {string} [opts.title]
- * @param {string} [opts.performer]
- */
-/**
- * Send any file as a Telegram document (PDF, zip, txt, etc).
- * @param {string} token
- * @param {string|number} chatId
- * @param {string|Buffer} document  Path or Buffer of document data
- * @param {object} [opts]
- * @param {string} [opts.caption]
- * @param {string} [opts.filename] override filename for Buffer input
- * @param {string} [opts.mime_type]
- */
-export async function sendDocument(token, chatId, document, { caption, filename, mime_type } = {}) {
-  const url = `${API_BASE}/bot${token}/sendDocument`;
-  const form = new FormData();
-  form.append("chat_id", String(chatId));
-  if (caption) form.append("caption", caption);
-
-  // URL string → let Telegram fetch it
-  if (typeof document === "string" && /^https?:\/\//.test(document)) {
-    form.append("document", document);
-  } else {
-    const buf = Buffer.isBuffer(document) ? document : fs.readFileSync(document);
-    const name =
-      filename ||
-      (typeof document === "string" ? path.basename(document) : "document.bin");
-    const blob = new Blob([buf], { type: mime_type || "application/octet-stream" });
-    form.append("document", blob, name);
-  }
-
-  const res = await fetch(url, { method: "POST", body: form });
-  const json = await res.json();
-  if (!json.ok) throw new Error(`sendDocument failed: ${json.description || res.status}`);
-  return json.result;
-}
-
-export async function sendAudio(token, chatId, audio, { caption, title, performer } = {}) {
-  const url = `${API_BASE}/bot${token}/sendAudio`;
-  const form = new FormData();
-  form.append("chat_id", String(chatId));
-  if (caption) form.append("caption", caption);
-  if (title) form.append("title", title);
-  if (performer) form.append("performer", performer);
-
-  const buf = Buffer.isBuffer(audio) ? audio : fs.readFileSync(audio);
-  const name = typeof audio === "string" ? path.basename(audio) : "audio.mp3";
-  const blob = new Blob([buf], { type: "audio/mpeg" });
-  form.append("audio", blob, name);
-
-  const res = await fetch(url, { method: "POST", body: form });
-  const json = await res.json();
-  if (!json.ok) throw new Error(`sendAudio failed: ${json.description || res.status}`);
-  return json.result;
-}
-
-// Audio transcription is delegated to the central dispatcher
-// (../transcription.js) which handles local (faster-whisper via Python) +
-// OpenAI cloud fallback. See that module for config keys.
-
-/**
- * Download a file from Telegram servers.
- * Returns the local file path where it was saved.
- */
-async function downloadTelegramFile(token, fileId, destDir) {
-  // Step 1: get file path from Telegram
-  const infoRes = await fetch(`${API_BASE}/bot${token}/getFile?file_id=${fileId}`);
-  const infoJson = await infoRes.json();
-  if (!infoJson.ok) throw new Error(`getFile failed: ${infoJson.description}`);
-  const filePath = infoJson.result.file_path; // e.g. "photos/file_123.jpg"
-  const ext = path.extname(filePath) || ".jpg";
-  const fileName = `tg_${fileId.slice(-8)}_${Date.now()}${ext}`;
-  const localPath = path.join(destDir, fileName);
-
-  // Step 2: download
-  const dlRes = await fetch(`${API_BASE}/file/bot${token}/${filePath}`);
-  if (!dlRes.ok) throw new Error(`download failed: ${dlRes.status}`);
-  const buf = Buffer.from(await dlRes.arrayBuffer());
-  fs.writeFileSync(localPath, buf);
-  return localPath;
-}
-
-// ---------- shared state ----------------------------------------------------
-
+// Media sending helpers moved to ./media.js.
+import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "./media.js";
+export { sendPhoto, sendVoice, sendDocument, sendAudio };
 function loadState() {
   if (!fs.existsSync(TELEGRAM_STATE_PATH)) return { channels: {} };
   try {
@@ -485,7 +338,7 @@ class ChannelPoller {
         const localPath = await downloadTelegramFile(token, bestPhoto.file_id, mediaDir);
         this.log(`telegram[${this.channel.name}] photo saved: ${localPath}`);
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "in",
           type: "photo",
           actor_id: msg.from?.id ? String(msg.from.id) : author,
@@ -551,7 +404,7 @@ class ChannelPoller {
         : `[audio] (transcription unavailable${transcribeError ? ": " + transcribeError : ""})`;
 
       appendGlobalMessage({
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         direction: "in",
         type: "audio",
         actor_id: msg.from?.id ? String(msg.from.id) : author,
@@ -584,7 +437,7 @@ class ChannelPoller {
     if (chat_id && text && await this._maybeConsumeAskTextAnswer({ chat_id, text })) {
       // Still log the inbound so the chat history records what the user said.
       appendGlobalMessage({
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         direction: "in",
         type: "user",
         actor_id: msg.from?.id ? String(msg.from.id) : author,
@@ -623,7 +476,7 @@ class ChannelPoller {
       // the next turn reads a [RESUMEN COMPACTADO] instead of raw history. Never
       // awaited — adds zero latency to this reply, degrades gracefully.
       compactChannelIfNeeded({
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         chat_id,
         config: this.globalConfig,
         log: this.log,
@@ -647,7 +500,7 @@ class ChannelPoller {
 
     // Always log inbound to global store (~/.apx/messages/telegram/)
     appendGlobalMessage({
-      channel: "telegram",
+      channel: CHANNELS.TELEGRAM,
       direction: "in",
       type: "user",
       actor_id: msg.from?.id ? String(msg.from.id) : author,
@@ -679,7 +532,7 @@ class ChannelPoller {
         const ack = "Done, context cleared. Starting fresh. What do you need?";
         await this._send({ chat_id, text: ack });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "agent",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -703,7 +556,7 @@ class ChannelPoller {
     let replyActorId;   // stable id: super_agent | agent slug
     let replyKind;      // actor_kind: superagent | agent
     const projectCfg = target.config || this.globalConfig;
-    // Display name for the super-agent persona on this channel (Roby / APX).
+    // Display name for the super-agent persona on this channel (from identity.json).
     const agentDisplay = resolveAgentName(this.globalConfig);
 
     // Try the project's chosen agent first (skipped if the legacy
@@ -777,7 +630,7 @@ class ChannelPoller {
             const heads = headsUpPhrase();
             await this._send({ chat_id, text: heads });
             appendGlobalMessage({
-              channel: "telegram",
+              channel: CHANNELS.TELEGRAM,
               direction: "out",
               type: "agent",
               actor_id: SUPERAGENT_ACTOR_ID,
@@ -792,11 +645,17 @@ class ChannelPoller {
           if (ev.type === "assistant_text" && ev.text) {
             const piece = stripThinking(ev.text).trim();
             if (!piece) return;
+            // Skip post-tool segments that just restate the pre-tool intro —
+            // weaker models (gemini-flash et al.) frequently paraphrase the
+            // same content twice within a single turn.
+            if (lastStreamedText && isLikelyDuplicate(piece, lastStreamedText)) {
+              return;
+            }
             await this._send({ chat_id, text: piece });
             lastStreamedText = piece;
             streamedCount += 1;
             appendGlobalMessage({
-              channel: "telegram",
+              channel: CHANNELS.TELEGRAM,
               direction: "out",
               type: "agent",
               actor_id: SUPERAGENT_ACTOR_ID,
@@ -816,7 +675,7 @@ class ChannelPoller {
             // Logged for the audit trail / other channels — NOT sent to Telegram.
             const t = ev.trace;
             appendGlobalMessage({
-              channel: "telegram",
+              channel: CHANNELS.TELEGRAM,
               direction: "out",
               type: "tool",
               actor_id: t.tool,
@@ -846,17 +705,24 @@ class ChannelPoller {
         pendingStore: getConfirmStore(),
       });
 
+      // `/slug ...` shortcut: load the matching skill body into contextNote
+      // and strip the prefix from the user prompt before sending to the loop.
+      const slashed = tryResolveSkillCommand(text, { projectPath: target?.path });
+      const slashedPrompt = slashed.handled ? slashed.prompt : text;
+      const slashedContextNote = slashed.handled ? slashed.contextNote : "";
+
       try {
         const sa = await runSuperAgent({
           globalConfig: this.globalConfig,
           projects: this.projects,
           plugins: this.plugins,
           registries: this.registries,
-          prompt: text,
+          prompt: slashedPrompt,
           previousMessages,
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           relationshipBlock,
           allowedTools,
+          contextNote: slashedContextNote || undefined,
           channelMeta: buildTelegramMeta({
             channelName: this.channel.name,
             author,
@@ -932,8 +798,13 @@ class ChannelPoller {
     // turn isn't silently empty.
     const finalClean = replyText ? stripThinking(replyText).trim() : "";
     let toSend = "";
-    if (finalClean && finalClean !== lastStreamedText) toSend = finalClean;
-    else if (!finalClean && streamedCount === 0) toSend = "Listo.";
+    // Fuzzy dedupe against the last streamed segment: catches paraphrases
+    // (Jaccard ≥ 0.4 or short-mostly-inside-long), not just exact matches.
+    if (finalClean && !isLikelyDuplicate(finalClean, lastStreamedText) && finalClean !== lastStreamedText) {
+      toSend = finalClean;
+    } else if (!finalClean && streamedCount === 0) {
+      toSend = "Listo.";
+    }
 
     stopTyping();
     if (!toSend) return; // everything was already streamed — nothing left to send
@@ -949,7 +820,7 @@ class ChannelPoller {
       if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
       if (saUsage) meta.usage = saUsage;
       appendGlobalMessage({
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         direction: "out",
         type: "agent",
         actor_id: replyActorId || SUPERAGENT_ACTOR_ID,
@@ -962,7 +833,7 @@ class ChannelPoller {
     } catch (e) {
       this.log(`telegram[${this.channel.name}] send-back error: ${e.message}`);
       appendGlobalMessage({
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         direction: "out",
         type: "agent",
         actor_id: replyActorId || SUPERAGENT_ACTOR_ID,
@@ -1138,7 +1009,7 @@ class ChannelPoller {
     // it up on the NEXT inbound. Mirrors how a normal text reply would be
     // recorded.
     appendGlobalMessage({
-      channel: "telegram",
+      channel: CHANNELS.TELEGRAM,
       direction: "in",
       type: "user",
       actor_id: authorId ? String(authorId) : (author || "ask_flow"),
@@ -1168,10 +1039,10 @@ class ChannelPoller {
         registries: this.registries,
         prompt: compiled,
         previousMessages,
-        channel: "telegram",
+        channel: CHANNELS.TELEGRAM,
         relationshipBlock,
         allowedTools,
-        channelMeta: { channel: "telegram", chat_id, author, route_to_agent: this.channel.route_to_agent },
+        channelMeta: { channel: CHANNELS.TELEGRAM, chat_id, author, route_to_agent: this.channel.route_to_agent },
       });
       stopTyping();
 
@@ -1198,7 +1069,7 @@ class ChannelPoller {
       if (replyText) {
         await this._send({ chat_id, text: replyText });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "agent",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -1401,7 +1272,7 @@ export default {
         if (!p) throw new Error("no telegram channel available");
         const result = await p._send({ chat_id, text });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "agent",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -1431,7 +1302,7 @@ export default {
         if (!p) throw new Error("no telegram channel available");
         const result = await p._sendPhoto({ chat_id, photo, caption, parse_mode });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "photo",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -1455,7 +1326,7 @@ export default {
         if (!p) throw new Error("no telegram channel available");
         const result = await p._sendVoice({ chat_id, audio, caption, duration });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "voice",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -1479,7 +1350,7 @@ export default {
         if (!p) throw new Error("no telegram channel available");
         const result = await p._sendDocument({ chat_id, document, caption, filename, mime_type });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "document",
           actor_id: SUPERAGENT_ACTOR_ID,
@@ -1503,7 +1374,7 @@ export default {
         if (!p) throw new Error("no telegram channel available");
         const result = await p._sendAudio({ chat_id, audio, caption, title, performer });
         appendGlobalMessage({
-          channel: "telegram",
+          channel: CHANNELS.TELEGRAM,
           direction: "out",
           type: "audio",
           actor_id: SUPERAGENT_ACTOR_ID,

package/src/host/daemon/plugins/telegram/media.js

@@ -0,0 +1,162 @@
+// Telegram media helpers: send photo/voice/document/audio + download a remote
+// file. Auto-extracted from plugins/telegram/index.js — these used to live
+// inline next to the poll loop and the super-agent dispatch.
+//
+// Each helper takes the bot token and chat id explicitly so they can be used
+// from any code path (tests, other plugins, future agents). Buffer or
+// absolute path input is accepted for media; for URLs the helpers pass them
+// through to Telegram and let the API fetch them.
+import fs from "node:fs";
+import path from "node:path";
+
+export const API_BASE = "https://api.telegram.org";
+
+/**
+ * Send a photo to a Telegram chat.
+ * @param {string} token     Bot token
+ * @param {string|number} chatId  Telegram chat_id
+ * @param {string|Buffer} photo   Absolute file path OR Buffer of image data
+ * @param {object} [opts]
+ * @param {string} [opts.caption]
+ * @param {string} [opts.parse_mode]  "HTML" | "Markdown" | "MarkdownV2"
+ */
+export async function sendPhoto(token, chatId, photo, { caption, parse_mode } = {}) {
+  const url = `${API_BASE}/bot${token}/sendPhoto`;
+  const form = new FormData();
+  form.append("chat_id", String(chatId));
+  if (caption) form.append("caption", caption);
+  if (parse_mode) form.append("parse_mode", parse_mode);
+
+  if (typeof photo === "string" && photo.startsWith("http")) {
+    // Public URL — send as string
+    form.append("photo", photo);
+  } else {
+    // Local file path or Buffer
+    const buf = Buffer.isBuffer(photo) ? photo : fs.readFileSync(photo);
+    const name = typeof photo === "string" ? path.basename(photo) : "photo.jpg";
+    const blob = new Blob([buf], { type: name.endsWith(".png") ? "image/png" : "image/jpeg" });
+    form.append("photo", blob, name);
+  }
+
+  const res = await fetch(url, { method: "POST", body: form });
+  const json = await res.json();
+  if (!json.ok) throw new Error(`sendPhoto failed: ${json.description || res.status}`);
+  return json.result;
+}
+
+/**
+ * Send a voice message (OGG/Opus preferred by Telegram).
+ * @param {string} token
+ * @param {string|number} chatId
+ * @param {string|Buffer} audio  Path or Buffer
+ * @param {object} [opts]
+ * @param {string} [opts.caption]
+ * @param {number} [opts.duration]
+ */
+export async function sendVoice(token, chatId, audio, { caption, duration } = {}) {
+  const url = `${API_BASE}/bot${token}/sendVoice`;
+  const form = new FormData();
+  form.append("chat_id", String(chatId));
+  if (caption) form.append("caption", caption);
+  if (duration) form.append("duration", String(duration));
+
+  const buf = Buffer.isBuffer(audio) ? audio : fs.readFileSync(audio);
+  const name = typeof audio === "string" ? path.basename(audio) : "voice.ogg";
+  const blob = new Blob([buf], { type: "audio/ogg" });
+  form.append("voice", blob, name);
+
+  const res = await fetch(url, { method: "POST", body: form });
+  const json = await res.json();
+  if (!json.ok) throw new Error(`sendVoice failed: ${json.description || res.status}`);
+  return json.result;
+}
+
+/**
+ * Send an audio file (MP3, M4A, etc — shown in Telegram music player).
+ * @param {string} token
+ * @param {string|number} chatId
+ * @param {string|Buffer} audio  Path or Buffer
+ * @param {object} [opts]
+ * @param {string} [opts.caption]
+ * @param {string} [opts.title]
+ * @param {string} [opts.performer]
+ */
+/**
+ * Send any file as a Telegram document (PDF, zip, txt, etc).
+ * @param {string} token
+ * @param {string|number} chatId
+ * @param {string|Buffer} document  Path or Buffer of document data
+ * @param {object} [opts]
+ * @param {string} [opts.caption]
+ * @param {string} [opts.filename] override filename for Buffer input
+ * @param {string} [opts.mime_type]
+ */
+export async function sendDocument(token, chatId, document, { caption, filename, mime_type } = {}) {
+  const url = `${API_BASE}/bot${token}/sendDocument`;
+  const form = new FormData();
+  form.append("chat_id", String(chatId));
+  if (caption) form.append("caption", caption);
+
+  // URL string → let Telegram fetch it
+  if (typeof document === "string" && /^https?:\/\//.test(document)) {
+    form.append("document", document);
+  } else {
+    const buf = Buffer.isBuffer(document) ? document : fs.readFileSync(document);
+    const name =
+      filename ||
+      (typeof document === "string" ? path.basename(document) : "document.bin");
+    const blob = new Blob([buf], { type: mime_type || "application/octet-stream" });
+    form.append("document", blob, name);
+  }
+
+  const res = await fetch(url, { method: "POST", body: form });
+  const json = await res.json();
+  if (!json.ok) throw new Error(`sendDocument failed: ${json.description || res.status}`);
+  return json.result;
+}
+
+export async function sendAudio(token, chatId, audio, { caption, title, performer } = {}) {
+  const url = `${API_BASE}/bot${token}/sendAudio`;
+  const form = new FormData();
+  form.append("chat_id", String(chatId));
+  if (caption) form.append("caption", caption);
+  if (title) form.append("title", title);
+  if (performer) form.append("performer", performer);
+
+  const buf = Buffer.isBuffer(audio) ? audio : fs.readFileSync(audio);
+  const name = typeof audio === "string" ? path.basename(audio) : "audio.mp3";
+  const blob = new Blob([buf], { type: "audio/mpeg" });
+  form.append("audio", blob, name);
+
+  const res = await fetch(url, { method: "POST", body: form });
+  const json = await res.json();
+  if (!json.ok) throw new Error(`sendAudio failed: ${json.description || res.status}`);
+  return json.result;
+}
+
+// Audio transcription is delegated to the central dispatcher
+// (../transcription.js) which handles local (faster-whisper via Python) +
+// OpenAI cloud fallback. See that module for config keys.
+
+/**
+ * Download a file from Telegram servers.
+ * Returns the local file path where it was saved.
+ */
+export async function downloadTelegramFile(token, fileId, destDir) {
+  // Step 1: get file path from Telegram
+  const infoRes = await fetch(`${API_BASE}/bot${token}/getFile?file_id=${fileId}`);
+  const infoJson = await infoRes.json();
+  if (!infoJson.ok) throw new Error(`getFile failed: ${infoJson.description}`);
+  const filePath = infoJson.result.file_path; // e.g. "photos/file_123.jpg"
+  const ext = path.extname(filePath) || ".jpg";
+  const fileName = `tg_${fileId.slice(-8)}_${Date.now()}${ext}`;
+  const localPath = path.join(destDir, fileName);
+
+  // Step 2: download
+  const dlRes = await fetch(`${API_BASE}/file/bot${token}/${filePath}`);
+  if (!dlRes.ok) throw new Error(`download failed: ${dlRes.status}`);
+  const buf = Buffer.from(await dlRes.arrayBuffer());
+  fs.writeFileSync(localPath, buf);
+  return localPath;
+}
+