@agentprojectcontext/apx 1.41.0 → 1.42.1

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 };
+}

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

@@ -0,0 +1,204 @@
+// Shared Telegram super-agent reply path. Both the inbound dispatcher
+// (handleUpdate) and the ask-flow resume (_runResumedTurn in the host poller)
+// drive the SAME streamed turn through these helpers, so behavior — autonomy
+// budget, streaming, never-silent floor, localized errors, rich channelMeta —
+// can't drift between the two entry points. It did drift: the resume path was a
+// stale hand-rolled copy that missed maxIters, streaming and i18n. One source
+// of truth fixes that for good.
+import { runSuperAgent } from "#core/agent/super-agent.js";
+import { TELEGRAM_TOOL_ITERS } from "#core/agent/constants.js";
+import { stripThinking } from "#core/util/thinking.js";
+import { appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
+import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
+import { t, resolveLang } from "#core/i18n/index.js";
+import { buildTelegramMeta, resolveBotToken } from "./helpers.js";
+
+/**
+ * Build the streaming event handler for a Telegram super-agent turn. Sends a
+ * one-shot localized heads-up the moment real work starts (first tool), streams
+ * each assistant-text iteration as its own chat message, and logs tool calls
+ * (audit trail / other channels — never sent to Telegram). Returns the handler
+ * plus a live `state` the caller reads AFTER the run to drive the final send.
+ *
+ * @returns {{ onEvent: Function, state: { streamedCount: number, lastStreamedText: string } }}
+ */
+export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
+  const state = { streamedCount: 0, lastStreamedText: "", sentHeadsUp: false };
+  const onEvent = async (ev) => {
+    try {
+      if (ev.type === "tool_start" && !state.sentHeadsUp && state.streamedCount === 0) {
+        state.sentHeadsUp = true;
+        const heads = t("telegram.heads_up", { lang: resolveLang(self.globalConfig) });
+        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: 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 });
+        state.lastStreamedText = piece;
+        state.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: 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 tr = ev.trace;
+        appendGlobalMessage({
+          channel: CHANNELS.TELEGRAM,
+          direction: "out",
+          type: "tool",
+          actor_id: tr.tool,
+          actor_kind: "tool",
+          author: agentDisplay,
+          body: `${tr.tool}(${JSON.stringify(tr.args || {}).slice(0, 200)})`,
+          meta: { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, tool: tr.tool, args: tr.args, result: tr.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 so a mid-turn provider failure is diagnosable.
+        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}`);
+    }
+  };
+  return { onEvent, state };
+}
+
+/**
+ * Run the super-agent for a Telegram turn with the canonical channel config:
+ * the autonomy budget (telegram_max_iters → TELEGRAM_TOOL_ITERS), rich
+ * channelMeta (project pin + route), the confirmation adapter, and streaming.
+ * The single place this call is configured — change it once, both entry points
+ * inherit it. Throws on failure (caller decides abort-vs-error handling).
+ */
+export function runTelegramSuperAgent(self, {
+  chat_id, prompt, previousMessages, target, author, relationshipBlock,
+  allowedTools, contextNote, signal, onEvent,
+}) {
+  const confirmAdapter = createTelegramConfirmAdapter({
+    token: resolveBotToken(self.channel),
+    chatId: chat_id,
+    pendingStore: getConfirmStore(),
+  });
+  return runSuperAgent({
+    globalConfig: self.globalConfig,
+    projects: self.projects,
+    plugins: self.plugins,
+    registries: self.registries,
+    prompt,
+    previousMessages,
+    channel: CHANNELS.TELEGRAM,
+    relationshipBlock,
+    allowedTools,
+    contextNote: contextNote || undefined,
+    channelMeta: buildTelegramMeta({
+      channelName: self.channel.name,
+      author,
+      chatId: chat_id,
+      target,
+      routeToAgent: self.channel.route_to_agent,
+    }),
+    signal,
+    onEvent,
+    requestConfirmation: confirmAdapter.requestConfirmation,
+    // Autonomy budget: Telegram is the "do the whole task for me" surface, so it
+    // gets a real multi-step budget instead of the conversational default (which
+    // cut tasks off after ~9 actions to ask "continue?"). Tunable via
+    // config.super_agent.telegram_max_iters.
+    maxIters: Number(self.globalConfig?.super_agent?.telegram_max_iters) || TELEGRAM_TOOL_ITERS,
+  });
+}
+
+/** Localized "couldn't reply" text for a failed super-agent turn (model itself
+ * failed, so it can't author this — templated, but follows the user's language). */
+export function telegramErrorText(self, e) {
+  return t("telegram.error_generic", {
+    lang: resolveLang(self.globalConfig),
+    vars: { error: e?.message || "internal error" },
+  });
+}
+
+/**
+ * Send the final reply for a turn and log it. The intermediate prose was already
+ * streamed, so we only send `replyText` if it's non-empty AND not a duplicate of
+ * the last streamed piece. Never ends on silence: a turn that streamed/acted but
+ * produced no closing gets a neutral "continue?"; a pure chit-chat turn that did
+ * nothing gets a short ack. Caller stops the typing indicator before calling.
+ */
+export async function sendFinalReply(self, {
+  chat_id, update_id, replyText, replyAuthor, replyActorId, replyKind,
+  saUsage = null, streamedCount = 0, lastStreamedText = "", agentDisplay,
+  extraMeta = {},
+}) {
+  const finalClean = replyText ? stripThinking(replyText).trim() : "";
+  let toSend = "";
+  if (finalClean && finalClean !== lastStreamedText) {
+    toSend = finalClean;
+  } else if (!finalClean) {
+    const lang = resolveLang(self.globalConfig);
+    toSend = streamedCount === 0
+      ? t("telegram.fallback_listo", { lang })
+      : t("telegram.fallback_continue", { lang });
+  }
+  if (!toSend) return; // everything was already streamed — nothing left to send
+
+  const actorId = replyActorId || SUPERAGENT_ACTOR_ID;
+  const kind = replyKind || "superagent";
+  try {
+    await self._send({ chat_id, text: toSend });
+    const meta = { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, final: true, ...extraMeta };
+    if (replyText && stripThinking(replyText) !== replyText) meta.thinking_stripped = true;
+    if (saUsage) meta.usage = saUsage;
+    appendGlobalMessage({
+      channel: CHANNELS.TELEGRAM,
+      direction: "out",
+      type: "agent",
+      actor_id: actorId,
+      actor_kind: kind,
+      agent_slug: actorId,
+      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: actorId,
+      actor_kind: kind,
+      agent_slug: actorId,
+      author: replyAuthor || agentDisplay,
+      body: `[send_failed] ${toSend}`,
+      meta: { chat_id, tg_channel: self.channel.name, in_reply_to: update_id, send_error: e.message, ...(saUsage ? { usage: saUsage } : {}) },
+    });
+  }
+}

package/src/core/config/index.js

@@ -57,6 +57,11 @@ const DEFAULT_CONFIG = {
     system: "",                         // optional override; defaults in src/core/agent/prompts/
     permission_mode: PERMISSION_MODES.AUTOMATICO,       // total | automatico | permiso
     allowed_tools: [],                   // used by permission_mode="permiso"
+    // Per-turn tool-loop budget for the Telegram super-agent. Higher = more
+    // autonomous (chains explore→edit→verify→close before replying); lower =
+    // snappier but more "want me to continue?" hand-backs. 0/unset → built-in
+    // default (TELEGRAM_TOOL_ITERS in src/core/agent/constants.js).
+    telegram_max_iters: 0,
     // Model fallback: ordered list. Each item carries its own provider
     // prefix; the array order IS the attempt order. The router tries the
     // primary (super_agent.model) first, then walks this list, skipping

package/src/core/i18n/en.js

@@ -4,4 +4,8 @@ export default {
   "telegram.reset_ack": "Done, context cleared. Starting fresh. What do you need?",
   "telegram.fallback_listo": "Done.",
   "telegram.fallback_continue": "Made some headway. Want me to keep going?",
+  // Host-emitted error floors (the model itself failed, so it can't author
+  // these — they stay templated, but at least follow the user's language).
+  "telegram.error_agent": "⚠️ The agent hit an error ({error}).",
+  "telegram.error_generic": "⚠️ Couldn't reply right now ({error}).",
 };

package/src/core/i18n/es.js

@@ -6,4 +6,8 @@ export default {
   "telegram.reset_ack": "Listo, contexto borrado. Arranco un hilo nuevo, ¿qué necesitás?",
   "telegram.fallback_listo": "Listo.",
   "telegram.fallback_continue": "Avancé con eso. ¿Querés que siga?",
+  // Pisos de error emitidos por el host (el modelo falló, no puede redactarlos
+  // él mismo — quedan fijos, pero al menos respetan el idioma del usuario).
+  "telegram.error_agent": "⚠️ El agente tuvo un error ({error}).",
+  "telegram.error_generic": "⚠️ No pude responder ahora mismo ({error}).",
 };

package/src/core/i18n/pt.js

@@ -4,4 +4,8 @@ export default {
   "telegram.reset_ack": "Pronto, contexto limpo. Começando do zero — do que você precisa?",
   "telegram.fallback_listo": "Pronto.",
   "telegram.fallback_continue": "Avancei com isso. Quer que eu continue?",
+  // Pisos de erro emitidos pelo host (o modelo falhou, não pode redigi-los —
+  // ficam fixos, mas ao menos seguem o idioma do usuário).
+  "telegram.error_agent": "⚠️ O agente encontrou um erro ({error}).",
+  "telegram.error_generic": "⚠️ Não consegui responder agora ({error}).",
 };

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

@@ -27,23 +27,15 @@
 //     "poll_interval_ms": 1500
 //   }
 
-import fs from "node:fs";
-import path from "node:path";
-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 "#core/util/thinking.js";
+// This poller is intentionally thin: per-update logic lives in core/channels/
+// telegram/ (dispatch + reply + ask + inbound). It keeps only what the *running
+// process* needs — lifecycle, the poll loop, offset state and the inline-keyboard
+// callbacks. The earlier dispatch extraction left a pile of now-dead imports
+// here; only what's actually referenced below remains.
 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 "#core/channels/telegram/ask.js";
 
@@ -53,7 +45,6 @@ const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 // All non-class-bound channel logic lives in core/channels/telegram/ — this
 // file stays focused on the poller class + plugin lifecycle wiring.
 import {
-  buildTelegramMeta,
   loadState,
   saveState,
   resolveBotToken,
@@ -63,9 +54,10 @@ import {
   sleep,
 } from "#core/channels/telegram/helpers.js";
 import { handleUpdate } from "#core/channels/telegram/dispatch.js";
+import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply } from "#core/channels/telegram/reply.js";
 
 // ---------- media sending helpers (re-exports) ------------------------------
-import { sendPhoto, sendVoice, sendDocument, sendAudio, downloadTelegramFile, API_BASE } from "#core/channels/telegram/media.js";
+import { sendPhoto, sendVoice, sendDocument, sendAudio, API_BASE } from "#core/channels/telegram/media.js";
 export { sendPhoto, sendVoice, sendDocument, sendAudio };
 
 // ---------- per-channel poller ----------------------------------------------
@@ -328,9 +320,9 @@ class ChannelPoller {
   }
 
   // Run a follow-up super-agent turn with the compiled answers as the user
-  // prompt. Mirrors the post-runSuperAgent reply path in _handleUpdate but
-  // skipped of the photo/audio/reset preamble. Re-enters the ask flow if the
-  // model decides to ask again.
+  // prompt. Shares the exact reply path as a normal inbound turn (core/channels/
+  // telegram/reply.js) — only the photo/audio/reset preamble is skipped.
+  // Re-enters the ask flow if the model decides to ask again.
   async _runResumedTurn(ctx) {
     const { chat_id, compiled, target, relationshipBlock, allowedTools, author, agentDisplay, update_id, sender, authorId } = ctx;
     if (!chat_id) return;
@@ -359,25 +351,32 @@ class ChannelPoller {
       max_age_hours: 24,
     });
 
+    // Drive the resume through the SAME shared reply path as a normal inbound
+    // turn (see core/channels/telegram/reply.js): streaming, the autonomy budget
+    // (maxIters), the never-silent floor, localized errors and rich channelMeta.
+    // This used to be a hand-rolled copy that silently lagged behind the main
+    // path — now there's one source of truth.
+    const { onEvent, state } = buildStreamHandler(this, { chat_id, update_id, agentDisplay });
     const stopTyping = this._startTyping(chat_id);
+    let replyText;
+    let replyAuthor;
+    let saUsage = null;
     try {
-      const sa = await runSuperAgent({
-        globalConfig: this.globalConfig,
-        projects: this.projects,
-        plugins: this.plugins,
-        registries: this.registries,
+      const sa = await runTelegramSuperAgent(this, {
+        chat_id,
         prompt: compiled,
         previousMessages,
-        channel: CHANNELS.TELEGRAM,
+        target,
+        author,
         relationshipBlock,
         allowedTools,
-        channelMeta: { channel: CHANNELS.TELEGRAM, chat_id, author, route_to_agent: this.channel.route_to_agent },
+        onEvent,
       });
-      stopTyping();
 
       // Did the model ask again? Restart the flow instead of replying.
       const followupAsk = askFlow.extractAskQuestionsFromTrace(sa.trace);
       if (followupAsk) {
+        stopTyping();
         await this._startAskFlow({
           chat_id,
           projectId: target?.id,
@@ -393,36 +392,29 @@ class ChannelPoller {
         });
         return;
       }
-
-      const replyText = sa.text ? stripThinking(sa.text).trim() : "";
-      if (replyText) {
-        await this._send({ chat_id, text: replyText });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "agent",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          agent_slug: SUPERAGENT_ACTOR_ID,
-          author: sa.name || agentDisplay,
-          body: replyText,
-          meta: {
-            chat_id,
-            tg_channel: this.channel.name,
-            in_reply_to: update_id,
-            final: true,
-            ask_resume: true,
-            ...(sa.usage ? { usage: sa.usage } : {}),
-          },
-        });
-      }
+      replyText = sa.text;
+      replyAuthor = sa.name || agentDisplay;
+      saUsage = sa.usage;
     } catch (e) {
-      stopTyping();
       this.log(`telegram[${this.channel.name}] ask resume failed: ${e.message}`);
-      try {
-        await this._send({ chat_id, text: `⚠️ Error procesando tus respuestas (${e.message}).` });
-      } catch { /* best-effort */ }
+      replyText = telegramErrorText(this, e);
+      replyAuthor = agentDisplay;
     }
+
+    stopTyping();
+    await sendFinalReply(this, {
+      chat_id,
+      update_id,
+      replyText,
+      replyAuthor,
+      replyActorId: SUPERAGENT_ACTOR_ID,
+      replyKind: "superagent",
+      saUsage,
+      streamedCount: state.streamedCount,
+      lastStreamedText: state.lastStreamedText,
+      agentDisplay,
+      extraMeta: { ask_resume: true },
+    });
   }
 
   // Show "typing..." indicator in the chat. Telegram clears it automatically