@agentprojectcontext/apx 1.79.0 → 1.80.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.79.0",
+  "version": "1.80.1",
   "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/handlers/remember-routine.js

@@ -0,0 +1,79 @@
+import { appendRoutineMemory } from "#core/stores/routine-memory.js";
+
+/**
+ * A routine writing to its OWN memory.
+ *
+ * WHY THIS TOOL EXISTS. Routine memory is a file, and until now the only way to
+ * write it was `write_file` — which is gated as dangerous, correctly, because it
+ * can write anywhere. In a routine there is nobody to confirm anything, so
+ * `requirePermission` threw "Action requires user confirmation", the model
+ * treated it as a dead end, and the evening anchor ended without sending
+ * anything. The run still reported `ok`, so the only symptom was silence.
+ *
+ * An agent recording what it learned is not a dangerous act. It is the most
+ * ordinary thing it does, and it must not need a human standing by.
+ *
+ * WHY IT IS SAFE UNGATED: there is no path argument. The destination comes from
+ * the running routine's own context (channelMeta.routineId + the project's
+ * storage), so this tool cannot write anywhere else however it is called. That
+ * is the whole difference between this and write_file, and it is the reason the
+ * permission is unnecessary rather than merely inconvenient.
+ */
+export default {
+  name: "remember_routine",
+  schema: {
+    type: "function",
+    function: {
+      name: "remember_routine",
+      description:
+        "Save a durable note to THIS routine's own memory — what you learned about how the " +
+        "owner works, what turned out to be worth mentioning, what turned out to be noise. " +
+        "Only available while a routine is running. Use this instead of write_file: it is the " +
+        "routine's own notebook and needs no permission. For facts about the owner that matter " +
+        "on every channel, use `remember` instead.",
+      parameters: {
+        type: "object",
+        required: ["note"],
+        properties: {
+          note: {
+            type: "string",
+            description: "One line. A judgement that will change what you do next time, not a log of what happened.",
+          },
+        },
+      },
+    },
+  },
+  makeHandler: ({ channel, channelMeta, projects }) => async ({ note } = {}) => {
+    const text = String(note || "").trim();
+    if (!text) return { error: "note required" };
+
+    const routineId = channelMeta?.routineId;
+    const routineName = channelMeta?.routineName || "";
+    if (!routineId) {
+      // Said plainly so the model reaches for `remember` instead of retrying.
+      return {
+        error:
+          "remember_routine only works inside a running routine. " +
+          "Use `remember` for a durable fact about the owner.",
+        channel: channel || null,
+      };
+    }
+
+    // The routine's project storage, never a model-supplied path.
+    const projectPath = channelMeta?.projectPath || "";
+    let storagePath = "";
+    for (const entry of projects?.list?.() || []) {
+      if (projectPath && entry.path !== projectPath) continue;
+      storagePath = projects.get(entry.id)?.storagePath || "";
+      if (storagePath) break;
+    }
+    if (!storagePath) return { error: "could not resolve this routine's storage" };
+
+    try {
+      const r = appendRoutineMemory(storagePath, routineId, text, { routineName });
+      return { saved: true, routine: routineName || routineId, note: text, path: r?.path };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/names.js

@@ -42,6 +42,7 @@ export const TOOLS = Object.freeze({
   LIST_TASKS:          "list_tasks",
   CREATE_TASK:         "create_task",
   RECORD_COMMITMENT:   "record_commitment",
+  REMEMBER_ROUTINE:    "remember_routine",
   LIST_COMMITMENTS:    "list_commitments",
 
   // Interaction
@@ -139,6 +140,7 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.CREATE_TASK,
   TOOLS.RECORD_COMMITMENT,
   TOOLS.LIST_COMMITMENTS,
+  TOOLS.REMEMBER_ROUTINE,
   TOOLS.ASK_QUESTIONS,
   TOOLS.SEARCH_SESSIONS,
   TOOLS.TRANSCRIBE_AUDIO,
@@ -228,6 +230,7 @@ export const SIDE_EFFECT_TOOLS = new Set([
   TOOLS.SEND_TELEGRAM,
   TOOLS.CREATE_TASK,
   TOOLS.RECORD_COMMITMENT,
+  TOOLS.REMEMBER_ROUTINE,
   TOOLS.WRITE_FILE,
   TOOLS.EDIT_FILE,
   TOOLS.RUN_SHELL,

package/src/core/agent/tools/registry.js

@@ -30,6 +30,7 @@ import askQuestions from "./handlers/ask-questions.js";
 import createTask from "./handlers/create-task.js";
 import recordCommitment from "./handlers/record-commitment.js";
 import listCommitments from "./handlers/list-commitments.js";
+import rememberRoutine from "./handlers/remember-routine.js";
 import listTasks from "./handlers/list-tasks.js";
 import discoverTools from "./handlers/discover-tools.js";
 import gitStatus from "./handlers/git-status.js";
@@ -85,6 +86,7 @@ const NATIVE_TOOLS = [
   listTasks,
   recordCommitment,
   listCommitments,
+  rememberRoutine,
   discoverTools,
   gitStatus,
   gitDiff,
@@ -143,6 +145,10 @@ export const BASE_TOOL_NAMES = new Set([
   TOOLS.READ_AGENT_MEMORY,
   TOOLS.READ_SELF_MEMORY,
   TOOLS.REMEMBER,
+  // NOT here: remember_routine. It only works inside a routine, and the routine
+  // channel is in FULL_CHANNELS — it already receives the whole registry. Adding
+  // it to the base set would spend tokens on every Telegram and desktop turn for
+  // a tool that returns an error on those channels.
   TOOLS.SET_IDENTITY,
   // Sessions + messages (self-recall + channel history).
   TOOLS.SEARCH_SESSIONS,

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/profiles/bundled/secretary/routines/day-close.json

@@ -5,7 +5,7 @@
   "permission_mode": "permiso",
   "enabled_by_default": true,
   "spec": {
-    "prompt": "Close the day. Review what moved today, what is still stuck, and what carries over to tomorrow, across every registered project. Call list_tasks and list_commitments ONCE each, with no project argument — both search every project in a single call. Do not loop over projects. If a commitment came due today, ask whether it was kept — do not mark it yourself.\n\nSend ONE short message covering those, keeping promises to people separate from ordinary tasks. Note anything that has gone quiet longer than the staleness threshold. If the day was quiet, say that plainly in a line or two.\n\nThen record in your routine memory anything durable you learned about how this person works.\n\nDELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. Send exactly one message, then stop; do not end the turn by asking whether to keep looking.",
+    "prompt": "Close the day. Review what moved today, what is still stuck, and what carries over to tomorrow, across every registered project. Call list_tasks and list_commitments ONCE each, with no project argument — both search every project in a single call. Do not loop over projects. If a commitment came due today, ask whether it was kept — do not mark it yourself.\n\nSend ONE short message covering those, keeping promises to people separate from ordinary tasks. Note anything that has gone quiet longer than the staleness threshold. If the day was quiet, say that plainly in a line or two.\n\nThen record anything durable you learned about how this person works with remember_routine — one line. Never write_file for this: a scheduled run has nobody to approve it and the whole turn dies there.\n\nDELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. Send exactly one message, then stop; do not end the turn by asking whether to keep looking.",
     "anchor": true
   },
   "allowed_tools": [

package/src/core/profiles/bundled/secretary/routines/watch.json

@@ -5,7 +5,7 @@
   "permission_mode": "permiso",
   "enabled_by_default": true,
   "spec": {
-    "prompt": "You are watching {{owner_name}}'s projects between the anchors. The signals below were detected deterministically — they are facts, already gathered; you do not need to look them up again.\n\nDecide whether any of it is worth interrupting for RIGHT NOW rather than waiting for the next anchor. Staying quiet is the normal outcome and costs you nothing. A message that could have waited until tomorrow morning costs you the next one, because that is the one they will not open.\n\nIf you do speak: send ONE line naming the single most important thing and what you suggest doing about it, with send_telegram. DELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. If you decide to stay quiet, just say so in your reply and call nothing."
+    "prompt": "You are watching {{owner_name}}'s projects between the anchors. The signals below were detected deterministically — they are facts, already gathered; you do not need to look them up again.\n\nDecide whether any of it is worth interrupting for RIGHT NOW rather than waiting for the next anchor. Staying quiet is the normal outcome and costs you nothing. A message that could have waited until tomorrow morning costs you the next one, because that is the one they will not open.\n\nIf you do speak: send ONE line naming the single most important thing and what you suggest doing about it, with send_telegram. DELIVERY: send it with send_telegram. A routine's own output is only written to the log — if you do not call the tool, {{owner_name}} receives nothing at all. If you decide to stay quiet, just say so in your reply and call nothing.\n\nWhichever you choose, note what you learned with remember_routine — especially when you stayed quiet, because next time you need to know this kind of signal was not worth it."
   },
   "allowed_tools": [
     "send_telegram"

package/src/core/routines/runner.js

@@ -145,6 +145,12 @@ async function handleSuperAgent(ctx, routine, extraChannelMeta = {}) {
     suppressTools: suppressTools.length > 0 ? suppressTools : null,
   });
 
+  // A tool that needed a human in a run with no human is a DEAD END, not a
+  // hiccup: nobody is ever going to confirm it. Reporting the run as "ok"
+  // meant the only symptom was silence — the evening anchor produced nothing
+  // and it took twenty-one shell commands to work out why. Name it.
+  const blocked = blockedForPermission(result.trace);
+
   project.logMessage({
     channel: CHANNELS.ROUTINE,
     direction: "out",
@@ -161,9 +167,37 @@ async function handleSuperAgent(ctx, routine, extraChannelMeta = {}) {
       usage: result.usage,
     },
   });
+  if (blocked.length) {
+    return {
+      status: "error",
+      error:
+        `blocked waiting for a confirmation nobody can give: ${blocked.join(", ")}. ` +
+        `A scheduled run has no one to approve a dangerous tool — either allow it on ` +
+        `this routine (allowed_tools) or use a tool that does not need approval.`,
+      blocked_tools: blocked,
+      reply: result.text,
+      trace: result.trace,
+    };
+  }
   return { status: "ok", reply: result.text, trace: result.trace };
 }
 
+/**
+ * Tools whose result was "Action requires user confirmation" — the message
+ * createPermissionGuard throws when there is no confirmation channel wired
+ * (tools/helpers.js). Distinct from a tool that merely failed.
+ */
+export function blockedForPermission(trace) {
+  const names = new Set();
+  for (const item of Array.isArray(trace) ? trace : []) {
+    const err = item?.result?.error;
+    if (typeof err === "string" && /requires user confirmation/i.test(err)) {
+      names.add(item.tool || "unknown");
+    }
+  }
+  return [...names];
+}
+
 async function handleTelegram(ctx, routine) {
   const { plugins } = ctx;
   const tg = plugins?.get("telegram");

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.