@agentprojectcontext/apx 1.14.0 → 1.14.1

package/package.json

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

package/src/daemon/plugins/telegram.js

@@ -113,6 +113,40 @@ export async function sendVoice(token, chatId, audio, { caption, duration } = {}
  * @param {string} [opts.title]
  * @param {string} [opts.performer]
  */
+/**
+ * Send any file as a Telegram document (PDF, zip, txt, etc).
+ * @param {string} token
+ * @param {string|number} chatId
+ * @param {string|Buffer} document  Path or Buffer of document data
+ * @param {object} [opts]
+ * @param {string} [opts.caption]
+ * @param {string} [opts.filename] override filename for Buffer input
+ * @param {string} [opts.mime_type]
+ */
+export async function sendDocument(token, chatId, document, { caption, filename, mime_type } = {}) {
+  const url = `${API_BASE}/bot${token}/sendDocument`;
+  const form = new FormData();
+  form.append("chat_id", String(chatId));
+  if (caption) form.append("caption", caption);
+
+  // URL string → let Telegram fetch it
+  if (typeof document === "string" && /^https?:\/\//.test(document)) {
+    form.append("document", document);
+  } else {
+    const buf = Buffer.isBuffer(document) ? document : fs.readFileSync(document);
+    const name =
+      filename ||
+      (typeof document === "string" ? path.basename(document) : "document.bin");
+    const blob = new Blob([buf], { type: mime_type || "application/octet-stream" });
+    form.append("document", blob, name);
+  }
+
+  const res = await fetch(url, { method: "POST", body: form });
+  const json = await res.json();
+  if (!json.ok) throw new Error(`sendDocument failed: ${json.description || res.status}`);
+  return json.result;
+}
+
 export async function sendAudio(token, chatId, audio, { caption, title, performer } = {}) {
   const url = `${API_BASE}/bot${token}/sendAudio`;
   const form = new FormData();
@@ -724,6 +758,14 @@ class ChannelPoller {
     return sendVoice(token, target, audio, { caption, duration });
   }
 
+  /** Send a document (PDF, zip, etc) via this channel */
+  async _sendDocument({ chat_id, document, caption, filename, mime_type }) {
+    const token = resolveBotToken(this.channel);
+    if (!token) throw new Error(`channel ${this.channel.name}: no bot_token`);
+    const target = chat_id || resolveChatId(this.channel);
+    return sendDocument(token, target, document, { caption, filename, mime_type });
+  }
+
   /** Send an audio file via this channel */
   async _sendAudio({ chat_id, audio, caption, title, performer }) {
     const token = resolveBotToken(this.channel);
@@ -848,6 +890,29 @@ export default {
         return result;
       },
 
+      /**
+       * Send a document (PDF, zip, txt, generated reports, etc).
+       * document: local file path, Buffer, or public https URL.
+       */
+      async sendDocument({ channel: channelName, chat_id, document, caption, filename, mime_type, author = "apx" }) {
+        const p =
+          (channelName && pollers.find((pp) => pp.channel.name === channelName)) ||
+          pollers.find((pp) => resolveBotToken(pp.channel)) ||
+          null;
+        if (!p) throw new Error("no telegram channel available");
+        const result = await p._sendDocument({ chat_id, document, caption, filename, mime_type });
+        appendGlobalMessage({
+          channel: "telegram",
+          direction: "out",
+          type: "document",
+          actor_id: author,
+          author,
+          body: caption || `[document${filename ? " " + filename : ""}]`,
+          meta: { chat_id: chat_id || resolveChatId(p.channel), tg_channel: p.channel.name, filename, mime_type },
+        });
+        return result;
+      },
+
       /**
        * Send an audio file (MP3/M4A — shown in music player).
        * audio: local file path or Buffer

package/src/daemon/super-agent-tools/tools/send-telegram.js

@@ -1,12 +1,41 @@
 import { confirmedProperty } from "../helpers.js";
 
+function decodeBase64(b64) {
+  const clean = String(b64).replace(/^data:[a-z/-]+;base64,/, "");
+  return Buffer.from(clean, "base64");
+}
+
 function decodePhoto({ photo_base64, photo_path, photo_url }) {
-  if (photo_url)  return String(photo_url);
-  if (photo_path) return String(photo_path);
-  if (photo_base64) {
-    // Strip "data:image/...;base64," prefix if present
-    const clean = String(photo_base64).replace(/^data:image\/[a-z]+;base64,/, "");
-    return Buffer.from(clean, "base64");
+  if (photo_url)    return String(photo_url);
+  if (photo_path)   return String(photo_path);
+  if (photo_base64) return decodeBase64(photo_base64);
+  return null;
+}
+
+function decodeDocument({ document_base64, document_path, document_url }) {
+  if (document_url)    return String(document_url);
+  if (document_path)   return String(document_path);
+  if (document_base64) return decodeBase64(document_base64);
+  return null;
+}
+
+/**
+ * Detect the common LLM mistake of embedding raw base64 in the text field
+ * (often wrapped in markdown image syntax). Telegram does NOT render those —
+ * it just shows the literal characters. Fail fast with a clear hint.
+ */
+function detectBase64InText(text) {
+  if (!text || typeof text !== "string") return null;
+  if (/!\[[^\]]*\]\(data:image\/[a-z]+;base64,/i.test(text)) {
+    return "markdown image with data URI";
+  }
+  if (/data:image\/[a-z]+;base64,/i.test(text)) {
+    return "data URI";
+  }
+  // Long runs of base64-looking chars (>500 contiguous) — almost certainly a
+  // dumped image
+  if (/[A-Za-z0-9+/=]{500,}/.test(text)) {
+    return "raw base64 blob (>500 chars)";
   }
   return null;
 }
@@ -18,28 +47,61 @@ export default {
     function: {
       name: "send_telegram",
       description:
-        "Send a Telegram message via the daemon's Telegram plugin. Text only by default; pass photo_base64 (from browser_screenshot) / photo_path / photo_url to attach an image — the text becomes the caption. Use this AFTER a browser_screenshot when the user asks for a screenshot or visual reply.",
+        "Send a Telegram message via the daemon's Telegram plugin. STRICT rule: to attach an image use the photo_* params; to attach a file use the document_* params — NEVER paste base64 or a data URI inside `text` (Telegram does not render markdown images / data URIs, the recipient sees the literal base64). After browser_screenshot, pass its `base64` field directly to photo_base64 here (not in text). The text field becomes the caption when media is attached.",
       parameters: {
         type: "object",
         properties: {
-          channel:      { type: "string", description: "telegram channel name; omit for default" },
-          chat_id:      { type: "string", description: "destination chat id; omit to use channel default" },
-          text:         { type: "string", description: "message body (becomes the photo caption when a photo_* arg is passed)" },
-          photo_base64: { type: "string", description: "raw base64 PNG/JPG (or 'data:image/...;base64,...' data URI). Pass the `base64` field returned by browser_screenshot here." },
-          photo_path:   { type: "string", description: "absolute filesystem path to an image file" },
-          photo_url:    { type: "string", description: "public https URL of an image" },
-          confirmed:    confirmedProperty("true only after explicit user confirmation for this exact outbound message"),
+          channel: { type: "string", description: "telegram channel name; omit for default" },
+          chat_id: { type: "string", description: "destination chat id; omit to use channel default" },
+          text: {
+            type: "string",
+            description:
+              "Plain-text body (becomes the caption when a photo_* or document_* is attached). MUST NOT contain base64, data URIs, or markdown image syntax like ![](data:...) — use photo_base64 for that.",
+          },
+          // --- image attachments ---
+          photo_base64: {
+            type: "string",
+            description:
+              "raw base64 PNG/JPG (or 'data:image/...;base64,...'). Pass the `base64` field from browser_screenshot directly here.",
+          },
+          photo_path: { type: "string", description: "absolute filesystem path to an image file" },
+          photo_url:  { type: "string", description: "public https URL of an image" },
+          // --- document attachments (PDF, txt, zip, etc) ---
+          document_base64: { type: "string", description: "raw base64 of a file" },
+          document_path:   { type: "string", description: "absolute filesystem path to any file (PDF, txt, zip, .csv...)" },
+          document_url:    { type: "string", description: "public https URL of a file" },
+          filename:        { type: "string", description: "filename to show in Telegram when sending a document (Buffer-style input)" },
+          mime_type:       { type: "string", description: "optional MIME type for the document" },
+          confirmed: confirmedProperty("true only after explicit user confirmation for this exact outbound message"),
         },
         required: ["text"],
       },
     },
   },
-  makeHandler: ({ plugins, requirePermission }) => async ({ channel, chat_id, text, photo_base64, photo_path, photo_url, confirmed = false }) => {
+  makeHandler: ({ plugins, requirePermission }) => async (args = {}) => {
+    const {
+      channel, chat_id, text,
+      photo_base64, photo_path, photo_url,
+      document_base64, document_path, document_url,
+      filename, mime_type,
+      confirmed = false,
+    } = args;
+
     requirePermission("send_telegram", { dangerous: true, confirmed });
     if (!plugins) throw new Error("plugins unavailable");
     const telegram = plugins.get("telegram");
     if (!telegram) throw new Error("telegram plugin not loaded");
 
+    // Defensive: catch the classic mistake of dumping base64 into text.
+    const bad = detectBase64InText(text);
+    if (bad) {
+      throw new Error(
+        `send_telegram: refusing to send — text appears to contain ${bad}. ` +
+        `Telegram does not render data URIs or markdown images. ` +
+        `Pass the base64 in photo_base64 (NOT text). Set text to a short caption like "Captura de localhost:8801".`
+      );
+    }
+
     const photo = decodePhoto({ photo_base64, photo_path, photo_url });
     if (photo) {
       const result = await telegram.sendPhoto({
@@ -48,6 +110,14 @@ export default {
       return { ok: true, kind: "photo", message_id: result.message_id };
     }
 
+    const document = decodeDocument({ document_base64, document_path, document_url });
+    if (document) {
+      const result = await telegram.sendDocument({
+        channel, chat_id, document, caption: text, filename, mime_type, author: "apx",
+      });
+      return { ok: true, kind: "document", message_id: result.message_id, filename };
+    }
+
     const result = await telegram.send({ channel, chat_id, text, author: "apx" });
     return { ok: true, kind: "text", message_id: result.message_id };
   },

package/src/daemon/super-agent.js

@@ -65,7 +65,8 @@ HARD RULES (do not deviate):
 18. **NO EMPTY RESPONSES**: Never respond with only text when you have tools available and the user is asking you to DO something. Call the tool FIRST, then explain. Never say "I'll do X" without immediately calling the tool. Empty acknowledgments ("ok", "entendido", "dame un minuto", "voy", "checking", "stand by") without a tool call are invalid responses — they will be re-prompted and waste a turn.
 19. **CWD RULE**: When the channel context includes a "CWD: <path>" line, that is the user's current working directory. References to "este directorio", "este proyecto", "esta carpeta", "acá", "aquí", "this directory", "this project", "current dir/folder" all mean that exact CWD path. Use it as the path argument directly — DO NOT ask the user "what's the path?" when CWD is already given. Example: if user says "agregá este proyecto a la lista", call add_project({path: <CWD>}) immediately.
 20. **NO MANUAL SCAFFOLDING**: To register or scaffold a project, ALWAYS use add_project — it auto-creates AGENTS.md and .apc/project.json when missing (one call, atomic). NEVER write AGENTS.md, .apc/project.json, or any APC scaffold file by hand via run_shell / write_file / shell pipes. The schema must come from the official initApf scaffold, not improvised. If add_project errors, report the error to the user — don't try to work around it with shell hacks. Same for any other APC-managed file (.apc/agents/*, .apc/skills/*, etc.) — use the dedicated tool, never raw filesystem writes.
-21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.`;
+21. **SKILLS — ON DEMAND**: The "# Available skills" section below lists every skill available to you (slug + description, NO body). When the user asks about specific APX/APC commands, project structure, agent runtimes, or anything where exact syntax or detailed behavior matches a skill description (in ANY language — match semantically, not by keyword), call load_skill({slug}) to fetch the full markdown body. If a CWD is in the contextNote, pass it as project_path so project-scoped skills resolve. If the user explicitly asks "what skills do you have?", you can either read the catalog below directly OR call list_skills to get a fresh enumeration. Do NOT load skills for trivial / unrelated questions — that wastes tokens. Don't guess CLI syntax when a skill can tell you; load it.
+22. **NEVER PASTE BASE64 OR DATA URIs IN MESSAGE TEXT**: When you need to send an image, audio, or file via Telegram (or any channel), you MUST pass it via the dedicated parameter — NEVER embed it in the text field. Concretely: after browser_screenshot returns its base64 field, call send_telegram({text: "<short caption>", photo_base64: "<that base64>"}). Do NOT write text like 'Aquí está: ![screenshot](data:image/png;base64,...)' — Telegram (and most chat clients) do NOT render data URIs or markdown images; the user sees thousands of garbage characters. Same for files: use document_path / document_base64 / document_url, NOT the text field. The text field is exclusively for human-readable prose (and becomes the caption when media is attached). If unsure, save the image to /tmp/screenshot-<ts>.png first (browser_screenshot supports save_to_tmp=true and returns a path field) and pass that path to send_telegram via photo_path — never inline the bytes in text.`;
 
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i

package/src/daemon/tools/browser.js

@@ -197,7 +197,7 @@ export async function browser_navigate({ url, launch_options, allow_dangerous }
   };
 }
 
-export async function browser_screenshot({ selector, full_page = false, width, height, encoded = false } = {}) {
+export async function browser_screenshot({ selector, full_page = false, width, height, encoded = false, save_path, save_to_tmp = false } = {}) {
   const page = await ensureBrowser();
   if (width || height) {
     await page.setViewport({
@@ -218,12 +218,30 @@ export async function browser_screenshot({ selector, full_page = false, width, h
     throw new Error(`Screenshot too large: ${Math.round(size / 1024)}KB (max ${Math.round(MAX_SCREENSHOT_BYTES / 1024)}KB)`);
   }
 
+  // Optional disk write so the caller can pass `path` to e.g. send_telegram
+  // instead of shuttling base64 around.
+  let writtenPath = null;
+  if (save_path || save_to_tmp) {
+    const fs   = await import("node:fs");
+    const path = await import("node:path");
+    const os   = await import("node:os");
+    let target = save_path;
+    if (!target) {
+      const dir = path.join(os.tmpdir(), "apx-screenshots");
+      fs.mkdirSync(dir, { recursive: true });
+      target = path.join(dir, `screenshot-${Date.now()}.png`);
+    }
+    fs.writeFileSync(target, Buffer.from(String(buf), "base64"));
+    writtenPath = target;
+  }
+
   return {
     ok: true,
     url: page.url(),
     format: "png",
     bytes: size,
     base64: buf,
+    path: writtenPath,
     data_uri: encoded ? `data:image/png;base64,${buf}` : undefined,
   };
 }

package/src/daemon/tools/registry.js

@@ -366,19 +366,21 @@ const TOOL_DEFINITIONS = [
   {
     name: "browser_screenshot",
     category: "browser",
-    description: "Take a screenshot of the current browser page (or a single element via selector). Returns base64 PNG.",
+    description: "Take a screenshot of the current browser page (or an element via selector). Returns { base64, path?, bytes, url }. To send via Telegram, prefer `save_to_tmp: true` and pass the returned `path` to send_telegram({photo_path}); otherwise pass `base64` straight to send_telegram({photo_base64}). NEVER include the base64 in any text field — Telegram does not render it.",
     endpoint: { method: "POST", path: "/tools/browser/screenshot" },
     parameters: {
       type: "object",
       properties: {
-        selector: { type: "string", description: "CSS selector of element to capture. Omit to capture full viewport/page." },
-        full_page: { type: "boolean", default: false },
-        width: { type: "number", description: "Viewport width (capped at 1920)." },
-        height: { type: "number", description: "Viewport height (capped at 1080)." },
-        encoded: { type: "boolean", description: "Also return a data: URI." },
+        selector:    { type: "string",  description: "CSS selector of element to capture. Omit for full viewport/page." },
+        full_page:   { type: "boolean", default: false },
+        width:       { type: "number",  description: "Viewport width (capped at 1920)." },
+        height:      { type: "number",  description: "Viewport height (capped at 1080)." },
+        encoded:     { type: "boolean", description: "Also return a data:image/png;base64 URI in response." },
+        save_path:   { type: "string",  description: "Absolute path to write the PNG. Returns it in `path`." },
+        save_to_tmp: { type: "boolean", description: "Auto-write to <os.tmpdir>/apx-screenshots/screenshot-<ts>.png. Returns the path." },
       },
     },
-    examples: [{}, { selector: "#hero" }],
+    examples: [{}, { selector: "#hero" }, { save_to_tmp: true }],
   },
   {
     name: "browser_click",