@agentprojectcontext/apx 1.42.0 → 1.42.2

package/src/core/channels/telegram/dispatch.js

@@ -11,25 +11,22 @@
 // `appendGlobalMessage`, `CHANNELS`, `nowIso`, etc. Top-level imports here
 // keep that scope intact — earlier splits forgot them and the bug only
 // surfaced when a real telegram update arrived (ReferenceError at runtime).
-import path from "node:path";
 import { callEngine } from "#core/engines/index.js";
-import { runSuperAgent, isSuperAgentEnabled } from "#core/agent/super-agent.js";
-import { stripThinking } from "#core/util/thinking.js";
+import { isSuperAgentEnabled } from "#core/agent/super-agent.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 "#core/voice/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 { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
 import * as askFlow from "./ask.js";
-import { buildTelegramMeta, resolveBotToken, sleep } from "./helpers.js";
-import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "./media.js";
+import { telegramAuthorLabel } from "./helpers.js";
+import { handleIncomingPhoto } from "./inbound/photo.js";
+import { handleIncomingAudio } from "./inbound/audio.js";
+import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply } from "./reply.js";
 import { t, resolveLang } from "#core/i18n/index.js";
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -50,10 +47,7 @@ export async function handleUpdate(self, u) {
       self.log(`telegram[${self.channel.name}] update ${u.update_id} ignored — no target project`);
       return;
     }
-    const author =
-      msg.from?.username
-        ? "@" + msg.from.username
-        : `${msg.from?.first_name || ""} ${msg.from?.last_name || ""}`.trim() || "unknown";
+    const author = telegramAuthorLabel(msg.from);
     const chat_id = msg.chat?.id;
 
     // Resolve WHO is writing (owner / known contact / guest), keyed by the
@@ -85,108 +79,18 @@ export async function handleUpdate(self, u) {
 
     let text = msg.text || msg.caption || "";
 
-    // ── Incoming photo handling ───────────────────────────────────────────
+    // ── Incoming media ────────────────────────────────────────────────────
+    // Photo and voice/audio each download + archive the file and rewrite `text`
+    // so the rest of the pipeline treats them like a typed message. The handlers
+    // live in ./inbound/ to keep this dispatcher focused on routing. Photos have
+    // no vision yet, so the handler injects an `[image]` marker (never silent);
+    // audio injects its `[audio]` transcript.
     if (msg.photo && msg.photo.length > 0) {
-      // Telegram sends multiple sizes; pick the largest
-      const bestPhoto = msg.photo.reduce((a, b) => (b.file_size > a.file_size ? b : a));
-      const token = resolveBotToken(self.channel);
-      const mediaDir = path.join(APX_HOME, "media");
-      fs.mkdirSync(mediaDir, { recursive: true });
-      try {
-        const localPath = await downloadTelegramFile(token, bestPhoto.file_id, mediaDir);
-        self.log(`telegram[${self.channel.name}] photo saved: ${localPath}`);
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "in",
-          type: "photo",
-          actor_id: msg.from?.id ? String(msg.from.id) : author,
-          external_id: String(u.update_id),
-          author,
-          body: text || "[photo]",
-          meta: {
-            chat_id,
-            user_id: msg.from?.id || null,
-            message_id: msg.message_id,
-            tg_channel: self.channel.name,
-            local_path: localPath,
-            file_id: bestPhoto.file_id,
-            width: bestPhoto.width,
-            height: bestPhoto.height,
-          },
-        });
-      } catch (e) {
-        self.log(`telegram[${self.channel.name}] photo download failed: ${e.message}`);
-      }
-      // If there's a caption, continue to handle it as text; otherwise return
-      if (!text) return;
+      ({ text } = await handleIncomingPhoto(self, { msg, u, author, chat_id, text }));
     }
-
-    // ── Incoming voice / audio handling ──────────────────────────────────
-    // Telegram sends `voice` for the press-and-hold mic recording (.oga/opus)
-    // and `audio` for uploaded audio files (mp3/m4a/etc.). Either way we
-    // download, run it through Whisper, prefix the result with `[audio] `
-    // and let the rest of the message flow handle it as plain text.
     const incomingAudio = msg.voice || msg.audio;
     if (incomingAudio && incomingAudio.file_id) {
-      const token = resolveBotToken(self.channel);
-      const mediaDir = path.join(APX_HOME, "media");
-      fs.mkdirSync(mediaDir, { recursive: true });
-      // Show "typing…" right away — download + transcription is the slow part of
-      // a voice message, and the reply-path typing (below) only starts after it,
-      // so without this the chat sits silent for seconds with no feedback.
-      const stopVoiceTyping = self._startTyping(chat_id);
-      let localPath = null;
-      let transcript = "";
-      let transcribeError = null;
-      let transcribeBackend = null;
-      try {
-        localPath = await downloadTelegramFile(token, incomingAudio.file_id, mediaDir);
-        self.log(`telegram[${self.channel.name}] audio saved: ${localPath}`);
-      } catch (e) {
-        self.log(`telegram[${self.channel.name}] audio download failed: ${e.message}`);
-      }
-      if (localPath) {
-        try {
-          const result = await transcribeAudioFile(localPath);
-          transcript = result.text || "";
-          transcribeBackend = result.backend;
-          self.log(`telegram[${self.channel.name}] audio transcribed via ${transcribeBackend} (${transcript.length} chars, lang=${result.language || "?"})`);
-        } catch (e) {
-          transcribeError = e.message;
-          self.log(`telegram[${self.channel.name}] audio transcription failed: ${e.message}`);
-        }
-      }
-      stopVoiceTyping(); // reply-path typing takes over from here
-      const audioBody = transcript
-        ? `[audio] ${transcript}`
-        : `[audio] (transcription unavailable${transcribeError ? ": " + transcribeError : ""})`;
-
-      appendGlobalMessage({
-        channel: CHANNELS.TELEGRAM,
-        direction: "in",
-        type: "audio",
-        actor_id: msg.from?.id ? String(msg.from.id) : author,
-        external_id: String(u.update_id),
-        author,
-        body: audioBody,
-        meta: {
-          chat_id,
-          user_id: msg.from?.id || null,
-          message_id: msg.message_id,
-          tg_channel: self.channel.name,
-          local_path: localPath,
-          file_id: incomingAudio.file_id,
-          duration: incomingAudio.duration,
-          mime_type: incomingAudio.mime_type,
-          transcription_backend: transcribeBackend,
-          transcription_error: transcribeError,
-        },
-      });
-
-      // Inject the transcribed text into `text` so the rest of the agent
-      // pipeline treats it identically to a typed message. If there was a
-      // caption alongside the audio, prepend the audio marker to it.
-      text = text ? `${audioBody}\n${text}` : audioBody;
+      ({ text } = await handleIncomingAudio(self, { msg, u, author, chat_id, text, incomingAudio }));
     }
 
     // If there's a pending ask_questions flow for this chat AND the current
@@ -309,10 +213,14 @@ export async function handleUpdate(self, u) {
     // Start "typing..." indicator. Stops when we send the reply (or fail).
     const stopTyping = self._startTyping(chat_id);
 
+    // Preset to the super-agent defaults so every exit path (including one where
+    // neither the routed-agent nor the super-agent branch runs) has a valid
+    // actor — the routed-agent / super-agent branches override these on success,
+    // and their catch blocks reset all four together (no partial-overwrite gap).
     let replyText;
     let replyAuthor;
-    let replyActorId;   // stable id: super_agent | agent slug
-    let replyKind;      // actor_kind: superagent | agent
+    let replyActorId = SUPERAGENT_ACTOR_ID;   // stable id: super_agent | agent slug
+    let replyKind = "superagent";             // actor_kind: superagent | agent
     const projectCfg = target.config || self.globalConfig;
     // Display name for the super-agent persona on this channel (from identity.json).
     const agentDisplay = resolveAgentName(self.globalConfig);
@@ -342,7 +250,10 @@ export async function handleUpdate(self, u) {
           replyKind = "agent";
         } catch (e) {
           self.log(`telegram[${self.channel.name}] agent reply failed: ${e.message}`);
-          replyText = `[apx error] ${e.message.slice(0, 200)}`;
+          replyText = t("telegram.error_agent", {
+            lang: resolveLang(self.globalConfig),
+            vars: { error: e.message.slice(0, 200) },
+          });
           replyAuthor = agentDisplay;
           replyActorId = SUPERAGENT_ACTOR_ID;
           replyKind = "superagent";
@@ -354,140 +265,33 @@ export async function handleUpdate(self, u) {
       }
     }
 
-    // Fallback: super-agent — STREAMED.
-    // Each iteration's assistant text is sent to Telegram as its own message
-    // the moment the model produces it (its running commentary), so the user
-    // sees a real back-and-forth instead of one giant final dump. Tool calls
-    // are logged to the message store — visible via apx log / apx search and
-    // to channels that render tools — but NEVER sent to Telegram; tools are
-    // internal. The conversation saved on disk is the full, real exchange;
-    // Telegram is just the prose-only view of it.
+    // Fallback: super-agent — STREAMED. Each iteration's assistant text is sent
+    // to Telegram as its own message the moment the model produces it; tool
+    // calls are logged but never sent (internal). The streamed turn + its final
+    // send live in ./reply.js so this dispatcher and the ask-flow resume
+    // (_runResumedTurn in the host poller) share ONE reply path — no drift.
     let saUsage = null;
     let streamedCount = 0;
     let lastStreamedText = "";
-    // Telegram shows the user ONLY prose — never the tool calls. On an action
-    // request the model often jumps straight to a tool with no preamble text,
-    // so the user would stare at a silent chat until the final reply. Send one
-    // short localized heads-up the moment real work starts (first tool_start),
-    // but only if the agent didn't already write its own "on it" line.
-    let sentHeadsUp = false;
-    const headsUpPhrase = () => t("telegram.heads_up", { lang: resolveLang(self.globalConfig) });
     if (!replyText && isSuperAgentEnabled(self.globalConfig)) {
-      const onEvent = async (ev) => {
-        try {
-          if (ev.type === "tool_start" && !sentHeadsUp && streamedCount === 0) {
-            sentHeadsUp = true;
-            const heads = headsUpPhrase();
-            await self._send({ chat_id, text: heads });
-            appendGlobalMessage({
-              channel: CHANNELS.TELEGRAM,
-              direction: "out",
-              type: "agent",
-              actor_id: SUPERAGENT_ACTOR_ID,
-              actor_kind: "superagent",
-              agent_slug: SUPERAGENT_ACTOR_ID,
-              author: agentDisplay,
-              body: heads,
-              meta: { chat_id, tg_channel: self.channel.name, in_reply_to: u.update_id, heads_up: true },
-            });
-            return;
-          }
-          if (ev.type === "assistant_text" && ev.text) {
-            const piece = stripThinking(ev.text).trim();
-            if (!piece) return;
-            await self._send({ chat_id, text: piece });
-            lastStreamedText = piece;
-            streamedCount += 1;
-            appendGlobalMessage({
-              channel: CHANNELS.TELEGRAM,
-              direction: "out",
-              type: "agent",
-              actor_id: SUPERAGENT_ACTOR_ID,
-              actor_kind: "superagent",
-              agent_slug: SUPERAGENT_ACTOR_ID,
-              author: agentDisplay,
-              body: piece,
-              meta: {
-                chat_id,
-                tg_channel: self.channel.name,
-                in_reply_to: u.update_id,
-                streamed: true,
-                iteration: ev.iteration,
-              },
-            });
-          } else if (ev.type === "tool_result" && ev.trace) {
-            // Logged for the audit trail / other channels — NOT sent to Telegram.
-            const t = ev.trace;
-            appendGlobalMessage({
-              channel: CHANNELS.TELEGRAM,
-              direction: "out",
-              type: "tool",
-              actor_id: t.tool,
-              actor_kind: "tool",
-              author: agentDisplay,
-              body: `${t.tool}(${JSON.stringify(t.args || {}).slice(0, 200)})`,
-              meta: {
-                chat_id,
-                tg_channel: self.channel.name,
-                in_reply_to: u.update_id,
-                tool: t.tool,
-                args: t.args,
-                result: t.result,
-                iteration: ev.iteration,
-              },
-            });
-          } else if (ev.type === "engine_failed") {
-            // A model in the fallback chain errored; the loop is rotating to
-            // the next one. Log it so a mid-turn provider failure (rate limit,
-            // tool-grammar 400, …) is diagnosable instead of invisible.
-            self.log(
-              `telegram[${self.channel.name}] engine_failed: ${ev.model || "?"} (${ev.reason || "?"}) → ${ev.retry_with || "end of chain"}`,
-            );
-          } else if (ev.type === "model_routed" || ev.type === "model_retry") {
-            self.log(
-              `telegram[${self.channel.name}] ${ev.type}: model=${ev.model || "?"}${ev.reason ? ` reason=${ev.reason}` : ""}${ev.from_fallback ? " (fallback)" : ""}`,
-            );
-          }
-        } catch (e) {
-          // A failed intermediate send must not abort the whole run.
-          self.log(`telegram[${self.channel.name}] stream event failed: ${e.message}`);
-        }
-      };
-
-      const confirmAdapter = createTelegramConfirmAdapter({
-        token: resolveBotToken(self.channel),
-        chatId: chat_id,
-        pendingStore: getConfirmStore(),
-      });
+      const { onEvent, state } = buildStreamHandler(self, { chat_id, update_id: u.update_id, agentDisplay });
 
-      // `/slug ...` shortcut: load the matching skill body into contextNote
-      // and strip the prefix from the user prompt before sending to the loop.
+      // `/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: self.globalConfig,
-          projects: self.projects,
-          plugins: self.plugins,
-          registries: self.registries,
-          prompt: slashedPrompt,
+        const sa = await runTelegramSuperAgent(self, {
+          chat_id,
+          prompt: slashed.handled ? slashed.prompt : text,
           previousMessages,
-          channel: CHANNELS.TELEGRAM,
+          target,
+          author,
           relationshipBlock,
           allowedTools,
-          contextNote: slashedContextNote || undefined,
-          channelMeta: buildTelegramMeta({
-            channelName: self.channel.name,
-            author,
-            chatId: chat_id,
-            target,
-            routeToAgent: self.channel.route_to_agent,
-          }),
+          contextNote: slashed.handled ? slashed.contextNote : "",
           signal: abortCtrl.signal,
           onEvent,
-          requestConfirmation: confirmAdapter.requestConfirmation,
         });
         replyText = sa.text;
         replyAuthor = sa.name || agentDisplay;
@@ -496,13 +300,13 @@ export async function handleUpdate(self, u) {
         saUsage = sa.usage;
 
         // ── ask_questions integration ────────────────────────────────────
-        // If the super-agent ended this turn by calling ask_questions, hand
-        // off to the inline-keyboard flow instead of sending the bare
-        // assistant text. The flow keeps state per chat_id and re-runs the
-        // super-agent once every answer is collected.
+        // If the super-agent ended this turn by calling ask_questions, hand off
+        // to the inline-keyboard flow instead of sending the bare assistant
+        // text. The flow keeps state per chat_id and re-runs the super-agent
+        // (via _runResumedTurn) once every answer is collected.
         const askQuestions = askFlow.extractAskQuestionsFromTrace(sa.trace);
         if (askQuestions && chat_id) {
-          if (chat_id) self.activeRequests.delete(chat_id);
+          self.activeRequests.delete(chat_id);
           stopTyping();
           try {
             await self._startAskFlow({
@@ -523,21 +327,20 @@ export async function handleUpdate(self, u) {
           }
           return; // The reply for this turn IS the ask flow.
         }
+        streamedCount = state.streamedCount;
+        lastStreamedText = state.lastStreamedText;
       } catch (e) {
         if (abortCtrl.signal.aborted) {
           // A newer message superseded this one. Whatever streamed so far is
-          // already sent + logged; the newer message's run continues the
-          // thread from that history.
+          // already sent + logged; the newer message's run continues the thread.
           self.log(`telegram[${self.channel.name}] request aborted for chat ${chat_id}`);
           if (chat_id) self.activeRequests.delete(chat_id);
           stopTyping();
           return;
         }
         self.log(`telegram[${self.channel.name}] super-agent failed: ${e.message}`);
-        // Surface the failure to the user instead of silently dropping the
-        // turn — otherwise from the chat side it looks like the bot ignored
-        // the message. Keep the message short and non-leaking.
-        replyText = `⚠️ Could not generate a reply right now (${e.message || "internal error"}).`;
+        // Surface the failure to the user instead of silently dropping the turn.
+        replyText = telegramErrorText(self, e);
         replyAuthor = agentDisplay;
         replyActorId = SUPERAGENT_ACTOR_ID;
         replyKind = "superagent";
@@ -545,71 +348,18 @@ export async function handleUpdate(self, u) {
     }
 
     if (chat_id) self.activeRequests.delete(chat_id);
-
-    // Final answer. The intermediate prose was already streamed; only send the
-    // final text if it's non-empty AND not a duplicate of the last streamed
-    // piece (the loop can end on an iteration whose text was already sent).
-    // If nothing streamed and there's no final text, send a minimal ack so the
-    // turn isn't silently empty.
-    const finalClean = replyText ? stripThinking(replyText).trim() : "";
-    let toSend = "";
-    if (finalClean && finalClean !== lastStreamedText) {
-      toSend = finalClean;
-    } else if (!finalClean) {
-      // Never end a turn on silence. The loop's tool-free wrap-up normally
-      // fills finalClean with a model-authored closing (handled above); this is
-      // the last-resort floor for the rare case it still came back empty. A
-      // pure chit-chat turn that did nothing gets the short ack; a turn that
-      // streamed/acted but produced no closing gets a neutral "continue?" that
-      // does NOT claim completion.
-      toSend = streamedCount === 0
-        ? t("telegram.fallback_listo", { lang: resolveLang(self.globalConfig) })
-        : t("telegram.fallback_continue", { lang: resolveLang(self.globalConfig) });
-    }
-
     stopTyping();
-    if (!toSend) return; // everything was already streamed — nothing left to send
-
-    try {
-      await self._send({ chat_id, text: toSend });
-      const meta = {
-        chat_id,
-        tg_channel: self.channel.name,
-        in_reply_to: u.update_id,
-        final: true,
-      };
-      if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
-      if (saUsage) meta.usage = saUsage;
-      appendGlobalMessage({
-        channel: CHANNELS.TELEGRAM,
-        direction: "out",
-        type: "agent",
-        actor_id: replyActorId || SUPERAGENT_ACTOR_ID,
-        actor_kind: replyKind || "superagent",
-        agent_slug: replyActorId || SUPERAGENT_ACTOR_ID,
-        author: replyAuthor || agentDisplay,
-        body: toSend,
-        meta,
-      });
-    } catch (e) {
-      self.log(`telegram[${self.channel.name}] send-back error: ${e.message}`);
-      appendGlobalMessage({
-        channel: CHANNELS.TELEGRAM,
-        direction: "out",
-        type: "agent",
-        actor_id: replyActorId || SUPERAGENT_ACTOR_ID,
-        actor_kind: replyKind || "superagent",
-        agent_slug: replyActorId || SUPERAGENT_ACTOR_ID,
-        author: replyAuthor || agentDisplay,
-        body: `[send_failed] ${toSend}`,
-        meta: {
-          chat_id,
-          tg_channel: self.channel.name,
-          in_reply_to: u.update_id,
-          send_error: e.message,
-          ...(saUsage ? { usage: saUsage } : {}),
-        },
-      });
-    }
+    await sendFinalReply(self, {
+      chat_id,
+      update_id: u.update_id,
+      replyText,
+      replyAuthor,
+      replyActorId,
+      replyKind,
+      saUsage,
+      streamedCount,
+      lastStreamedText,
+      agentDisplay,
+    });
   }
 

package/src/core/channels/telegram/helpers.js

@@ -2,10 +2,37 @@
 // big poller class stays focused on lifecycle + message dispatch. Each
 // function is pure (no `this`) — instances import them and call as needed.
 import fs from "node:fs";
-import { TELEGRAM_STATE_PATH } from "#core/config/index.js";
+import path from "node:path";
+import { TELEGRAM_STATE_PATH, APX_HOME } from "#core/config/index.js";
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
+/**
+ * Display label for a Telegram sender used as the `author` / actor fallback:
+ *   @username  →  "First Last"  →  "unknown".
+ * Single source of truth so every inbound branch (text/photo/audio) and the
+ * message store agree. NOTE: this is the raw handle; the *resolved contact
+ * name* (which prefers a saved roster name) is `resolveSender().name` in
+ * core/identity/telegram.js — different purpose, don't conflate them.
+ */
+export function telegramAuthorLabel(from) {
+  if (from?.username) return "@" + from.username;
+  const full = `${from?.first_name || ""} ${from?.last_name || ""}`.trim();
+  return full || "unknown";
+}
+
+/**
+ * Ensure and return the shared media-download directory (~/.apx/media).
+ * Owns BOTH the path and the mkdir so callers never touch `fs`/`APX_HOME`
+ * directly — the inbound dispatcher used to inline this and a module split
+ * dropped its `fs`/`APX_HOME` imports, silently breaking every photo/voice.
+ */
+export function telegramMediaDir() {
+  const dir = path.join(APX_HOME, "media");
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 /**
  * Build the channelMeta block the super-agent loop receives for a Telegram
  * turn. The prompt template at src/core/agent/prompts/channels/telegram.md

package/src/core/channels/telegram/inbound/audio.js

@@ -0,0 +1,82 @@
+// Inbound Telegram VOICE/AUDIO handling, split out of dispatch.js. Telegram
+// sends `voice` for the press-and-hold mic recording (.oga/opus) and `audio`
+// for uploaded audio files (mp3/m4a/etc.). Either way we download, run it
+// through Whisper, prefix the result with `[audio] ` and let the rest of the
+// message flow handle it as plain text.
+//
+// Takes the poller instance (`self`, for logging, channel + the typing
+// indicator) plus the parsed update context, and returns the `text` the rest of
+// the pipeline should run — the transcript merged into any existing caption.
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { transcribe as transcribeAudioFile } from "#core/voice/transcription.js";
+import { resolveBotToken, telegramMediaDir } from "../helpers.js";
+import { downloadTelegramFile } from "../media.js";
+
+/**
+ * @param {object} self  poller instance (uses self.log, self.channel, self._startTyping)
+ * @param {object} ctx   { msg, u, author, chat_id, text, incomingAudio }
+ * @returns {Promise<{ text: string }>}  text to continue the pipeline with
+ */
+export async function handleIncomingAudio(self, { msg, u, author, chat_id, text, incomingAudio }) {
+  const token = resolveBotToken(self.channel);
+  const mediaDir = telegramMediaDir();
+
+  // Show "typing…" right away — download + transcription is the slow part of a
+  // voice message, and the reply-path typing only starts after it, so without
+  // this the chat sits silent for seconds with no feedback.
+  const stopVoiceTyping = self._startTyping(chat_id);
+  let localPath = null;
+  let transcript = "";
+  let transcribeError = null;
+  let transcribeBackend = null;
+  try {
+    localPath = await downloadTelegramFile(token, incomingAudio.file_id, mediaDir);
+    self.log(`telegram[${self.channel.name}] audio saved: ${localPath}`);
+  } catch (e) {
+    self.log(`telegram[${self.channel.name}] audio download failed: ${e.message}`);
+  }
+  if (localPath) {
+    try {
+      const result = await transcribeAudioFile(localPath);
+      transcript = result.text || "";
+      transcribeBackend = result.backend;
+      self.log(`telegram[${self.channel.name}] audio transcribed via ${transcribeBackend} (${transcript.length} chars, lang=${result.language || "?"})`);
+    } catch (e) {
+      transcribeError = e.message;
+      self.log(`telegram[${self.channel.name}] audio transcription failed: ${e.message}`);
+    }
+  }
+  stopVoiceTyping(); // reply-path typing takes over from here
+
+  const audioBody = transcript
+    ? `[audio] ${transcript}`
+    : `[audio] (transcription unavailable${transcribeError ? ": " + transcribeError : ""})`;
+
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "in",
+    type: "audio",
+    actor_id: msg.from?.id ? String(msg.from.id) : author,
+    external_id: String(u.update_id),
+    author,
+    body: audioBody,
+    meta: {
+      chat_id,
+      user_id: msg.from?.id || null,
+      message_id: msg.message_id,
+      tg_channel: self.channel.name,
+      local_path: localPath,
+      file_id: incomingAudio.file_id,
+      duration: incomingAudio.duration,
+      mime_type: incomingAudio.mime_type,
+      transcription_backend: transcribeBackend,
+      transcription_error: transcribeError,
+    },
+  });
+
+  // Inject the transcribed text into `text` so the rest of the agent pipeline
+  // treats it identically to a typed message. If there was a caption alongside
+  // the audio, prepend the audio marker to it.
+  return { text: text ? `${audioBody}\n${text}` : audioBody };
+}

package/src/core/channels/telegram/inbound/photo.js

@@ -0,0 +1,63 @@
+// Inbound Telegram PHOTO handling, split out of dispatch.js so the dispatcher
+// stays focused on routing. Pure of the poller's lifecycle: it takes the poller
+// instance (`self`, for logging + channel) plus the parsed update context, and
+// returns the (possibly rewritten) `text` the rest of the pipeline should run.
+//
+// Vision note: we do NOT have image understanding yet — the engine layer can't
+// pass image content to the model. So we download + archive the photo and then
+// inject an internal `[image]` marker into `text` so the agent ALWAYS produces a
+// reply in its own words (never goes silent on a no-caption photo). The reply is
+// model-authored; the marker only tells the model an image arrived and that it
+// can't see the pixels yet. Mirrors the `[audio]` marker convention.
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { resolveBotToken, telegramMediaDir } from "../helpers.js";
+import { downloadTelegramFile } from "../media.js";
+
+/**
+ * @param {object} self  poller instance (uses self.log, self.channel)
+ * @param {object} ctx   { msg, u, author, chat_id, text }
+ * @returns {Promise<{ text: string }>}  text to continue the pipeline with
+ */
+export async function handleIncomingPhoto(self, { msg, u, author, chat_id, text }) {
+  // Telegram sends multiple sizes; pick the largest.
+  const bestPhoto = msg.photo.reduce((a, b) => (b.file_size > a.file_size ? b : a));
+  const token = resolveBotToken(self.channel);
+  const mediaDir = telegramMediaDir();
+
+  let localPath = null;
+  try {
+    localPath = await downloadTelegramFile(token, bestPhoto.file_id, mediaDir);
+    self.log(`telegram[${self.channel.name}] photo saved: ${localPath}`);
+  } catch (e) {
+    self.log(`telegram[${self.channel.name}] photo download failed: ${e.message}`);
+  }
+
+  // Archive the inbound photo regardless of download outcome, so chat history
+  // records it even if the file fetch failed.
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "in",
+    type: "photo",
+    actor_id: msg.from?.id ? String(msg.from.id) : author,
+    external_id: String(u.update_id),
+    author,
+    body: text || "[photo]",
+    meta: {
+      chat_id,
+      user_id: msg.from?.id || null,
+      message_id: msg.message_id,
+      tg_channel: self.channel.name,
+      local_path: localPath,
+      file_id: bestPhoto.file_id,
+      width: bestPhoto.width,
+      height: bestPhoto.height,
+    },
+  });
+
+  // Guard: never go silent. Hand the agent an internal marker so it replies in
+  // its own words. No vision yet → say so, in-band, so the model doesn't
+  // hallucinate "seeing" the image.
+  const marker = "[image attached — you cannot see its contents yet]";
+  return { text: text ? `${marker} ${text}` : marker };
+}