npm - @agentprojectcontext/apx - Versions diffs - 1.78.0 → 1.80.0 - Mend

@agentprojectcontext/apx 1.78.0 → 1.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (97) hide show

package/package.json +1 -1
package/src/core/agent/run-agent.js +46 -6
package/src/core/agent/super-agent.js +3 -0
package/src/core/agent/tool-summary.js +65 -0
package/src/core/agent/tools/handlers/list-commitments.js +80 -0
package/src/core/agent/tools/handlers/list-tasks.js +66 -27
package/src/core/agent/tools/handlers/record-commitment.js +68 -0
package/src/core/agent/tools/handlers/send-telegram.js +68 -2
package/src/core/agent/tools/names.js +6 -0
package/src/core/agent/tools/registry.js +9 -0
package/src/core/agent/tools/tool-call-parser.js +123 -6
package/src/core/channels/telegram/ask-callbacks.js +121 -6
package/src/core/channels/telegram/dispatch.js +21 -4
package/src/core/channels/telegram/inbound/file.js +108 -0
package/src/core/channels/telegram/inbound/photo.js +42 -11
package/src/core/channels/telegram/media.js +31 -3
package/src/core/channels/telegram/reply.js +32 -5
package/src/core/config/paths.js +3 -0
package/src/core/config/redact.js +22 -0
package/src/core/daemon/service.js +238 -0
package/src/core/engines/gemini.js +343 -63
package/src/core/engines/openai-compatible.js +21 -2
package/src/core/memory/consolidate.js +225 -0
package/src/core/nudge/index.js +192 -0
package/src/core/nudge/policy.js +143 -0
package/src/core/nudge/store.js +141 -0
package/src/core/profiles/bundled/secretary/PROFILE.md +8 -9
package/src/core/profiles/bundled/secretary/config.schema.json +33 -3
package/src/core/profiles/bundled/secretary/routines/day-close.json +7 -3
package/src/core/profiles/bundled/secretary/routines/day-open.json +7 -3
package/src/core/profiles/bundled/secretary/routines/watch.json +13 -0
package/src/core/routines/runner.js +102 -3
package/src/core/routines/signals.js +270 -0
package/src/core/stores/commitments.js +331 -0
package/src/core/stores/messages.js +10 -1
package/src/core/stores/routines.js +17 -3
package/src/core/util/thinking.js +51 -0
package/src/host/daemon/api/commitments.js +135 -0
package/src/host/daemon/api/nudges.js +112 -0
package/src/host/daemon/api/routines.js +24 -0
package/src/host/daemon/api/self-memory.js +50 -0
package/src/host/daemon/api/telegram.js +42 -4
package/src/host/daemon/api/voice.js +3 -1
package/src/host/daemon/api.js +6 -0
package/src/host/daemon/callback-reconciler.js +16 -0
package/src/host/daemon/plugins/desktop/index.js +7 -1
package/src/host/daemon/plugins/telegram/index.js +7 -2
package/src/host/daemon/wakeup.js +17 -3
package/src/interfaces/cli/commands/commitment.js +154 -0
package/src/interfaces/cli/commands/daemon.js +57 -0
package/src/interfaces/cli/commands/memory.js +73 -0
package/src/interfaces/cli/commands/nudge.js +130 -0
package/src/interfaces/cli/help/index.js +2 -2
package/src/interfaces/cli/routes/commitment.js +19 -0
package/src/interfaces/cli/routes/daemon.js +7 -1
package/src/interfaces/cli/routes/index.js +4 -0
package/src/interfaces/cli/routes/memory.js +10 -2
package/src/interfaces/cli/routes/nudge.js +17 -0
package/src/interfaces/web/dist/assets/index-CvEoGtTf.js +849 -0
package/src/interfaces/web/dist/assets/index-CvEoGtTf.js.map +1 -0
package/src/interfaces/web/dist/assets/index-DzBBXFaO.css +1 -0
package/src/interfaces/web/dist/index.html +2 -2
package/src/interfaces/web/package-lock.json +11 -10
package/src/interfaces/web/src/components/Section.tsx +18 -3
package/src/interfaces/web/src/components/chat/MessageBubble.tsx +13 -0
package/src/interfaces/web/src/components/cron/CronPicker.tsx +196 -0
package/src/interfaces/web/src/components/inbox/InboxList.tsx +145 -0
package/src/interfaces/web/src/components/memory/MemoryBrowser.tsx +34 -4
package/src/interfaces/web/src/components/routines/RoutineDetail.tsx +16 -4
package/src/interfaces/web/src/components/routines/RoutineEditor.tsx +12 -2
package/src/interfaces/web/src/components/routines/shared.ts +14 -5
package/src/interfaces/web/src/components/settings/NudgePanel.tsx +183 -0
package/src/interfaces/web/src/components/settings/ProfilePanel.tsx +36 -12
package/src/interfaces/web/src/components/ui/filter-chips.tsx +47 -0
package/src/interfaces/web/src/components/ui.tsx +1 -0
package/src/interfaces/web/src/constants/index.ts +1 -0
package/src/interfaces/web/src/hooks/useChat.ts +5 -1
package/src/interfaces/web/src/hooks/useNudges.ts +38 -0
package/src/interfaces/web/src/i18n/en.ts +127 -0
package/src/interfaces/web/src/i18n/es.ts +127 -0
package/src/interfaces/web/src/lib/api/commitments.ts +57 -0
package/src/interfaces/web/src/lib/api/notebook.ts +23 -0
package/src/interfaces/web/src/lib/api/nudges.ts +53 -0
package/src/interfaces/web/src/lib/cron.ts +196 -0
package/src/interfaces/web/src/lib/when.ts +32 -0
package/src/interfaces/web/src/screens/InboxScreen.tsx +107 -77
package/src/interfaces/web/src/screens/ProjectScreen.tsx +5 -2
package/src/interfaces/web/src/screens/SettingsScreen.tsx +17 -3
package/src/interfaces/web/src/screens/base/CommitmentsTab.tsx +239 -0
package/src/interfaces/web/src/screens/base/GlobalTasksTab.tsx +102 -19
package/src/interfaces/web/src/screens/base/LogsTab.tsx +15 -0
package/src/interfaces/web/src/screens/project/ChatTab.tsx +21 -3
package/src/interfaces/web/src/screens/project/RoutinesTab.tsx +13 -11
package/src/interfaces/web/src/types/daemon.ts +10 -1
package/src/interfaces/web/dist/assets/index-CBR_-QyA.js +0 -824
package/src/interfaces/web/dist/assets/index-CBR_-QyA.js.map +0 -1
package/src/interfaces/web/dist/assets/index-D_EJEA1n.css +0 -1

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

@@ -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>
@@ -162,7 +206,70 @@ function extractLlamaDottedFunctionCalls(text) {
 // trivial wrappers (<tool_call>, ```tool_use, _icall(), etc.) that often sit
 // around them. Used to clean up final answers that the model emitted with
 // leftover textual tool-call gunk.
-export function cleanTextOfPseudoToolCalls(text) {
+/**
+ * The bare `tool_name({...json...})` form.
+ *
+ * WHERE THIS COMES FROM, and why it is not hypothetical: APX renders past tool
+ * results into model context as `[tool result: <name>] <body>`
+ * (stores/messages.js). A weaker model reads that pattern in its own history
+ * and imitates it in PROSE — gemini-3.5-flash produced
+ *
+ *   [tool result: create_task] create_task({"project":"apx","title":"…"})
+ *
+ * and then told the user the task was filed. It was not. That is the worst
+ * failure mode available: a confident false confirmation, with nothing on disk.
+ *
+ * GATED ON KNOWN TOOL NAMES, deliberately. The other two passes key off
+ * unambiguous markers (`<function.` or a `{name, arguments}` pair); a bare
+ * `foo({...})` is ordinary prose about code. Without the allow-list, a model
+ * EXPLAINING `create_task({...})` in an answer would silently create a task.
+ * So: no known names, no matches.
+ *
+ * @param {string} text
+ * @param {Iterable<string>} knownNames  tool names callable on this turn
+ */
+export function extractBareFunctionCalls(text, knownNames) {
+  const allowed = new Set(knownNames || []);
+  if (!text || typeof text !== "string" || allowed.size === 0) return [];
+  const out = [];
+  // `name(` where name is a plausible identifier. The `[tool result: x] `
+  // prefix the model copies is left for the cleaner to strip.
+  const re = /(^|[^A-Za-z0-9_.])([a-z][a-z0-9_]{2,63})\s*\(\s*(?=\{)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[2];
+    if (!allowed.has(name)) continue;
+    // The '{' the regex already looked ahead to.
+    const i = text.indexOf("{", m.index + m[0].length - 1);
+    if (i < 0) continue;
+    const balanced = readBalancedJson(text, i);
+    if (!balanced.ok) continue;
+    let args;
+    try {
+      args = JSON.parse(text.slice(i, balanced.end));
+    } catch {
+      continue;
+    }
+    if (!args || typeof args !== "object" || Array.isArray(args)) continue;
+    // Include the closing paren in the raw span when it is there, so the
+    // cleaner removes the whole call rather than leaving a dangling `)`.
+    let end = balanced.end;
+    const after = text.slice(end).match(/^\s*\)/);
+    if (after) end += after[0].length;
+    const rawStart = m.index + (m[1] ? m[1].length : 0);
+    out.push({
+      id: nextId(),
+      type: "function",
+      function: { name, arguments: JSON.stringify(args) },
+      _raw: text.slice(rawStart, end),
+    });
+  }
+  return out;
+}
+export function cleanTextOfPseudoToolCalls(text, knownNames) {
   if (!text || typeof text !== "string") return text;
   // Strip explicit XML-like fences first
@@ -179,6 +286,16 @@ export function cleanTextOfPseudoToolCalls(text) {
   for (const call of extractPseudoToolCalls(out)) {
     if (call._raw) out = out.replace(call._raw, "");
   }
+  // The bare `name({...})` form, and the `[tool result: name]` prefix the
+  // model copies out of its own transcript.
+  for (const call of extractBareFunctionCalls(out, 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 CHANGED Viewed

@@ -12,11 +12,35 @@ import { getConfirmationStore as getConfirmStore } from "#core/confirmation/pend
 import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "#core/stores/messages.js";
 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 || "";
@@ -24,15 +48,90 @@ export async function handleCallbackQuery(self, callbackQuery) {
     await handleAskCallback(self, callbackQuery);
     return;
   }
+  if (data.startsWith("apx:nudge:")) {
+    await handleNudgeCallback(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}`);
+  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 */ }
+}
+/**
+ * "Was that worth interrupting you for?" — the feedback loop on proactive
+ * pushes (core/nudge). One tap, no reply, and the keyboard disappears so the
+ * chat does not accumulate stale buttons. Never re-enters the super-agent: an
+ * opinion about a message is not a new turn to answer.
+ */
+export async function handleNudgeCallback(self, callbackQuery) {
+  const chatId = callbackQuery.message?.chat?.id;
+  const result = applyNudgeCallback(callbackQuery.data || "");
+  await self._answerCallback({
+    callback_query_id: callbackQuery.id,
+    text: result?.ack || "",
+  });
+  if (!result || !chatId) return;
+  try {
+    await self._editKeyboard({
+      chat_id: chatId,
+      message_id: callbackQuery.message?.message_id,
+      reply_markup: { inline_keyboard: [] },
+    });
+  } catch { /* best-effort */ }
+  self.log(
+    `telegram[${self.channel.name}] nudge feedback: ${result.entry?.kind || "?"} → ` +
+    `${result.entry?.feedback?.useful ? "useful" : "noise"}`
+  );
 }
 /**
@@ -79,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.
@@ -182,6 +294,7 @@ export async function runResumedTurn(self, ctx) {
   let replyAuthor;
   let saUsage = null;
   let saModel = null;
+  let saTrace = null;
   try {
     const sa = await runTelegramSuperAgent(self, {
       chat_id,
@@ -218,6 +331,7 @@ export async function runResumedTurn(self, ctx) {
     replyAuthor = sa.name || agentDisplay;
     saUsage = sa.usage;
     saModel = sa.model || state.model || null;
+    saTrace = sa.trace || null;
   } catch (e) {
     self.log(`telegram[${self.channel.name}] ask resume failed: ${e.message}`);
     replyText = telegramErrorText(self, e);
@@ -235,6 +349,7 @@ export async function runResumedTurn(self, ctx) {
     replyKind: "superagent",
     saUsage,
     saModel,
+    saTrace,
     streamedCount: state.streamedCount,
     lastStreamedText: state.lastStreamedText,
     agentDisplay,

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

@@ -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
@@ -228,6 +241,7 @@ export async function handleUpdate(self, u) {
     let replyKind = "superagent";             // actor_kind: superagent | agent
     let replyModel = null;                    // model that actually produced the reply
     let replyUsage = null;                    // token accounting for this turn
+    let replyTrace = null;                    // what the turn actually did (summarised on the message)
     const projectCfg = target.config || self.globalConfig;
     // Display name for the super-agent persona on this channel (from identity.json).
     const agentDisplay = resolveAgentName(self.globalConfig);
@@ -318,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,
@@ -335,6 +350,7 @@ export async function handleUpdate(self, u) {
         replyActorId = SUPERAGENT_ACTOR_ID;
         replyKind = "superagent";
         replyUsage = sa.usage;
+        replyTrace = sa.trace || null;
         replyModel = sa.model || state.model || null;
         // ── ask_questions integration ────────────────────────────────────
@@ -397,6 +413,7 @@ export async function handleUpdate(self, u) {
       replyKind,
       saUsage: replyUsage,
       saModel: replyModel,
+      saTrace: replyTrace,
       streamedCount,
       lastStreamedText,
       agentDisplay,

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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