@agentprojectcontext/apx 1.42.1 → 1.42.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.42.1",
+  "version": "1.42.2",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,62 @@
+// Low-level Telegram Bot API client — the single place the raw JSON endpoints
+// are called. Higher layers (the poller's send/typing/keyboard methods, the
+// confirmation adapter, the ask flow) compose these instead of hand-rolling
+// fetch boilerplate, so each endpoint's quirks live in exactly one spot. These
+// used to be duplicated across the poller AND the confirm adapter.
+//
+// Every call is token-explicit (no channel/config coupling) so it's reusable
+// from any surface — poller, adapter, routines, tests. Media uploads (multipart
+// FormData) stay in ./media.js; this module owns the JSON endpoints.
+import { API_BASE } from "./media.js";
+
+/**
+ * POST a JSON body to a Bot API method. Returns the parsed `result` on success;
+ * throws on transport failure or a non-ok Telegram response. Best-effort callers
+ * (typing, keyboard edits, callback acks) wrap this in their own try/catch.
+ */
+async function apiCall(token, method, body) {
+  const res = await fetch(`${API_BASE}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const json = await res.json().catch(() => ({}));
+  if (!json.ok) throw new Error(json.description || `${method} failed (${res.status})`);
+  return json.result;
+}
+
+/** sendMessage: the plain text reply (optionally with an inline keyboard). */
+export function sendMessage(token, chatId, { text, reply_markup, parse_mode } = {}) {
+  const body = { chat_id: chatId, text };
+  if (reply_markup) body.reply_markup = reply_markup;
+  if (parse_mode) body.parse_mode = parse_mode;
+  return apiCall(token, "sendMessage", body);
+}
+
+/** sendChatAction: the "typing…" indicator (auto-clears after ~5s). */
+export function sendChatAction(token, chatId, action = "typing") {
+  return apiCall(token, "sendChatAction", { chat_id: chatId, action });
+}
+
+/** editMessageReplyMarkup: swap/clear the inline keyboard on a sent message. */
+export function editMessageReplyMarkup(token, chatId, messageId, reply_markup) {
+  const body = { chat_id: chatId, message_id: messageId };
+  if (reply_markup) body.reply_markup = reply_markup;
+  return apiCall(token, "editMessageReplyMarkup", body);
+}
+
+/** answerCallbackQuery: clear the spinner on a tapped inline button (+ toast). */
+export function answerCallbackQuery(token, callbackQueryId, text) {
+  const body = { callback_query_id: callbackQueryId };
+  if (text) body.text = text;
+  return apiCall(token, "answerCallbackQuery", body);
+}
+
+/** getUpdates: long-poll for inbound updates from a given offset. */
+export async function getUpdates(token, { offset = 0, timeout = 25 } = {}) {
+  const res = await fetch(`${API_BASE}/bot${token}/getUpdates?timeout=${timeout}&offset=${offset}`);
+  if (!res.ok) throw new Error(`getUpdates ${res.status}`);
+  const json = await res.json();
+  if (!json.ok) throw new Error(json.description || "telegram error");
+  return json.result || [];
+}

package/src/core/channels/telegram/ask-callbacks.js

@@ -0,0 +1,238 @@
+// ask_questions flow orchestration for Telegram, extracted from the host poller
+// so that file stays focused on process lifecycle. Like dispatch.js, every
+// function takes the poller instance (`self`) and reaches its I/O surface
+// (self._send / _editKeyboard / _answerCallback / _startTyping) and config
+// through it. The flow's own state machine lives in ./ask.js; this is the glue
+// that turns its decisions into Telegram messages and re-enters the reply path.
+import * as askFlow from "./ask.js";
+import { resolveBotToken } from "./helpers.js";
+import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply } from "./reply.js";
+import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
+import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
+import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
+import { CHANNELS } from "#core/constants/channels.js";
+import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
+
+/**
+ * Route an inbound callback_query. ask_questions button presses are handled
+ * here; everything else falls through to the confirmation adapter. Both use
+ * `apx:<verb>:...` namespacing but the ask flow owns its own state.
+ */
+export async function handleCallbackQuery(self, callbackQuery) {
+  const data = callbackQuery.data || "";
+  if (data.startsWith("apx:ask:")) {
+    await handleAskCallback(self, callbackQuery);
+    return;
+  }
+  const adapter = createTelegramConfirmAdapter({
+    token: resolveBotToken(self.channel),
+    chatId: callbackQuery.message?.chat?.id,
+    pendingStore: getConfirmStore(),
+  });
+  const handled = await adapter.handleCallbackQuery(callbackQuery);
+  if (!handled) {
+    self.log(`telegram[${self.channel.name}] unhandled callback_query: ${callbackQuery.data}`);
+  }
+}
+
+/**
+ * Draw the current question as a fresh message with its inline keyboard, wiping
+ * the previous question's keyboard so the chat reads as a clean history.
+ */
+export async function renderQuestion(self, state) {
+  const text = askFlow.formatQuestionText(state);
+  const reply_markup = askFlow.buildKeyboard(state);
+  if (state.messageId) {
+    try {
+      await self._editKeyboard({
+        chat_id: state.chatId,
+        message_id: state.messageId,
+        reply_markup: { inline_keyboard: [] },
+      });
+    } catch { /* best-effort */ }
+  }
+  const sent = await self._send({ chat_id: state.chatId, text, reply_markup, parse_mode: "Markdown" });
+  state.messageId = sent?.message_id || null;
+  askFlow.saveState(state.chatId, state);
+}
+
+/**
+ * Kick off a brand-new ask flow after the super-agent called ask_questions. The
+ * flow's `resume` callback captures the per-turn context so when the compiled
+ * answer arrives we run another super-agent turn without retyping the inputs.
+ */
+export async function startAskFlow(self, ctx) {
+  const state = askFlow.startFlow({
+    chatId: ctx.chat_id,
+    projectId: ctx.projectId,
+    authorId: ctx.authorId,
+    questions: ctx.questions,
+    resume: async (compiled) => {
+      await runResumedTurn(self, { ...ctx, compiled });
+    },
+  });
+  await renderQuestion(self, state);
+}
+
+/** Apply an inline-keyboard press, then react: redraw, advance, cancel or finish. */
+export async function handleAskCallback(self, callbackQuery) {
+  const chatId = callbackQuery.message?.chat?.id;
+  if (!chatId) return;
+  const result = askFlow.applyCallback(chatId, callbackQuery.data || "");
+  // Ack the press regardless — keeps the spinner from hanging client-side.
+  await self._answerCallback({ callback_query_id: callbackQuery.id });
+  if (!result) return; // stale or unknown — adapter already ack'd.
+
+  if (result.action === "redraw") {
+    // Multi-select toggle: refresh the keyboard on the SAME message.
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: askFlow.buildKeyboard(result.state),
+      });
+    } catch (e) {
+      self.log(`telegram[${self.channel.name}] redraw failed: ${e.message}`);
+    }
+    return;
+  }
+  if (result.action === "advance") {
+    await renderQuestion(self, result.state);
+    return;
+  }
+  if (result.action === "cancel") {
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: { inline_keyboard: [] },
+      });
+      await self._send({ chat_id: chatId, text: "Pregunta cancelada." });
+    } catch { /* best-effort */ }
+    return;
+  }
+  if (result.action === "done") {
+    try {
+      await self._editKeyboard({
+        chat_id: chatId,
+        message_id: callbackQuery.message?.message_id,
+        reply_markup: { inline_keyboard: [] },
+      });
+    } catch { /* best-effort */ }
+    // Feed the compiled answer back as a synthetic user turn.
+    if (typeof result.state.resume === "function") {
+      await result.state.resume(result.compiled);
+    }
+  }
+}
+
+/**
+ * Apply a free-text user reply when there's a pending free-text question.
+ * Returns true iff the message was consumed by the ask flow (so the normal
+ * super-agent path should be skipped for this update).
+ */
+export async function maybeConsumeAskTextAnswer(self, { chat_id, text }) {
+  if (!chat_id || !text) return false;
+  if (!askFlow.hasPendingFreeText(chat_id)) return false;
+  const state = askFlow.applyTextAnswer(chat_id, text);
+  if (!state) return false;
+  // Advance: emit a synthetic "next" to move past this question.
+  const next = askFlow.applyCallback(chat_id, `apx:ask:${state.correlationId}:next`);
+  if (!next) return true;
+  if (next.action === "advance") {
+    await renderQuestion(self, next.state);
+    return true;
+  }
+  if (next.action === "done") {
+    if (typeof next.state.resume === "function") {
+      await next.state.resume(next.compiled);
+    }
+    return true;
+  }
+  return true;
+}
+
+/**
+ * Run a follow-up super-agent turn with the compiled answers as the user prompt.
+ * Shares the exact reply path as a normal inbound turn (./reply.js) — only the
+ * photo/audio/reset preamble is skipped. Re-enters the ask flow if the model
+ * decides to ask again.
+ */
+export async function runResumedTurn(self, ctx) {
+  const { chat_id, compiled, target, relationshipBlock, allowedTools, author, agentDisplay, update_id, sender, authorId } = ctx;
+  if (!chat_id) return;
+  // Log the synthetic user message so getRecentTelegramTurnsFromFs picks it up
+  // on the NEXT inbound. Mirrors how a normal text reply would be recorded.
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "in",
+    type: "user",
+    actor_id: authorId ? String(authorId) : (author || "ask_flow"),
+    external_id: `ask-${Date.now()}`,
+    author: author || "user",
+    body: compiled,
+    meta: { chat_id, user_id: authorId || null, tg_channel: self.channel.name, ask_flow: true },
+  });
+
+  const previousMessages = getRecentTelegramTurnsFromFs({ chat_id, keepRecent: 40, max_age_hours: 24 });
+
+  const { onEvent, state } = buildStreamHandler(self, { chat_id, update_id, agentDisplay });
+  const stopTyping = self._startTyping(chat_id);
+  let replyText;
+  let replyAuthor;
+  let saUsage = null;
+  try {
+    const sa = await runTelegramSuperAgent(self, {
+      chat_id,
+      prompt: compiled,
+      previousMessages,
+      target,
+      author,
+      relationshipBlock,
+      allowedTools,
+      onEvent,
+    });
+
+    // Did the model ask again? Restart the flow instead of replying.
+    const followupAsk = askFlow.extractAskQuestionsFromTrace(sa.trace);
+    if (followupAsk) {
+      stopTyping();
+      await startAskFlow(self, {
+        chat_id,
+        projectId: target?.id,
+        authorId,
+        questions: followupAsk,
+        author,
+        agentDisplay,
+        relationshipBlock,
+        allowedTools,
+        target,
+        sender,
+        update_id,
+      });
+      return;
+    }
+    replyText = sa.text;
+    replyAuthor = sa.name || agentDisplay;
+    saUsage = sa.usage;
+  } catch (e) {
+    self.log(`telegram[${self.channel.name}] ask resume failed: ${e.message}`);
+    replyText = telegramErrorText(self, e);
+    replyAuthor = agentDisplay;
+  }
+
+  stopTyping();
+  await sendFinalReply(self, {
+    chat_id,
+    update_id,
+    replyText,
+    replyAuthor,
+    replyActorId: SUPERAGENT_ACTOR_ID,
+    replyKind: "superagent",
+    saUsage,
+    streamedCount: state.streamedCount,
+    lastStreamedText: state.lastStreamedText,
+    agentDisplay,
+    extraMeta: { ask_resume: true },
+  });
+}

package/src/core/confirmation/adapters/telegram.js

@@ -24,7 +24,10 @@
 // keyboard but before the user tapped, pendingStore.wasKnown() detects the
 // SQLite row with no memory entry and we show "Expirado" instead of an error.
 
-const API_BASE = "https://api.telegram.org";
+// Raw Bot API calls go through the shared client so endpoint boilerplate lives
+// in one place (these used to be hand-rolled fetch calls duplicated here).
+import { sendMessage, answerCallbackQuery as apiAnswerCallbackQuery, editMessageReplyMarkup } from "#core/channels/telegram/api.js";
+
 const TIMEOUT_MS = 60_000; // 60 s — long enough for a human, short enough to not block forever
 
 /**
@@ -81,51 +84,31 @@ export function createTelegramConfirmAdapter({ token, chatId, pendingStore }) {
 
 async function sendConfirmKeyboard(token, chatId, description, correlationId, timeoutMs) {
   const timeoutSec = Math.round(timeoutMs / 1000);
-  await fetch(`${API_BASE}/bot${token}/sendMessage`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      chat_id: chatId,
-      text:
-        `⚠️ *Confirm action*\n\n${escapeMarkdown(description)}\n\n` +
-        `_Expires in ${timeoutSec}s. No response → cancelled._`,
-      parse_mode: "Markdown",
-      reply_markup: {
-        inline_keyboard: [[
-          { text: "✅ Yes", callback_data: `apx:confirm:${correlationId}:yes` },
-          { text: "❌ No",  callback_data: `apx:confirm:${correlationId}:no` },
-        ]],
-      },
-    }),
+  await sendMessage(token, chatId, {
+    text:
+      `⚠️ *Confirm action*\n\n${escapeMarkdown(description)}\n\n` +
+      `_Expires in ${timeoutSec}s. No response → cancelled._`,
+    parse_mode: "Markdown",
+    reply_markup: {
+      inline_keyboard: [[
+        { text: "✅ Yes", callback_data: `apx:confirm:${correlationId}:yes` },
+        { text: "❌ No",  callback_data: `apx:confirm:${correlationId}:no` },
+      ]],
+    },
   });
 }
 
+// best-effort — Telegram gives only ~30s to answer; after that it's already cleared
 async function answerCallbackQuery(token, callbackQueryId, text) {
   try {
-    await fetch(`${API_BASE}/bot${token}/answerCallbackQuery`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ callback_query_id: callbackQueryId, text }),
-    });
-  } catch {
-    // best-effort — Telegram gives only 30s to answer; after that it's already cleared
-  }
+    await apiAnswerCallbackQuery(token, callbackQueryId, text);
+  } catch { /* best-effort */ }
 }
 
 async function editMessageButtons(token, chatId, messageId, inlineKeyboard) {
   try {
-    await fetch(`${API_BASE}/bot${token}/editMessageReplyMarkup`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({
-        chat_id: chatId,
-        message_id: messageId,
-        reply_markup: { inline_keyboard: inlineKeyboard },
-      }),
-    });
-  } catch {
-    // best-effort
-  }
+    await editMessageReplyMarkup(token, chatId, messageId, { inline_keyboard: inlineKeyboard });
+  } catch { /* best-effort */ }
 }
 
 // Escape Markdown special chars so description text doesn't break Telegram markup.

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

@@ -140,7 +140,12 @@ async function _handleMessage({ ws, text, previousMessages }, { projects, config
       channel: CHANNELS.DESKTOP,
       ...(slashed.handled ? { contextNote: slashed.contextNote } : {}),
       channelMeta: { voice: true }, // desktop module is voice-first → spoken mode
-      previousMessages: history.slice(0, -1),
+      // WS path: history was just appended with the current user turn (line 87),
+      // so drop it. HTTP path: `previousMessages` came in already excluding the
+      // current user turn (the renderer slices it off before POSTing), so
+      // dropping again would silently strip the last assistant reply — making
+      // every turn look like a fresh conversation to the model.
+      previousMessages: ws ? history.slice(0, -1) : history,
       overrideModel: cfg.model || null,
       signal: controller.signal,
       onToken: (chunk) => { liveBuf += chunk; },

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

@@ -28,22 +28,14 @@
 //   }
 
 // 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";
+// telegram/ — dispatch (inbound routing), reply (the super-agent turn),
+// ask-callbacks (the ask_questions flow), inbound/ (media), and the raw Bot API
+// in api.js + media.js. The poller keeps only what the *running process* needs:
+// lifecycle, the poll loop, offset state, and the thin I/O surface (self._send
+// etc.) that the extracted core logic calls back into through `self`.
+import { appendGlobalMessage } from "#core/stores/messages.js";
 import { resolveAgentName, SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
-import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pending-store.js";
 import { CHANNELS } from "#core/constants/channels.js";
-import { createTelegramConfirmAdapter } from "#core/confirmation/adapters/telegram.js";
-import * as askFlow from "#core/channels/telegram/ask.js";
-
-// API_BASE re-imported from #core/channels/telegram/media.js below
-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 {
   loadState,
   saveState,
@@ -54,12 +46,13 @@ 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, API_BASE } from "#core/channels/telegram/media.js";
+import { handleCallbackQuery, startAskFlow, maybeConsumeAskTextAnswer } from "#core/channels/telegram/ask-callbacks.js";
+import { sendMessage, sendChatAction, editMessageReplyMarkup, answerCallbackQuery, getUpdates } from "#core/channels/telegram/api.js";
+import { sendPhoto, sendVoice, sendDocument, sendAudio } from "#core/channels/telegram/media.js";
 export { sendPhoto, sendVoice, sendDocument, sendAudio };
 
+const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+
 // ---------- per-channel poller ----------------------------------------------
 
 class ChannelPoller {
@@ -157,13 +150,7 @@ class ChannelPoller {
   }
 
   async _getUpdates() {
-    const token = resolveBotToken(this.channel);
-    const url = `${API_BASE}/bot${token}/getUpdates?timeout=25&offset=${this.offset}`;
-    const res = await fetch(url);
-    if (!res.ok) throw new Error(`getUpdates ${res.status}`);
-    const json = await res.json();
-    if (!json.ok) throw new Error(json.description || "telegram error");
-    return json.result || [];
+    return getUpdates(resolveBotToken(this.channel), { offset: this.offset });
   }
 
   // Method body lives in ./dispatch.js as `handleUpdate(self, u)` so this file
@@ -173,270 +160,42 @@ class ChannelPoller {
     return handleUpdate(this, u);
   }
 
+  // ── ask_questions flow ──────────────────────────────────────────────────
+  // Orchestration lives in ./ask-callbacks.js (state machine in ./ask.js). These
+  // are thin delegates: dispatch.js reaches _startAskFlow / _maybeConsumeAsk...
+  // through `self`, and inbound callback_query routes through _handleCallbackQuery.
+  // The core functions call back into this poller's I/O surface (_send etc.).
   async _handleCallbackQuery(callbackQuery) {
-    // Route ask_questions button presses before the confirmation adapter —
-    // both use `apx:<verb>:...` namespacing but ask owns its own state.
-    const data = callbackQuery.data || "";
-    if (data.startsWith("apx:ask:")) {
-      await this._handleAskCallback(callbackQuery);
-      return;
-    }
-
-    const adapter = createTelegramConfirmAdapter({
-      token: resolveBotToken(this.channel),
-      chatId: callbackQuery.message?.chat?.id,
-      pendingStore: getConfirmStore(),
-    });
-    const handled = await adapter.handleCallbackQuery(callbackQuery);
-    if (!handled) {
-      this.log(`telegram[${this.channel.name}] unhandled callback_query: ${callbackQuery.data}`);
-    }
-  }
-
-  // ── ask_questions: state-machine helpers ───────────────────────────────
-  // The flow lives in telegram-ask.js; this class owns the I/O (sending
-  // messages, editing keyboards, re-entering the super-agent loop with the
-  // compiled answer once the flow finishes).
-
-  async _renderQuestion(state) {
-    const text = askFlow.formatQuestionText(state);
-    const reply_markup = askFlow.buildKeyboard(state);
-    // If we already have a message for the previous question, leave its
-    // keyboard wiped — we draw a fresh message per question for clearer
-    // history in the chat (the question text stays as a record).
-    if (state.messageId) {
-      try {
-        await this._editKeyboard({
-          chat_id: state.chatId,
-          message_id: state.messageId,
-          reply_markup: { inline_keyboard: [] },
-        });
-      } catch { /* best-effort */ }
-    }
-    const sent = await this._send({
-      chat_id: state.chatId,
-      text,
-      reply_markup,
-      parse_mode: "Markdown",
-    });
-    state.messageId = sent?.message_id || null;
-    askFlow.saveState(state.chatId, state);
+    return handleCallbackQuery(this, callbackQuery);
   }
 
-  // Kick off a brand-new ask flow after the super-agent called ask_questions.
-  // The flow's `resume` callback captures the per-turn context (sender,
-  // relationship, project) so when the compiled answer arrives we can run
-  // another super-agent turn without retyping all the inputs.
   async _startAskFlow(ctx) {
-    const state = askFlow.startFlow({
-      chatId: ctx.chat_id,
-      projectId: ctx.projectId,
-      authorId: ctx.authorId,
-      questions: ctx.questions,
-      resume: async (compiled) => {
-        await this._runResumedTurn({ ...ctx, compiled });
-      },
-    });
-    await this._renderQuestion(state);
+    return startAskFlow(this, ctx);
   }
 
-  // Apply an inline-keyboard press, then react: redraw, advance, or finish.
-  async _handleAskCallback(callbackQuery) {
-    const chatId = callbackQuery.message?.chat?.id;
-    if (!chatId) return;
-    const result = askFlow.applyCallback(chatId, callbackQuery.data || "");
-    // Ack the press regardless — keeps the spinner from hanging client-side.
-    await this._answerCallback({ callback_query_id: callbackQuery.id });
-    if (!result) return; // stale or unknown — adapter already ack'd.
-
-    if (result.action === "redraw") {
-      // Multi-select toggle: just refresh the keyboard on the SAME message.
-      try {
-        await this._editKeyboard({
-          chat_id: chatId,
-          message_id: callbackQuery.message?.message_id,
-          reply_markup: askFlow.buildKeyboard(result.state),
-        });
-      } catch (e) {
-        this.log(`telegram[${this.channel.name}] redraw failed: ${e.message}`);
-      }
-      return;
-    }
-    if (result.action === "advance") {
-      await this._renderQuestion(result.state);
-      return;
-    }
-    if (result.action === "cancel") {
-      try {
-        await this._editKeyboard({
-          chat_id: chatId,
-          message_id: callbackQuery.message?.message_id,
-          reply_markup: { inline_keyboard: [] },
-        });
-        await this._send({ chat_id: chatId, text: "Pregunta cancelada." });
-      } catch { /* best-effort */ }
-      return;
-    }
-    if (result.action === "done") {
-      try {
-        await this._editKeyboard({
-          chat_id: chatId,
-          message_id: callbackQuery.message?.message_id,
-          reply_markup: { inline_keyboard: [] },
-        });
-      } catch { /* best-effort */ }
-      // Feed the compiled answer back as a synthetic user turn.
-      if (typeof result.state.resume === "function") {
-        await result.state.resume(result.compiled);
-      }
-    }
-  }
-
-  // Apply a free-text user reply when there's a pending free-text question.
-  // Returns true iff the message was consumed by the ask flow (so the normal
-  // super-agent path should be skipped for this update).
-  async _maybeConsumeAskTextAnswer({ chat_id, text }) {
-    if (!chat_id || !text) return false;
-    if (!askFlow.hasPendingFreeText(chat_id)) return false;
-    const state = askFlow.applyTextAnswer(chat_id, text);
-    if (!state) return false;
-    // Advance: emit a synthetic "next" to move past this question.
-    const next = askFlow.applyCallback(
-      chat_id,
-      `apx:ask:${state.correlationId}:next`,
-    );
-    if (!next) return true;
-    if (next.action === "advance") {
-      await this._renderQuestion(next.state);
-      return true;
-    }
-    if (next.action === "done") {
-      if (typeof next.state.resume === "function") {
-        await next.state.resume(next.compiled);
-      }
-      return true;
-    }
-    return true;
+  async _maybeConsumeAskTextAnswer(args) {
+    return maybeConsumeAskTextAnswer(this, args);
   }
 
-  // Run a follow-up super-agent turn with the compiled answers as the user
-  // 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;
-    // Log the synthetic user message so getRecentTelegramTurnsFromFs picks
-    // it up on the NEXT inbound. Mirrors how a normal text reply would be
-    // recorded.
-    appendGlobalMessage({
-      channel: CHANNELS.TELEGRAM,
-      direction: "in",
-      type: "user",
-      actor_id: authorId ? String(authorId) : (author || "ask_flow"),
-      external_id: `ask-${Date.now()}`,
-      author: author || "user",
-      body: compiled,
-      meta: {
-        chat_id,
-        user_id: authorId || null,
-        tg_channel: this.channel.name,
-        ask_flow: true,
-      },
-    });
-
-    const previousMessages = getRecentTelegramTurnsFromFs({
-      chat_id,
-      keepRecent: 40,
-      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 runTelegramSuperAgent(this, {
-        chat_id,
-        prompt: compiled,
-        previousMessages,
-        target,
-        author,
-        relationshipBlock,
-        allowedTools,
-        onEvent,
-      });
-
-      // 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,
-          authorId,
-          questions: followupAsk,
-          author,
-          agentDisplay,
-          relationshipBlock,
-          allowedTools,
-          target,
-          sender,
-          update_id,
-        });
-        return;
-      }
-      replyText = sa.text;
-      replyAuthor = sa.name || agentDisplay;
-      saUsage = sa.usage;
-    } catch (e) {
-      this.log(`telegram[${this.channel.name}] ask resume failed: ${e.message}`);
-      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 },
-    });
+  // Resolve the bot token + outbound chat for this channel — the single place
+  // the "no token / no chat" guards live, shared by every send method.
+  _resolve(chat_id) {
+    const token = resolveBotToken(this.channel);
+    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
+    const target = chat_id || resolveChatId(this.channel);
+    if (!target) throw new Error(`channel ${this.channel.name}: no chat_id`);
+    return { token, target };
   }
 
-  // Show "typing..." indicator in the chat. Telegram clears it automatically
-  // after 5 seconds, so call this every ~4s while a long operation is going.
+  // Show "typing..." indicator. Telegram clears it after ~5s; _startTyping
+  // re-pings every 4s. Best-effort — failures aren't worth surfacing.
   async _typing(chat_id) {
-    try {
-      const token = resolveBotToken(this.channel);
-      if (!token || !chat_id) return;
-      const url = `${API_BASE}/bot${token}/sendChatAction`;
-      await fetch(url, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ chat_id, action: "typing" }),
-      });
-    } catch {
-      // best-effort; failures here aren't worth surfacing
-    }
+    const token = resolveBotToken(this.channel);
+    if (!token || !chat_id) return;
+    try { await sendChatAction(token, chat_id); } catch { /* best-effort */ }
   }
 
-  // Returns a function that pings sendChatAction every 4s until called as
-  // stop(). Used to wrap the engine round-trip in a "typing" loop so the
-  // user sees feedback while qwen thinks.
+  // Returns a stop() fn; pings the typing indicator every 4s until called.
   _startTyping(chat_id) {
     if (!chat_id) return () => {};
     let stopped = false;
@@ -450,58 +209,27 @@ class ChannelPoller {
   }
 
   async _send({ chat_id, text, reply_markup, parse_mode }) {
-    const token = resolveBotToken(this.channel);
-    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
-    const target = chat_id || resolveChatId(this.channel);
-    if (!target) throw new Error(`channel ${this.channel.name}: no chat_id`);
-    const url = `${API_BASE}/bot${token}/sendMessage`;
-    const body = { chat_id: target, text };
-    if (reply_markup) body.reply_markup = reply_markup;
-    if (parse_mode) body.parse_mode = parse_mode;
-    const res = await fetch(url, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-    });
-    const json = await res.json();
-    if (!json.ok) throw new Error(json.description || `send failed (${res.status})`);
-    return json.result;
+    const { token, target } = this._resolve(chat_id);
+    return sendMessage(token, target, { text, reply_markup, parse_mode });
   }
 
-  // Replace just the inline keyboard on a previously-sent message (used to
-  // refresh after a multi-select toggle, or to wipe buttons once the flow
-  // has moved on). Best-effort: failures are logged but don't break the flow.
+  // Replace/clear the inline keyboard on a sent message. Best-effort: logged.
   async _editKeyboard({ chat_id, message_id, reply_markup }) {
     const token = resolveBotToken(this.channel);
     if (!token) return;
     try {
-      const url = `${API_BASE}/bot${token}/editMessageReplyMarkup`;
-      const body = { chat_id, message_id };
-      if (reply_markup) body.reply_markup = reply_markup;
-      await fetch(url, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-      });
+      await editMessageReplyMarkup(token, chat_id, message_id, reply_markup);
     } catch (e) {
       this.log(`telegram[${this.channel.name}] editMessageReplyMarkup failed: ${e.message}`);
     }
   }
 
-  // Acknowledge a callback button press so the user's Telegram client clears
-  // the spinner on the tapped button. Optional `text` shows a small toast.
+  // Ack a callback button press so the client clears the spinner (+ optional toast).
   async _answerCallback({ callback_query_id, text }) {
     const token = resolveBotToken(this.channel);
     if (!token) return;
     try {
-      const url = `${API_BASE}/bot${token}/answerCallbackQuery`;
-      const body = { callback_query_id };
-      if (text) body.text = text;
-      await fetch(url, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-      });
+      await answerCallbackQuery(token, callback_query_id, text);
     } catch (e) {
       this.log(`telegram[${this.channel.name}] answerCallbackQuery failed: ${e.message}`);
     }
@@ -509,40 +237,42 @@ class ChannelPoller {
 
   /** Send a photo via this channel */
   async _sendPhoto({ chat_id, photo, caption, parse_mode }) {
-    const token = resolveBotToken(this.channel);
-    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
-    const target = chat_id || resolveChatId(this.channel);
-    if (!target) throw new Error(`channel ${this.channel.name}: no chat_id`);
+    const { token, target } = this._resolve(chat_id);
     return sendPhoto(token, target, photo, { caption, parse_mode });
   }
 
   /** Send a voice message via this channel */
   async _sendVoice({ chat_id, audio, caption, duration }) {
-    const token = resolveBotToken(this.channel);
-    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
-    const target = chat_id || resolveChatId(this.channel);
+    const { token, target } = this._resolve(chat_id);
     return sendVoice(token, target, audio, { caption, duration });
   }
 
   /** Send a document (PDF, zip, etc) via this channel */
   async _sendDocument({ chat_id, document, caption, filename, mime_type }) {
-    const token = resolveBotToken(this.channel);
-    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
-    const target = chat_id || resolveChatId(this.channel);
+    const { token, target } = this._resolve(chat_id);
     return sendDocument(token, target, document, { caption, filename, mime_type });
   }
 
   /** Send an audio file via this channel */
   async _sendAudio({ chat_id, audio, caption, title, performer }) {
-    const token = resolveBotToken(this.channel);
-    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
-    const target = chat_id || resolveChatId(this.channel);
+    const { token, target } = this._resolve(chat_id);
     return sendAudio(token, target, audio, { caption, title, performer });
   }
 }
 
 // ---------- plugin export ---------------------------------------------------
 
+// Pick the poller to send through: the named channel if given, else the first
+// channel with a usable bot token. Shared by every outbound helper below.
+function pickPoller(pollers, channelName) {
+  const p =
+    (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
+    pollers.find((pp) => resolveBotToken(pp.channel)) ||
+    null;
+  if (!p) throw new Error("no telegram channel available");
+  return p;
+}
+
 export default {
   id: "telegram",
 
@@ -582,11 +312,7 @@ export default {
       // the outbound on `messages` of the channel's target project so audit
       // trails are complete.
       async send({ channel: channelName, chat_id, text, author = resolveAgentName(config), project }) {
-        const p =
-          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
-          pollers.find((pp) => resolveBotToken(pp.channel)) ||
-          null;
-        if (!p) throw new Error("no telegram channel available");
+        const p = pickPoller(pollers, channelName);
         const result = await p._send({ chat_id, text });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
@@ -612,11 +338,7 @@ export default {
        * opts: { caption, parse_mode, channel, author }
        */
       async sendPhoto({ channel: channelName, chat_id, photo, caption, parse_mode, author = resolveAgentName(config) }) {
-        const p =
-          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
-          pollers.find((pp) => resolveBotToken(pp.channel)) ||
-          null;
-        if (!p) throw new Error("no telegram channel available");
+        const p = pickPoller(pollers, channelName);
         const result = await p._sendPhoto({ chat_id, photo, caption, parse_mode });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
@@ -636,11 +358,7 @@ export default {
        * audio: local file path or Buffer
        */
       async sendVoice({ channel: channelName, chat_id, audio, caption, duration, author = resolveAgentName(config) }) {
-        const p =
-          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
-          pollers.find((pp) => resolveBotToken(pp.channel)) ||
-          null;
-        if (!p) throw new Error("no telegram channel available");
+        const p = pickPoller(pollers, channelName);
         const result = await p._sendVoice({ chat_id, audio, caption, duration });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
@@ -660,11 +378,7 @@ export default {
        * document: local file path, Buffer, or public https URL.
        */
       async sendDocument({ channel: channelName, chat_id, document, caption, filename, mime_type, author = resolveAgentName(config) }) {
-        const p =
-          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
-          pollers.find((pp) => resolveBotToken(pp.channel)) ||
-          null;
-        if (!p) throw new Error("no telegram channel available");
+        const p = pickPoller(pollers, channelName);
         const result = await p._sendDocument({ chat_id, document, caption, filename, mime_type });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,
@@ -684,11 +398,7 @@ export default {
        * audio: local file path or Buffer
        */
       async sendAudio({ channel: channelName, chat_id, audio, caption, title, performer, author = resolveAgentName(config) }) {
-        const p =
-          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
-          pollers.find((pp) => resolveBotToken(pp.channel)) ||
-          null;
-        if (!p) throw new Error("no telegram channel available");
+        const p = pickPoller(pollers, channelName);
         const result = await p._sendAudio({ chat_id, audio, caption, title, performer });
         appendGlobalMessage({
           channel: CHANNELS.TELEGRAM,

package/src/interfaces/web/package-lock.json

@@ -3327,9 +3327,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.15",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
-      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "version": "8.5.16",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.16.tgz",
+      "integrity": "sha512-vuwillviilfKZsg0VGj5R/YwwcHx4SLsIOI/7K6mQkWx+l5cUHTjj5g0AasTBcyXsbfTgrwsUNmVUb5xVwyPwg==",
       "funding": [
         {
           "type": "opencollective",