@agentprojectcontext/apx 1.33.0 → 1.33.1

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

@@ -50,124 +50,23 @@ 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
-// src/core/agent/prompts/channels/telegram.md interpolates {{projectBlock}}
-// and {{routeBlock}} verbatim, so we pre-render them as plain text here
-// (the template engine doesn't do conditionals).
-function buildTelegramMeta({ channelName, author, chatId, target, routeToAgent }) {
-  const projectBlock = target
-    ? `\nProject pin: **${target.name || "(unnamed)"}** (\`${target.path || "?"}\`).\n` +
-      "This Telegram channel belongs to that project. Default any " +
-      "project-scoped tool call (list_agents, list_tasks, list_mcps, " +
-      "list_skills, create_task, list_routines, …) to " +
-      `\`${target.name || target.path}\` without asking the user "which ` +
-      'project?". Only ask when they explicitly reference another project ' +
-      "by name."
-    : "";
-  const routeBlock = routeToAgent
-    ? `\nMaster agent for this channel: **${routeToAgent}**. Prefer ` +
-      `delegating substantive work to that agent via call_agent({ project: ` +
-      `"${target?.name || target?.path || ""}", agent: "${routeToAgent}", ` +
-      "prompt: <user message> }) rather than answering yourself, unless " +
-      "the message is small-talk or a quick factual reply."
-    : "";
-  return {
-    channelName,
-    author,
-    chatId,
-    projectBlock,
-    routeBlock,
-    // Also expose raw fields for any future surface / log that wants them.
-    ...(target ? {
-      projectId:   String(target.id),
-      projectName: target.name || "",
-      projectPath: target.path || "",
-    } : {}),
-    ...(routeToAgent ? { routeToAgent } : {}),
-  };
-}
-
-// Media sending helpers moved to ./media.js.
+// All non-class-bound helpers live in ./helpers.js so the file stays
+// focused on the poller class + dispatch wiring.
+import {
+  buildTelegramMeta,
+  loadState,
+  saveState,
+  resolveBotToken,
+  resolveChatId,
+  tokenSource,
+  resolveChannels,
+  sleep,
+} from "./helpers.js";
+import { handleUpdate } from "./dispatch.js";
+
+// ---------- media sending helpers (re-exports) ------------------------------
 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 {
-    const raw = JSON.parse(fs.readFileSync(TELEGRAM_STATE_PATH, "utf8"));
-    return { channels: raw.channels || {}, _legacy_offset: raw.offset || 0 };
-  } catch {
-    return { channels: {} };
-  }
-}
-
-function saveState(state) {
-  fs.writeFileSync(
-    TELEGRAM_STATE_PATH,
-    JSON.stringify({ ...state, updated_at: nowIso() }, null, 2) + "\n"
-  );
-}
-
-// ---------- env-fallback helpers --------------------------------------------
-
-function resolveBotToken(channel) {
-  return (
-    channel.bot_token ||
-    process.env.BOT_TELEGRAM_TOKEN ||
-    process.env.TELEGRAM_BOT_TOKEN ||
-    ""
-  );
-}
-
-function resolveChatId(channel) {
-  return (
-    channel.chat_id ||
-    process.env.TELEGRAM_CHAT_ID ||
-    process.env.BOT_TELEGRAM_CHAT_ID ||
-    ""
-  );
-}
-
-function tokenSource(channel) {
-  if (channel.bot_token) return "config";
-  if (process.env.BOT_TELEGRAM_TOKEN) return "env:BOT_TELEGRAM_TOKEN";
-  if (process.env.TELEGRAM_BOT_TOKEN) return "env:TELEGRAM_BOT_TOKEN";
-  return null;
-}
-
-// ---------- channel-list resolution -----------------------------------------
-
-function resolveChannels(globalConfig) {
-  const tg = globalConfig.telegram || {};
-  if (Array.isArray(tg.channels) && tg.channels.length > 0) {
-    return tg.channels.map((c, i) => ({
-      name: c.name || `channel-${i + 1}`,
-      bot_token: c.bot_token || "",
-      chat_id: c.chat_id || "",
-      route_to_agent: c.route_to_agent || "",
-      project: c.project || null,
-      respond_with_engine:
-        c.respond_with_engine !== undefined
-          ? c.respond_with_engine
-          : tg.respond_with_engine !== false,
-      poll_interval_ms: c.poll_interval_ms || tg.poll_interval_ms || 1500,
-    }));
-  }
-  // Legacy single-channel mode
-  if (!tg.bot_token && !process.env.BOT_TELEGRAM_TOKEN && !process.env.TELEGRAM_BOT_TOKEN) {
-    return [];
-  }
-  return [
-    {
-      name: "default",
-      bot_token: tg.bot_token || "",
-      chat_id: tg.chat_id || "",
-      route_to_agent: tg.route_to_agent || "",
-      project: null,
-      respond_with_engine: tg.respond_with_engine !== false,
-      poll_interval_ms: tg.poll_interval_ms || 1500,
-    },
-  ];
-}
 
 // ---------- per-channel poller ----------------------------------------------
 
@@ -275,569 +174,11 @@ class ChannelPoller {
     return json.result || [];
   }
 
+  // Method body lives in ./dispatch.js as `handleUpdate(self, u)` so this file
+  // stays focused on poller lifecycle. The function reaches every internal
+  // poller field through the `self` it receives.
   async _handleUpdate(u) {
-    this.lastUpdateAt = nowIso();
-
-    // Inline keyboard button press: route to the confirmation adapter.
-    if (u.callback_query) {
-      await this._handleCallbackQuery(u.callback_query);
-      return;
-    }
-
-    const msg = u.message || u.edited_message;
-    if (!msg) return;
-    const target = this.resolveProject();
-    if (!target) {
-      this.log(`telegram[${this.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 chat_id = msg.chat?.id;
-
-    // Resolve WHO is writing (owner / known contact / guest), keyed by the
-    // stable Telegram user_id. Records unknown senders and, on a fresh private
-    // channel with no owner yet, claims this sender as the owner. Mutates the
-    // in-memory globalConfig in place so later messages in this daemon session
-    // see the update. The resulting block is injected into whichever agent
-    // answers (super-agent OR a routed project agent).
-    const { sender } = registerSender({
-      cfg: this.globalConfig,
-      channelName: this.channel.name,
-      from: msg.from,
-      chatType: msg.chat?.type,
-    });
-    const relationshipBlock = buildRelationshipBlock(sender);
-    // Role-based tool gating for the super-agent path (guests → no tools).
-    const allowedTools = resolveAllowedTools(this.globalConfig, sender);
-
-    // Default Interrupt: abort any running request for this chat_id
-    if (chat_id) {
-      const prev = this.activeRequests.get(chat_id);
-      if (prev) {
-        this.log(`telegram[${this.channel.name}] interrupting previous request for chat ${chat_id}`);
-        prev.abort();
-      }
-    }
-    const abortCtrl = new AbortController();
-    if (chat_id) this.activeRequests.set(chat_id, abortCtrl);
-
-    let text = msg.text || msg.caption || "";
-
-    // ── Incoming photo handling ───────────────────────────────────────────
-    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(this.channel);
-      const mediaDir = path.join(APX_HOME, "media");
-      fs.mkdirSync(mediaDir, { recursive: true });
-      try {
-        const localPath = await downloadTelegramFile(token, bestPhoto.file_id, mediaDir);
-        this.log(`telegram[${this.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: this.channel.name,
-            local_path: localPath,
-            file_id: bestPhoto.file_id,
-            width: bestPhoto.width,
-            height: bestPhoto.height,
-          },
-        });
-      } catch (e) {
-        this.log(`telegram[${this.channel.name}] photo download failed: ${e.message}`);
-      }
-      // If there's a caption, continue to handle it as text; otherwise return
-      if (!text) return;
-    }
-
-    // ── 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(this.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 = this._startTyping(chat_id);
-      let localPath = null;
-      let transcript = "";
-      let transcribeError = null;
-      let transcribeBackend = null;
-      try {
-        localPath = await downloadTelegramFile(token, incomingAudio.file_id, mediaDir);
-        this.log(`telegram[${this.channel.name}] audio saved: ${localPath}`);
-      } catch (e) {
-        this.log(`telegram[${this.channel.name}] audio download failed: ${e.message}`);
-      }
-      if (localPath) {
-        try {
-          const result = await transcribeAudioFile(localPath);
-          transcript = result.text || "";
-          transcribeBackend = result.backend;
-          this.log(`telegram[${this.channel.name}] audio transcribed via ${transcribeBackend} (${transcript.length} chars, lang=${result.language || "?"})`);
-        } catch (e) {
-          transcribeError = e.message;
-          this.log(`telegram[${this.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: this.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;
-    }
-
-    // If there's a pending ask_questions flow for this chat AND the current
-    // question is free-text, treat this message as the answer rather than a
-    // brand-new turn. Returns true when the message was consumed.
-    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: CHANNELS.TELEGRAM,
-        direction: "in",
-        type: "user",
-        actor_id: msg.from?.id ? String(msg.from.id) : author,
-        external_id: String(u.update_id),
-        author,
-        body: text,
-        meta: {
-          chat_id,
-          user_id: msg.from?.id || null,
-          message_id: msg.message_id,
-          tg_channel: this.channel.name,
-          ask_answer: true,
-        },
-      });
-      return;
-    }
-
-    // /reset or /new wipes the rolling context for this chat. We just
-    // remember a marker timestamp; subsequent inbounds will only consider
-    // history newer than this. Implemented by writing a synthetic message
-    // with a known marker so getRecentTelegramTurns naturally cuts off.
-    const isReset = /^\/(reset|new)\b/i.test(text.trim());
-
-    // Pull the prior conversation BEFORE we log this inbound — so the
-    // current message isn't part of its own history. We then prune anything
-    // older than the most recent /reset for this chat_id.
-    let previousMessages = [];
-    if (chat_id && !isReset) {
-      previousMessages = getRecentTelegramTurnsFromFs({
-        chat_id,
-        keepRecent: 40,
-        max_age_hours: 24,
-      });
-      // Progressive compaction (Pieza 3) runs OUT of the reply path: if this
-      // chat is over threshold, summarize the oldest turns in the background so
-      // the next turn reads a [RESUMEN COMPACTADO] instead of raw history. Never
-      // awaited — adds zero latency to this reply, degrades gracefully.
-      compactChannelIfNeeded({
-        channel: CHANNELS.TELEGRAM,
-        chat_id,
-        config: this.globalConfig,
-        log: this.log,
-      }).catch(() => {});
-      // Honour a /reset marker: drop everything up to and including it.
-      const lastResetIdx = (() => {
-        for (let i = previousMessages.length - 1; i >= 0; i--) {
-          if (
-            previousMessages[i].role === "user" &&
-            /^\/(reset|new)\b/i.test(previousMessages[i].content.trim())
-          ) {
-            return i;
-          }
-        }
-        return -1;
-      })();
-      if (lastResetIdx >= 0) {
-        previousMessages = previousMessages.slice(lastResetIdx + 1);
-      }
-    }
-
-    // Always log inbound to global store (~/.apx/messages/telegram/)
-    appendGlobalMessage({
-      channel: CHANNELS.TELEGRAM,
-      direction: "in",
-      type: "user",
-      actor_id: msg.from?.id ? String(msg.from.id) : author,
-      external_id: String(u.update_id),
-      author,
-      body: text,
-      meta: {
-        chat_id,
-        user_id: msg.from?.id || null,
-        message_id: msg.message_id,
-        tg_channel: this.channel.name,
-      },
-    });
-
-    // Super-agent is ALWAYS active on Telegram: respond_with_engine === false
-    // used to silently drop user messages, which looked to the user like the
-    // bot ignored them. Honour the legacy flag only as a soft hint (skip the
-    // routed-agent shortcut so we fall straight to super-agent) but never let
-    // it short-circuit the whole reply. To genuinely silence the bot, disable
-    // the channel entirely (telegram.enabled = false in config).
-    const skipRoutedAgent = this.channel.respond_with_engine === false;
-    if (!text) return;
-
-    // Short-circuit /reset / /new: send an ack and don't engage the engine.
-    // The marker we just logged is enough — getRecentTelegramTurns will
-    // honor it for future messages.
-    if (isReset) {
-      try {
-        const ack = "Done, context cleared. Starting fresh. What do you need?";
-        await this._send({ chat_id, text: ack });
-        appendGlobalMessage({
-          channel: CHANNELS.TELEGRAM,
-          direction: "out",
-          type: "agent",
-          actor_id: SUPERAGENT_ACTOR_ID,
-          actor_kind: "superagent",
-          agent_slug: SUPERAGENT_ACTOR_ID,
-          author: resolveAgentName(this.globalConfig),
-          body: ack,
-          meta: { chat_id, tg_channel: this.channel.name, in_reply_to: u.update_id, reset: true },
-        });
-      } catch (e) {
-        this.log(`telegram[${this.channel.name}] reset ack failed: ${e.message}`);
-      }
-      return;
-    }
-
-    // Start "typing..." indicator. Stops when we send the reply (or fail).
-    const stopTyping = this._startTyping(chat_id);
-
-    let replyText;
-    let replyAuthor;
-    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 (from identity.json).
-    const agentDisplay = resolveAgentName(this.globalConfig);
-
-    // Try the project's chosen agent first (skipped if the legacy
-    // respond_with_engine === false hint asked to bypass routed agents).
-    const routeSlug = skipRoutedAgent ? null : this.channel.route_to_agent;
-    if (routeSlug) {
-      const agent = readAgents(target.path).find((a) => a.slug === routeSlug);
-      if (agent && agent.fields.Model) {
-        try {
-          const system = buildAgentSystem(target, agent, {
-            invocation: "telegram",
-            channel: this.channel.name,
-            caller: author,
-            extraParts: [relationshipBlock],
-          });
-          const result = await callEngine({
-            modelId: agent.fields.Model,
-            system,
-            messages: [{ role: "user", content: text }],
-            config: projectCfg,
-          });
-          replyText = result.text;
-          replyAuthor = agent.slug;
-          replyActorId = agent.slug;
-          replyKind = "agent";
-        } catch (e) {
-          this.log(`telegram[${this.channel.name}] agent reply failed: ${e.message}`);
-          replyText = `[apx error] ${e.message.slice(0, 200)}`;
-          replyAuthor = agentDisplay;
-          replyActorId = SUPERAGENT_ACTOR_ID;
-          replyKind = "superagent";
-        }
-      } else {
-        this.log(
-          `telegram[${this.channel.name}] route_to_agent="${routeSlug}" not usable (missing or no model) → trying super-agent`
-        );
-      }
-    }
-
-    // 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.
-    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 = () => {
-      const lang = (this.globalConfig?.user?.language || "es").slice(0, 2);
-      const byLang = {
-        es: "Dale, estoy con eso… 🛠️",
-        en: "On it — working on that… 🛠️",
-        pt: "Já estou nisso… 🛠️",
-      };
-      return byLang[lang] || byLang.es;
-    };
-    if (!replyText && isSuperAgentEnabled(this.globalConfig)) {
-      const onEvent = async (ev) => {
-        try {
-          if (ev.type === "tool_start" && !sentHeadsUp && streamedCount === 0) {
-            sentHeadsUp = true;
-            const heads = headsUpPhrase();
-            await this._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: this.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 this._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: this.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: this.channel.name,
-                in_reply_to: u.update_id,
-                tool: t.tool,
-                args: t.args,
-                result: t.result,
-                iteration: ev.iteration,
-              },
-            });
-          }
-        } catch (e) {
-          // A failed intermediate send must not abort the whole run.
-          this.log(`telegram[${this.channel.name}] stream event failed: ${e.message}`);
-        }
-      };
-
-      const confirmAdapter = createTelegramConfirmAdapter({
-        token: resolveBotToken(this.channel),
-        chatId: chat_id,
-        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: slashedPrompt,
-          previousMessages,
-          channel: CHANNELS.TELEGRAM,
-          relationshipBlock,
-          allowedTools,
-          contextNote: slashedContextNote || undefined,
-          channelMeta: buildTelegramMeta({
-            channelName: this.channel.name,
-            author,
-            chatId: chat_id,
-            target,
-            routeToAgent: this.channel.route_to_agent,
-          }),
-          signal: abortCtrl.signal,
-          onEvent,
-          requestConfirmation: confirmAdapter.requestConfirmation,
-        });
-        replyText = sa.text;
-        replyAuthor = sa.name || agentDisplay;
-        replyActorId = SUPERAGENT_ACTOR_ID;
-        replyKind = "superagent";
-        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.
-        const askQuestions = askFlow.extractAskQuestionsFromTrace(sa.trace);
-        if (askQuestions && chat_id) {
-          if (chat_id) this.activeRequests.delete(chat_id);
-          stopTyping();
-          try {
-            await this._startAskFlow({
-              chat_id,
-              projectId: target?.id,
-              authorId: msg.from?.id,
-              questions: askQuestions,
-              author,
-              agentDisplay,
-              relationshipBlock,
-              allowedTools,
-              target,
-              sender,
-              update_id: u.update_id,
-            });
-          } catch (e) {
-            this.log(`telegram[${this.channel.name}] ask flow start failed: ${e.message}`);
-          }
-          return; // The reply for this turn IS the ask flow.
-        }
-      } 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.
-          this.log(`telegram[${this.channel.name}] request aborted for chat ${chat_id}`);
-          if (chat_id) this.activeRequests.delete(chat_id);
-          stopTyping();
-          return;
-        }
-        this.log(`telegram[${this.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"}).`;
-        replyAuthor = agentDisplay;
-        replyActorId = SUPERAGENT_ACTOR_ID;
-        replyKind = "superagent";
-      }
-    }
-
-    if (chat_id) this.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 && streamedCount === 0) toSend = "Listo.";
-
-    stopTyping();
-    if (!toSend) return; // everything was already streamed — nothing left to send
-
-    try {
-      await this._send({ chat_id, text: toSend });
-      const meta = {
-        chat_id,
-        tg_channel: this.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) {
-      this.log(`telegram[${this.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: this.channel.name,
-          in_reply_to: u.update_id,
-          send_error: e.message,
-          ...(saUsage ? { usage: saUsage } : {}),
-        },
-      });
-    }
+    return handleUpdate(this, u);
   }
 
   async _handleCallbackQuery(callbackQuery) {
@@ -1208,10 +549,6 @@ class ChannelPoller {
   }
 }
 
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
-
 // ---------- plugin export ---------------------------------------------------
 
 export default {