@agentprojectcontext/apx 1.14.0 → 1.15.0

package/src/daemon/skills-loader.js

@@ -1,26 +1,28 @@
 // daemon/skills-loader.js
 // Discover and load APX skills on-demand for the super-agent.
 //
-// The super-agent reads skills from immutable INTERNAL sources under
-// src/core/ — they ship with apx and can never be deleted by the user. This
-// guarantees apx/apc/runtime knowledge is always available regardless of
-// what the user does to ~/.apx/skills/. Distribution copies under
-// <package>/skills/ are a separate concern (scaffold.js handles them) and
-// the loader does NOT read from there.
+// The super-agent reads skills from immutable INTERNAL sources under the
+// package root — they ship with apx and can never be deleted by the user.
+// This guarantees apx/apc/runtime knowledge is always available regardless
+// of what the user does to ~/.apx/skills/ or per-project overrides.
 //
 // Discovery order (priority high → low):
-//   1. <projectPath>/.apc/skills/<slug>.md          ← project-scoped
-//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md    ← same, dir-style
-//   2. ~/.apx/skills/<slug>/SKILL.md                ← user-installed global
-//   3. <packageRoot>/src/core/runtime-skills/<slug>.md ← built-in runtime docs
-//                                                       (claude-code, codex-cli,
-//                                                       opencode-cli, openrouter)
-//   4. <packageRoot>/src/core/apx-skill.md          ← built-in intrinsic apx
-//   4b.<packageRoot>/src/core/apc-context-skill.md  ← built-in intrinsic apc-context
+//   1. <projectPath>/.apc/skills/<slug>.md           ← project-scoped (flat)
+//   1b.<projectPath>/.apc/skills/<slug>/SKILL.md     ← project-scoped (dir)
+//   2. ~/.apx/skills/<slug>/SKILL.md                 ← user-installed global
+//   3. <packageRoot>/skills/<slug>/SKILL.md          ← bundled core skills
+//                                                     (apx, apc-context)
+//   4. <packageRoot>/src/core/runtime-skills/<slug>.md
+//                                                     (claude-code, codex-cli,
+//                                                      opencode-cli, openrouter)
 //
-// A slug found in a higher-priority location SHADOWS lower ones — so a user
-// who drops `~/.apx/skills/apx/SKILL.md` overrides the intrinsic one, but the
-// intrinsic stays in the package as a safety net.
+// A slug found in a higher-priority location SHADOWS lower ones. A user can
+// override the bundled apc-context by dropping `~/.apx/skills/apc-context/SKILL.md`,
+// but the bundled copy stays in the package as a safety net.
+//
+// Note: the bundled `apc-context` skill is REFRESHED from the canonical apc
+// repo on every npm install / update (see src/cli/postinstall.js). APC is a
+// living standard, so its skill content is not pinned to an apx version.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -32,38 +34,8 @@ const __dirname  = path.dirname(__filename);
 const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
 
 const RUNTIME_SKILLS_DIR = path.join(PACKAGE_ROOT, "src", "core", "runtime-skills");
+const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
 const GLOBAL_DIR         = path.join(os.homedir(), ".apx", "skills");
-const CORE_DIR           = path.join(PACKAGE_ROOT, "src", "core");
-
-// Intrinsic built-in skills whose source files (src/core/*-skill.md) do NOT
-// carry frontmatter — the scaffold.js wrapper adds frontmatter when copying
-// these out to external IDE skill dirs. For the super-agent's catalog we
-// supply slug + description inline. Keep in sync with scaffold.js.
-const INTRINSIC = [
-  {
-    slug: "apx",
-    file: path.join(CORE_DIR, "apx-skill.md"),
-    description:
-      "APX CLI skill. Activate when: user asks to run or coordinate agents, " +
-      "use MCP tools from .apc/mcps.json, install agents from a team workspace, " +
-      "or explicitly mentions apx commands. Do NOT activate just because .apc/ exists — " +
-      "that is handled by the apc-context skill. Activate on: 'apx run', 'apx exec', " +
-      "'run an agent', 'coordinate agents', 'MCP not working', 'install agent', " +
-      "'team agents', 'apx memory', 'daemon'.",
-  },
-  {
-    slug: "apc-context",
-    file: path.join(CORE_DIR, "apc-context-skill.md"),
-    description:
-      "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. " +
-      "Do not wait to be asked. Read .apc/ before making any assumption about agents, " +
-      "memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', " +
-      "'list agents', 'agent context', 'who are the agents', any question about agents " +
-      "or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the " +
-      "conversation with a migration offer before answering anything else. If the user " +
-      "declines, delete .apc/migrate.md immediately so it is not shown again.",
-  },
-];
 
 // ---------------------------------------------------------------------------
 // Frontmatter parsing (minimal — handles the YAML we ship)
@@ -153,15 +125,11 @@ export function listSkills({ projectPath } = {}) {
   // priority 2: user-installed global
   found.push(...scanDirStyle(GLOBAL_DIR, "global"));
 
-  // priority 3: built-in runtime docs (have frontmatter)
-  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
+  // priority 3: bundled core skills (apx, apc-context)
+  found.push(...scanDirStyle(BUNDLED_SKILLS_DIR, "builtin"));
 
-  // priority 4: intrinsic built-ins (no frontmatter — descriptions hardcoded)
-  for (const it of INTRINSIC) {
-    if (fs.existsSync(it.file)) {
-      found.push({ slug: it.slug, source: "builtin", file: it.file, _description: it.description });
-    }
-  }
+  // priority 4: runtime docs (claude-code, codex-cli, opencode-cli, openrouter)
+  found.push(...scanFlatStyle(RUNTIME_SKILLS_DIR, "builtin"));
 
   // dedupe by slug (first-wins = higher priority shadows lower)
   const seen = new Set();
@@ -170,15 +138,12 @@ export function listSkills({ projectPath } = {}) {
     if (seen.has(entry.slug)) continue;
     seen.add(entry.slug);
 
-    // Description: prefer inline (intrinsic) → frontmatter → empty
-    let description = entry._description || "";
-    if (!description) {
-      try {
-        const raw = fs.readFileSync(entry.file, "utf8");
-        const { fm } = parseFrontmatter(raw);
-        description = fm.description || "";
-      } catch { /* unreadable — skip description */ }
-    }
+    let description = "";
+    try {
+      const raw = fs.readFileSync(entry.file, "utf8");
+      const { fm } = parseFrontmatter(raw);
+      description = fm.description || "";
+    } catch { /* unreadable — skip description */ }
 
     result.push({
       slug: entry.slug,
@@ -223,6 +188,6 @@ export function loadSkill(slug, { projectPath } = {}) {
 // Useful for diagnostics
 export const SKILL_LOCATIONS = {
   runtime_skills: RUNTIME_SKILLS_DIR,
-  intrinsic: CORE_DIR,
+  bundled: BUNDLED_SKILLS_DIR,
   global: GLOBAL_DIR,
 };

package/src/daemon/smoke.js

@@ -14,7 +14,14 @@ import { readAgents } from "../core/parser.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-const EXAMPLE = path.resolve(__dirname, "..", "..", "examples", "my-first-project");
+const EXAMPLE_CANDIDATES = [
+  path.resolve(__dirname, "..", "..", "examples", "my-first-project"),
+  path.resolve(__dirname, "..", "..", "..", "apc", "examples", "my-first-project"),
+];
+const EXAMPLE = EXAMPLE_CANDIDATES.find((p) =>
+  fs.existsSync(path.join(p, "AGENTS.md")) &&
+  fs.existsSync(path.join(p, ".apc", "project.json"))
+);
 
 function assert(cond, msg) {
   if (!cond) {
@@ -24,6 +31,7 @@ function assert(cond, msg) {
 }
 
 const projects = new ProjectManager();
+assert(EXAMPLE, `example project missing; checked ${EXAMPLE_CANDIDATES.join(", ")}`);
 const entry = projects.register(EXAMPLE);
 console.log("registered project", entry.id, entry.path);
 

package/src/daemon/super-agent-tools/index.js

@@ -22,6 +22,7 @@ import searchFiles from "./tools/search-files.js";
 import listSkills from "./tools/list-skills.js";
 import loadSkill from "./tools/load-skill.js";
 import transcribeAudio from "./tools/transcribe-audio.js";
+import askQuestions from "./tools/ask-questions.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 
@@ -50,6 +51,7 @@ const NATIVE_TOOLS = [
   listSkills,
   loadSkill,
   transcribeAudio,
+  askQuestions,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

package/src/daemon/super-agent-tools/tools/ask-questions.js

@@ -0,0 +1,28 @@
+export default {
+  name: "ask_questions",
+  schema: {
+    function: {
+      name: "ask_questions",
+      description: "Ask the user one or more specific questions to clarify the task or gather requirements.",
+      parameters: {
+        type: "object",
+        properties: {
+          questions: {
+            type: "array",
+            items: { type: "string" },
+            description: "A list of questions for the user."
+          }
+        },
+        required: ["questions"]
+      }
+    }
+  },
+  makeHandler: () => async ({ questions }) => {
+    // This tool is used by the agent to explicitly signal that it is waiting for 
+    // answers to specific questions. The UI can then highlight these.
+    return { 
+      status: "Questions presented to user. Waiting for input.", 
+      count: questions.length 
+    };
+  }
+};

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,49 @@ 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 compactToolSchema(schema) {
+  const fn = schema?.function || {};
+  const params = fn.parameters || {};
+  const properties = params.properties || {};
+  return {
+    name: fn.name,
+    description: fn.description,
+    required: params.required || [],
+    properties: Object.fromEntries(
+      Object.entries(properties).map(([name, spec]) => [
+        name,
+        {
+          type: spec?.type || "string",
+          enum: spec?.enum,
+          description: spec?.description,
+        },
+      ])
+    ),
+  };
+}
+
+function pseudoToolSystem(system) {
+  const catalog = TOOL_SCHEMAS.map(compactToolSchema);
+  return [
+    system,
+    "# Structured tool fallback",
+    "The engine rejected native structured tools. You can still call tools by emitting plain JSON.",
+    "When you need a tool, respond ONLY with one JSON object per line:",
+    "{\"name\":\"tool_name\",\"arguments\":{\"arg\":\"value\"}}",
+    "After tool results arrive, continue the task or give the final answer normally.",
+    "Available tools:",
+    JSON.stringify(catalog),
+  ].join("\n\n");
+}
+
+function shouldRetryWithPseudoTools(modelId, error, alreadyPseudo) {
+  if (alreadyPseudo) return false;
+  const message = String(error?.message || "");
+  return /^ollama:/i.test(String(modelId || "")) && /ollama\s+500/i.test(message);
+}
 
 function isShortConfirmation(text) {
   return /^(yes|y|si|si dale|dale|ok|okay|confirm|confirmed|go|proceed|do it)\b/i
@@ -114,6 +156,7 @@ export async function runSuperAgent({
   previousMessages = [],
   overrideModel = null,
   onEvent = null,
+  signal,
 }) {
   if (!isSuperAgentEnabled(globalConfig)) {
     throw new Error("super-agent not enabled (set super_agent.enabled and .model in ~/.apx/config.json)");
@@ -186,6 +229,7 @@ export async function runSuperAgent({
   const trace = [];
   let totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
+  let usePseudoTools = false;
 
   for (let iter = 0; iter < MAX_TOOL_ITERS; iter++) {
     await emitProgress(onEvent, { type: "model_start", iteration: iter + 1 });
@@ -194,15 +238,38 @@ export async function runSuperAgent({
     // acting on an action request. On later iterations (after tool results
     // have been fed back) tool_choice is "auto" so the model can produce its
     // final text summary.
-    const result = await callEngine({
-      modelId: activeModel,
-      system,
-      messages: conversation,
-      config: globalConfig,
-      tools: TOOL_SCHEMAS,
-      toolChoice: iter === 0 ? "required" : "auto",
-      maxTokens: 1024,
-    });
+    let result;
+    try {
+      result = await callEngine({
+        modelId: activeModel,
+        system: usePseudoTools ? pseudoToolSystem(system) : system,
+        messages: conversation,
+        config: globalConfig,
+        tools: usePseudoTools ? null : TOOL_SCHEMAS,
+        toolChoice: usePseudoTools ? null : (iter === 0 ? "required" : "auto"),
+        maxTokens: 1024,
+        signal,
+      });
+    } catch (e) {
+      if (usePseudoTools && /^ollama:/i.test(String(activeModel || "")) && /ollama\s+500/i.test(String(e?.message || "")) && trace.length > 0) {
+        await emitProgress(onEvent, { type: "model_retry", reason: "ollama_final_response_500", iteration: iter + 1 });
+        lastText = fallbackFinalText(trace, e);
+        break;
+      }
+      if (!shouldRetryWithPseudoTools(activeModel, e, usePseudoTools)) throw e;
+      usePseudoTools = true;
+      await emitProgress(onEvent, { type: "model_retry", reason: "ollama_structured_tools_500", iteration: iter + 1 });
+      result = await callEngine({
+        modelId: activeModel,
+        system: pseudoToolSystem(system),
+        messages: conversation,
+        config: globalConfig,
+        tools: null,
+        toolChoice: null,
+        maxTokens: 1024,
+        signal,
+      });
+    }
     totalUsage.input_tokens += result.usage?.input_tokens || 0;
     totalUsage.output_tokens += result.usage?.output_tokens || 0;
     lastText = result.text || "";
@@ -316,3 +383,25 @@ function summarizeForTrace(r) {
   if (s.length <= 400) return r;
   return s.slice(0, 380) + "…(truncated)";
 }
+
+function fallbackFinalText(trace, error) {
+  const lines = [
+    "Tool execution completed, but the model failed while composing the final answer.",
+    `Engine error: ${String(error?.message || error).slice(0, 220)}`,
+    "Trace:",
+  ];
+  for (const item of trace.slice(-8)) {
+    lines.push(`- ${item.tool}: ${previewTraceResult(item.result)}`);
+  }
+  return lines.join("\n");
+}
+
+function previewTraceResult(result) {
+  if (result === null || result === undefined) return "ok";
+  if (typeof result === "string") return result.slice(0, 180);
+  if (result.error) return `error: ${String(result.error).slice(0, 180)}`;
+  if (result.path) return String(result.path).slice(0, 180);
+  if (result.content) return String(result.content).slice(0, 180);
+  if (result.results) return JSON.stringify(result.results).slice(0, 180);
+  return JSON.stringify(result).slice(0, 180);
+}

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",