@agentprojectcontext/apx 1.79.0 → 1.80.0

package/package.json

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

package/src/core/agent/run-agent.js

@@ -123,6 +123,9 @@ export async function runAgent({
   system,
   prompt,
   previousMessages = [],
+  // Files that arrived with this turn: [{ kind, mime, data (base64), path }].
+  // Channel handlers (e.g. an inbound Telegram photo) populate it.
+  attachments = [],
   overrideModel = null,
   // Content-routed model for this turn (selectModelByRules). Unlike
   // overrideModel it is health-checked and falls back down the chain.
@@ -263,7 +266,19 @@ export async function runAgent({
     }
   };
 
-  const conversation = [...previousMessages, { role: "user", content: prompt }];
+  // Attachments ride on THIS turn's user message. Only images are forwarded to
+  // the model (a multimodal engine renders them; the rest ignore the field);
+  // every other kind is already described in the prompt text by the channel
+  // handler, with its local path, so the agent can reach it with file tools.
+  const turnImages = attachments.filter((a) => a?.data && /^image\//.test(a.mime || ""));
+  const conversation = [
+    ...previousMessages,
+    {
+      role: "user",
+      content: prompt,
+      ...(turnImages.length > 0 ? { images: turnImages } : {}),
+    },
+  ];
   const trace = [];
   const totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";

package/src/core/agent/super-agent.js

@@ -33,6 +33,8 @@ export async function runSuperAgent({
   // Pre-rendered "who you're talking to" block (see buildRelationshipBlock).
   relationshipBlock = "",
   previousMessages = [],
+  // Files that arrived with this turn; forwarded to runAgent verbatim.
+  attachments = [],
   overrideModel = null,
   onEvent = null,
   signal,
@@ -146,6 +148,7 @@ export async function runSuperAgent({
       system,
       prompt: turnPrompt,
       previousMessages: history,
+      attachments,
       overrideModel,
       preferredModel: contentRoute?.model || null,
       toolSchemas,

package/src/core/agent/tools/tool-call-parser.js

@@ -64,6 +64,15 @@ export function extractPseudoToolCalls(text) {
   // run-agent loop then treats them identically.
   const llamaCalls = extractLlamaDottedFunctionCalls(text);
 
+  // `[tool call: NAME] {…json…}` — APX's own internal transcription of a tool
+  // call, which used to be written into Gemini history when a turn had no
+  // thought signature to replay. Models copied the format out of their own
+  // history and started writing calls instead of making them, and the line
+  // was delivered to the user verbatim. The history no longer contains it,
+  // but a model that already learned the shape (or any model that invents it)
+  // must have the call EXECUTED rather than printed.
+  const bracketCalls = extractBracketToolCalls(text);
+
   // Second pass: balanced `{name, arguments}` JSON anywhere in the text.
   const jsonCalls = [];
   for (let i = 0; i < text.length; i++) {
@@ -86,11 +95,11 @@ export function extractPseudoToolCalls(text) {
       parsed.arguments !== null &&
       !Array.isArray(parsed.arguments)
     ) {
-      // Skip JSON that is actually the args object inside a dotted-function
-      // wrapper we already captured — otherwise we'd double-fire the tool.
-      const insideLlamaWrap = llamaCalls.some(
-        (lc) => lc._rawStart <= i && balanced.end <= lc._rawEnd
-      );
+      // Skip JSON that is actually the args object inside a wrapper we already
+      // captured — otherwise we'd double-fire the tool.
+      const insideLlamaWrap =
+        llamaCalls.some((lc) => lc._rawStart <= i && balanced.end <= lc._rawEnd) ||
+        bracketCalls.some((bc) => bc._rawStart <= i && balanced.end <= bc._rawEnd);
       if (insideLlamaWrap) {
         i = balanced.end - 1;
         continue;
@@ -108,10 +117,45 @@ export function extractPseudoToolCalls(text) {
   // Strip internal markers used to dedupe against JSON pass.
   return [
     ...llamaCalls.map(({ _rawStart, _rawEnd, ...rest }) => rest),
+    ...bracketCalls.map(({ _rawStart, _rawEnd, ...rest }) => rest),
     ...jsonCalls,
   ];
 }
 
+// Parse `[tool call: NAME] {…}` — see the note in extractPseudoToolCalls.
+// `_raw` spans the bracket AND its argument object so the whole line is
+// removed from the visible text, not just the JSON half.
+function extractBracketToolCalls(text) {
+  const out = [];
+  const re = /\[tool[ _]call:\s*([a-zA-Z_][a-zA-Z0-9_]*)\]\s*/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const argsStart = m.index + m[0].length;
+    let args = {};
+    let end = argsStart;
+    if (text[argsStart] === "{") {
+      const balanced = readBalancedJson(text, argsStart);
+      if (balanced.ok) {
+        try {
+          const parsed = JSON.parse(text.slice(argsStart, balanced.end));
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) args = parsed;
+        } catch { /* keep {} — a malformed arg blob still beats printing it */ }
+        end = balanced.end;
+      }
+    }
+    out.push({
+      id: nextId(),
+      function: { name: m[1], arguments: args },
+      _pseudo: true,
+      _raw: text.slice(m.index, end),
+      _rawStart: m.index,
+      _rawEnd: end,
+    });
+    re.lastIndex = end;
+  }
+  return out;
+}
+
 // Parse the dotted-function format emitted by some Llama instructions:
 //
 //   <function.send_telegram({"text": "hi"})</function>
@@ -248,6 +292,10 @@ export function cleanTextOfPseudoToolCalls(text, knownNames) {
     if (call._raw) out = out.replace(call._raw, "");
   }
   out = out.replace(/\[tool result:\s*[^\]]+\]\s*/gi, "");
+  // …and the history annotation the message store substitutes for a stale
+  // answer (`sanitizeAssistantForContext`). It describes a turn; it is never
+  // something to say to the user.
+  out = out.replace(/\[omitted:[^\]]*\]\s*/gi, "");
   // Some models emit a stray `</function>` after the args without the
   // opening tag — sweep those too.
   out = out.replace(/<\/?function(?:\.[a-zA-Z_][a-zA-Z0-9_]*)?>/gi, "");

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

@@ -14,10 +14,33 @@ import { CHANNELS } from "#core/constants/channels.js";
 import { SUPERAGENT_ACTOR_ID } from "#core/identity/index.js";
 import { applyNudgeCallback } from "#core/nudge/index.js";
 
+/**
+ * The label the user actually tapped, recovered from the keyboard attached to
+ * the message. `callback_data` is a routing slug ("mover_workspace_hoy"); the
+ * label is what the human read ("Mover al workspace de hoy"), and that is the
+ * better thing to hand an agent.
+ */
+export function buttonLabelFor(callbackQuery) {
+  const rows = callbackQuery?.message?.reply_markup?.inline_keyboard || [];
+  const data = callbackQuery?.data;
+  for (const row of rows) {
+    for (const btn of row || []) {
+      if (btn?.callback_data === data && btn?.text) return String(btn.text);
+    }
+  }
+  return "";
+}
+
 /**
  * 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.
+ * here; `apx:`-namespaced presses belong to an APX flow (ask / nudge /
+ * confirmation) and never reach the agent. Anything else is a button someone
+ * else put in the chat, and is treated as a user turn.
+ *
+ * TELEGRAM CONTRACT: every callback_query must be answered, handled or not.
+ * Until it is, the client keeps the button spinning and the tap looks dead —
+ * which is exactly how "the inline buttons do nothing" is reported. Nothing
+ * below may return without an `_answerCallback`.
  */
 export async function handleCallbackQuery(self, callbackQuery) {
   const data = callbackQuery.data || "";
@@ -35,9 +58,53 @@ export async function handleCallbackQuery(self, callbackQuery) {
     pendingStore: getConfirmStore(),
   });
   const handled = await adapter.handleCallbackQuery(callbackQuery);
-  if (!handled) {
-    self.log(`telegram[${self.channel.name}] unhandled callback_query: ${callbackQuery.data}`);
+  if (handled) return;
+
+  // `apx:noop` is a deliberately dead button (a disabled confirmation, an
+  // expired panel). Ack it so the spinner clears and stop there — replaying it
+  // to the agent would answer a question that is already closed.
+  if (data === "apx:noop" || data.startsWith("apx:")) {
+    await self._answerCallback({ callback_query_id: callbackQuery.id });
+    self.log(`telegram[${self.channel.name}] stale apx callback: ${data}`);
+    await clearKeyboard(self, callbackQuery);
+    return;
   }
+
+  // A button APX did not send — an agent-authored keyboard, another tool
+  // posting into this chat. Ack first (never leave it spinning), then let the
+  // press be a turn: re-enter the normal inbound path with the button's label
+  // as the text, so identity, routing and the agent loop all apply unchanged.
+  await self._answerCallback({ callback_query_id: callbackQuery.id });
+  const text = buttonLabelFor(callbackQuery) || data;
+  const chat = callbackQuery.message?.chat;
+  if (!chat?.id || !text) {
+    self.log(`telegram[${self.channel.name}] unhandled callback_query: ${data}`);
+    return;
+  }
+  self.log(`telegram[${self.channel.name}] button press → turn: ${data} (${text})`);
+  await self._handleUpdate({
+    update_id: callbackQuery.id,
+    message: {
+      message_id: callbackQuery.message?.message_id,
+      from: callbackQuery.from,
+      chat,
+      date: Math.floor(Date.now() / 1000),
+      text,
+    },
+  });
+}
+
+/** Best-effort: take the keyboard off a message whose buttons are now dead. */
+async function clearKeyboard(self, callbackQuery) {
+  const chatId = callbackQuery.message?.chat?.id;
+  if (!chatId) return;
+  try {
+    await self._editKeyboard({
+      chat_id: chatId,
+      message_id: callbackQuery.message?.message_id,
+      reply_markup: { inline_keyboard: [] },
+    });
+  } catch { /* best-effort */ }
 }
 
 /**
@@ -111,9 +178,22 @@ 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.
+  if (!result) {
+    // The flow is gone: ask state is process-local (see ask.js), so a daemon
+    // restart or the 30-min TTL kills it while its keyboard stays in the chat
+    // looking live. Acking silently is what makes the button read as broken —
+    // the tap "does nothing" and the user keeps tapping. Say so, and take the
+    // dead keyboard away so the message stops offering a choice it can't take.
+    await self._answerCallback({
+      callback_query_id: callbackQuery.id,
+      text: "Esa consulta ya expiró — escribime de nuevo y la retomamos.",
+    });
+    self.log(`telegram[${self.channel.name}] stale ask callback: ${callbackQuery.data}`);
+    await clearKeyboard(self, callbackQuery);
+    return;
+  }
+  // Ack the press — 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.

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

@@ -26,6 +26,7 @@ import * as askFlow from "./ask.js";
 import { telegramAuthorLabel } from "./helpers.js";
 import { handleIncomingPhoto } from "./inbound/photo.js";
 import { handleIncomingAudio } from "./inbound/audio.js";
+import { handleIncomingFile, detectIncomingFile } from "./inbound/file.js";
 import { buildStreamHandler, runTelegramSuperAgent, telegramErrorText, sendFinalReply, runFollowupTurn } from "./reply.js";
 import { t, resolveLang } from "#core/i18n/index.js";
 
@@ -87,16 +88,28 @@ export async function handleUpdate(self, u) {
     // ── Incoming media ────────────────────────────────────────────────────
     // Photo and voice/audio each download + archive the file and rewrite `text`
     // so the rest of the pipeline treats them like a typed message. The handlers
-    // live in ./inbound/ to keep this dispatcher focused on routing. Photos have
-    // no vision yet, so the handler injects an `[image]` marker (never silent);
-    // audio injects its `[audio]` transcript.
+    // live in ./inbound/ to keep this dispatcher focused on routing. Each one
+    // injects a marker so a caption-less attachment is never an empty turn:
+    // photos an `[image]` marker (plus the pixels, as an attachment, for a
+    // multimodal engine), audio its `[audio]` transcript, files a description
+    // with the local path.
+    const attachments = [];
     if (msg.photo && msg.photo.length > 0) {
-      ({ text } = await handleIncomingPhoto(self, { msg, u, author, chat_id, text }));
+      let attachment;
+      ({ text, attachment } = await handleIncomingPhoto(self, { msg, u, author, chat_id, text }));
+      if (attachment) attachments.push(attachment);
     }
     const incomingAudio = msg.voice || msg.audio;
     if (incomingAudio && incomingAudio.file_id) {
       ({ text } = await handleIncomingAudio(self, { msg, u, author, chat_id, text, incomingAudio }));
     }
+    // Documents, video, video notes and GIFs. Without this a file sent with no
+    // caption left `text` empty, the turn was dropped, and the bot answered
+    // nothing at all.
+    const incomingFile = detectIncomingFile(msg);
+    if (incomingFile) {
+      ({ text } = await handleIncomingFile(self, { msg, u, author, chat_id, text, incoming: incomingFile }));
+    }
 
     // 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
@@ -319,6 +332,7 @@ export async function handleUpdate(self, u) {
       try {
         const sa = await runTelegramSuperAgent(self, {
           chat_id,
+          attachments,
           prompt: slashed.handled ? slashed.prompt : text,
           previousMessages,
           target,

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

@@ -0,0 +1,108 @@
+// Inbound Telegram FILES: document, video, video_note, animation.
+//
+// Same shape as ./photo.js and ./audio.js — take the poller (`self`) plus the
+// parsed update, download and archive the file, and return the (rewritten)
+// `text` the rest of the pipeline runs with.
+//
+// Why this exists: dispatch only recognised photo and voice/audio. Every other
+// attachment fell through to `text = msg.caption || ""`, and a file sent with
+// no caption produced an EMPTY text — so the turn was dropped and the bot said
+// nothing at all. A user who sends a file and gets silence cannot tell the
+// difference between "not supported" and "broken".
+//
+// The reply is model-authored, as everywhere else: the marker states what
+// arrived and where it landed, and the agent puts that in its own words. No
+// canned "file received" string.
+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";
+
+/**
+ * The attachment kinds handled here, in the order Telegram nests them. A
+ * `video_note` (the round selfie clip) has no file_name; a `document` usually
+ * does and it is the one worth preserving.
+ */
+const FILE_KINDS = [
+  { key: "document", label: "document", type: "document" },
+  { key: "video", label: "video", type: "video" },
+  { key: "video_note", label: "video note", type: "video" },
+  { key: "animation", label: "animation (GIF)", type: "animation" },
+];
+
+/** The first file-like attachment on a message, or null. */
+export function detectIncomingFile(msg) {
+  for (const kind of FILE_KINDS) {
+    const file = msg?.[kind.key];
+    if (file?.file_id) return { ...kind, file };
+  }
+  return null;
+}
+
+function humanSize(bytes) {
+  const n = Number(bytes);
+  if (!Number.isFinite(n) || n <= 0) return "";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${Math.round(n / 1024)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * @param {object} self  poller instance (uses self.log, self.channel)
+ * @param {object} ctx   { msg, u, author, chat_id, text, incoming }
+ * @returns {Promise<{ text: string }>}
+ */
+export async function handleIncomingFile(self, { msg, u, author, chat_id, text, incoming }) {
+  const { file, label, type } = incoming;
+  const token = resolveBotToken(self.channel);
+  const mediaDir = telegramMediaDir();
+  const declaredName = file.file_name || "";
+
+  let localPath = null;
+  let failure = "";
+  try {
+    localPath = await downloadTelegramFile(token, file.file_id, mediaDir, {
+      preferredName: declaredName,
+    });
+    self.log(`telegram[${self.channel.name}] ${label} saved: ${localPath}`);
+  } catch (e) {
+    failure = e.message;
+    // Telegram refuses getFile over 20 MB for bots; say which failure it was
+    // rather than leaving the agent to guess.
+    self.log(`telegram[${self.channel.name}] ${label} download failed: ${e.message}`);
+  }
+
+  // Archive regardless of download outcome, so the history records the file
+  // even when the fetch failed.
+  appendGlobalMessage({
+    channel: CHANNELS.TELEGRAM,
+    direction: "in",
+    type,
+    actor_id: msg.from?.id ? String(msg.from.id) : author,
+    external_id: String(u.update_id),
+    author,
+    body: text || `[${label}]`,
+    meta: {
+      chat_id,
+      user_id: msg.from?.id || null,
+      message_id: msg.message_id,
+      tg_channel: self.channel.name,
+      local_path: localPath,
+      file_id: file.file_id,
+      file_name: declaredName || null,
+      mime_type: file.mime_type || null,
+      file_size: file.file_size || null,
+      duration: file.duration || null,
+    },
+  });
+
+  const bits = [declaredName || label];
+  const size = humanSize(file.file_size);
+  if (size) bits.push(size);
+  if (file.mime_type) bits.push(file.mime_type);
+  const marker = localPath
+    ? `[${label} received: ${bits.join(", ")} — saved to ${localPath}. You can open it with your file tools.]`
+    : `[${label} received: ${bits.join(", ")} — the download FAILED (${failure || "unknown error"}), so there is no local copy. Say so; files over 20 MB cannot be fetched by a bot.]`;
+
+  return { text: text ? `${marker} ${text}` : marker };
+}

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

@@ -3,12 +3,15 @@
 // 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.
+// Vision: the photo is downloaded, archived, and returned as an `attachment`
+// that dispatch threads onto the turn. A multimodal engine (Gemini) receives it
+// as real image content; engines without vision ignore it and still get the
+// `[image]` marker, which names the local path so the agent can reach the file
+// with its tools. The marker also guarantees a no-caption photo never produces
+// an empty turn — the reply is always model-authored, never canned. Mirrors the
+// `[audio]` marker convention.
+import fs from "node:fs";
+import path from "node:path";
 import { appendGlobalMessage } from "#core/stores/messages.js";
 import { CHANNELS } from "#core/constants/channels.js";
 import { resolveBotToken, telegramMediaDir } from "../helpers.js";
@@ -55,9 +58,37 @@ export async function handleIncomingPhoto(self, { msg, u, author, chat_id, text
     },
   });
 
-  // 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 };
+  // Hand the pixels to the turn. A multimodal engine (Gemini) renders them as
+  // an inlineData part; the others ignore the field and still have the marker
+  // and the path, so nothing regresses for them.
+  let attachment = null;
+  if (localPath) {
+    try {
+      attachment = {
+        kind: "image",
+        mime: mimeFromPath(localPath),
+        data: fs.readFileSync(localPath).toString("base64"),
+        path: localPath,
+      };
+    } catch (e) {
+      self.log(`telegram[${self.channel.name}] photo read-back failed: ${e.message}`);
+    }
+  }
+
+  // Guard: never go silent. The marker states what arrived and where it is,
+  // and stays neutral about visibility — a vision model can describe the image
+  // it was given, and one without it still has the path and its file tools.
+  const marker = localPath
+    ? `[image attached — saved to ${localPath}]`
+    : "[image attached — the download failed, there is no local copy]";
+  return { text: text ? `${marker} ${text}` : marker, attachment };
+}
+
+function mimeFromPath(p) {
+  const ext = path.extname(p).toLowerCase();
+  if (ext === ".png") return "image/png";
+  if (ext === ".webp") return "image/webp";
+  if (ext === ".gif") return "image/gif";
+  if (ext === ".heic") return "image/heic";
+  return "image/jpeg";
 }

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

@@ -142,14 +142,42 @@ export async function sendAudio(token, chatId, audio, { caption, title, performe
  * Download a file from Telegram servers.
  * Returns the local file path where it was saved.
  */
-export async function downloadTelegramFile(token, fileId, destDir) {
+/**
+ * Keep a user-supplied filename usable as a leaf name: no directory escape, no
+ * separators, no leading dot, bounded length. Returns "" when nothing usable
+ * survives, so callers fall back to the generated name.
+ */
+export function safeFileBase(name) {
+  const base = path.basename(String(name || "")).replace(/\.[^.]*$/, "");
+  const cleaned = base
+    .replace(/[/\\]/g, "")
+    .replace(/[^\p{L}\p{N}._ -]/gu, "")
+    .replace(/\s+/g, " ")
+    .replace(/^[.\s]+/, "")
+    .trim()
+    .slice(0, 60);
+  return cleaned;
+}
+
+/**
+ * Download a file by file_id into destDir. Returns the absolute local path.
+ *
+ * `preferredName` (a document's own `file_name`) is honoured so the archive is
+ * browsable and the agent can tell the user "I saved informe.pdf" rather than
+ * a generated id. It is sanitised and suffixed with part of the file_id, so a
+ * second "informe.pdf" never overwrites the first.
+ */
+export async function downloadTelegramFile(token, fileId, destDir, { preferredName } = {}) {
   // Step 1: get file path from Telegram
   const infoRes = await fetch(`${API_BASE}/bot${token}/getFile?file_id=${fileId}`);
   const infoJson = await infoRes.json();
   if (!infoJson.ok) throw new Error(`getFile failed: ${infoJson.description}`);
   const filePath = infoJson.result.file_path; // e.g. "photos/file_123.jpg"
-  const ext = path.extname(filePath) || ".jpg";
-  const fileName = `tg_${fileId.slice(-8)}_${Date.now()}${ext}`;
+  const ext = path.extname(preferredName || "") || path.extname(filePath) || ".jpg";
+  const base = safeFileBase(preferredName);
+  const fileName = base
+    ? `${base}-${fileId.slice(-6)}${ext}`
+    : `tg_${fileId.slice(-8)}_${Date.now()}${ext}`;
   const localPath = path.join(destDir, fileName);
 
   // Step 2: download

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

@@ -111,6 +111,7 @@ export function buildStreamHandler(self, { chat_id, update_id, agentDisplay }) {
 export function runTelegramSuperAgent(self, {
   chat_id, prompt, previousMessages, target, author, authorId, relationshipBlock,
   allowedTools, contextNote, signal, onEvent, backgroundResultSink = null,
+  attachments = [],
 }) {
   const confirmAdapter = createTelegramConfirmAdapter({
     token: resolveBotToken(self.channel),
@@ -126,6 +127,7 @@ export function runTelegramSuperAgent(self, {
     registries: self.registries,
     prompt,
     previousMessages,
+    attachments,
     channel: CHANNELS.TELEGRAM,
     relationshipBlock,
     allowedTools,

package/src/core/engines/gemini.js

@@ -207,9 +207,14 @@ function toGeminiContents(messages, { model = "", config = {} } = {}) {
       const name = m.name || m.tool_name || "tool";
       const id = m.tool_call_id || m.id;
       if (id && degraded.has(id)) {
+        // The call this answers was dropped, so it cannot be a functionResponse
+        // (Gemini rejects a response to a call it cannot see). Carry the result
+        // as an observation on the user side. Phrased as a plain report, never
+        // as call syntax — anything that looks like a callable format in the
+        // history gets imitated instead of executed.
         out.push({
           role: "user",
-          parts: [{ text: `[tool result: ${name}] ${asText(m.content)}` }],
+          parts: [{ text: `Resultado de ${name}: ${asText(m.content)}` }],
         });
         continue;
       }
@@ -262,25 +267,38 @@ function toGeminiContents(messages, { model = "", config = {} } = {}) {
         const sig = callSignatureOf(tc);
         if (requireSignatures && !turnHasSignature) {
           // Nothing to replay: sending this as a functionCall is a guaranteed
-          // 400. Narrate it instead so the model keeps the context without the
-          // API rejecting the turn.
+          // 400. DROP the call from the model turn — never transcribe it into
+          // text. A model turn that reads "[tool call: run_shell] {...}" is a
+          // worked example of writing calls as prose, and the model copies it:
+          // it stops emitting functionCall parts, the loop sees no tool_calls,
+          // and the transcript is delivered to the user as the final answer.
+          // The call itself is not what the model needs to continue — the
+          // RESULT is, and that still arrives (see the tool branch above).
           if (tc.id) degraded.add(tc.id);
-          parts.push({ text: `[tool call: ${name}] ${JSON.stringify(callArgsOf(tc))}` });
           continue;
         }
         const part = { functionCall: { name, args: callArgsOf(tc) } };
         if (sig) part.thoughtSignature = sig;
         parts.push(part);
       }
-      if (parts.length === 0) parts.push({ text: "" });
+      // Every call was dropped and the turn said nothing else: emit no turn at
+      // all rather than an empty model message.
+      if (parts.length === 0) continue;
       out.push({ role: "model", parts });
       continue;
     }
 
-    out.push({
-      role: m.role === "assistant" ? "model" : "user",
-      parts: [{ text: asText(m.content) }],
-    });
+    // A plain turn. A user turn may carry images (Telegram photos, etc.);
+    // Gemini takes them as inlineData parts beside the text. Non-multimodal
+    // engines ignore the field entirely, so carrying it costs them nothing.
+    const parts = [{ text: asText(m.content) }];
+    if (m.role !== "assistant" && Array.isArray(m.images)) {
+      for (const img of m.images) {
+        if (!img?.data || !img?.mime) continue;
+        parts.push({ inlineData: { mimeType: img.mime, data: img.data } });
+      }
+    }
+    out.push({ role: m.role === "assistant" ? "model" : "user", parts });
   }
   return out;
 }

package/src/core/stores/messages.js

@@ -358,7 +358,12 @@ function sanitizeAssistantForContext(content) {
   ];
   for (const re of FACTUAL_PATTERNS) {
     if (re.test(content)) {
-      return "(I answered with data here. Re-call the tool to get the current values — do not paraphrase from memory.)";
+      // Third person, and visibly an annotation ABOUT the turn rather than the
+      // turn itself. Written in the first person ("I answered with data here…")
+      // this read as something the assistant had said, and after a few of them
+      // in a row the model copied the sentence and sent it to the user as its
+      // reply. History the model can mistake for its own voice gets imitated.
+      return "[omitted: this turn contained data that may be stale — call the tool again instead of repeating it]";
     }
   }
   // Otherwise it's conversational small-talk; keep up to 200 chars.