@agentprojectcontext/apx 1.13.1 → 1.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.13.1",
+  "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

@@ -36,6 +36,7 @@ import { stripThinking } from "../thinking.js";
 import { getRecentTelegramTurnsFromFs, appendGlobalMessage } from "../../core/messages-store.js";
 import { readAgents } from "../../core/parser.js";
 import { buildAgentSystem } from "../../core/agent-system.js";
+import { transcribe as transcribeAudioFile } from "../transcription.js";
 
 const API_BASE = "https://api.telegram.org";
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -112,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();
@@ -131,47 +166,9 @@ export async function sendAudio(token, chatId, audio, { caption, title, performe
   return json.result;
 }
 
-/**
- * Transcribe an audio file via OpenAI Whisper.
- * Reads OPENAI_API_KEY from env or engines.openai.api_key in ~/.apx/config.json.
- * Returns the transcribed text, or throws if no key / API failure.
- */
-async function transcribeAudio(filePath) {
-  let apiKey = process.env.OPENAI_API_KEY;
-  if (!apiKey) {
-    try {
-      const { readConfig } = await import("../../core/config.js");
-      apiKey = readConfig()?.engines?.openai?.api_key || "";
-    } catch { /* ignore */ }
-  }
-  if (!apiKey) throw new Error("OPENAI_API_KEY not set (env or engines.openai.api_key)");
-
-  const fileBuf = fs.readFileSync(filePath);
-  const ext = path.extname(filePath).slice(1).toLowerCase() || "ogg";
-  const mimeMap = {
-    oga: "audio/ogg", ogg: "audio/ogg", opus: "audio/ogg",
-    mp3: "audio/mpeg", m4a: "audio/mp4", mp4: "audio/mp4",
-    wav: "audio/wav", webm: "audio/webm",
-  };
-  const mime = mimeMap[ext] || "audio/ogg";
-  const blob = new Blob([fileBuf], { type: mime });
-
-  const form = new FormData();
-  form.append("file", blob, `audio.${ext}`);
-  form.append("model", "whisper-1");
-
-  const res = await fetch("https://api.openai.com/v1/audio/transcriptions", {
-    method: "POST",
-    headers: { Authorization: `Bearer ${apiKey}` },
-    body: form,
-  });
-  if (!res.ok) {
-    const err = await res.text().catch(() => "");
-    throw new Error(`Whisper ${res.status}: ${err.slice(0, 200)}`);
-  }
-  const json = await res.json();
-  return String(json.text || "").trim();
-}
+// Audio transcription is delegated to the central dispatcher
+// (../transcription.js) which handles local (faster-whisper via Python) +
+// OpenAI cloud fallback. See that module for config keys.
 
 /**
  * Download a file from Telegram servers.
@@ -444,6 +441,7 @@ class ChannelPoller {
       let localPath = null;
       let transcript = "";
       let transcribeError = null;
+      let transcribeBackend = null;
       try {
         localPath = await downloadTelegramFile(token, incomingAudio.file_id, mediaDir);
         this.log(`telegram[${this.channel.name}] audio saved: ${localPath}`);
@@ -452,8 +450,10 @@ class ChannelPoller {
       }
       if (localPath) {
         try {
-          transcript = await transcribeAudio(localPath);
-          this.log(`telegram[${this.channel.name}] audio transcribed (${transcript.length} chars)`);
+          const result = await transcribeAudioFile(localPath);
+          transcript = result.text || "";
+          transcribeBackend = result.backend;
+          this.log(`telegram[${this.channel.name}] audio transcribed via ${transcribeBackend} (${transcript.length} chars, lang=${result.language || "?"})`);
         } catch (e) {
           transcribeError = e.message;
           this.log(`telegram[${this.channel.name}] audio transcription failed: ${e.message}`);
@@ -480,6 +480,7 @@ class ChannelPoller {
           file_id: incomingAudio.file_id,
           duration: incomingAudio.duration,
           mime_type: incomingAudio.mime_type,
+          transcription_backend: transcribeBackend,
           transcription_error: transcribeError,
         },
       });
@@ -757,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);
@@ -881,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/index.js

@@ -21,6 +21,7 @@ import setPermissionMode from "./tools/set-permission-mode.js";
 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 { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 
@@ -48,6 +49,7 @@ const NATIVE_TOOLS = [
   searchFiles,
   listSkills,
   loadSkill,
+  transcribeAudio,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

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-tools/tools/transcribe-audio.js

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { transcribe } from "../../transcription.js";
+
+export default {
+  name: "transcribe_audio",
+  schema: {
+    type: "function",
+    function: {
+      name: "transcribe_audio",
+      description:
+        "Transcribe an audio file to text. Default backend is local faster-whisper (model 'medium' on CPU with int8 quantization), with automatic fallback to OpenAI Whisper API if local fails. Pass file_path for a file on disk, or base64 for raw audio bytes (will be written to a temp file). Override provider/model/language as needed.",
+      parameters: {
+        type: "object",
+        properties: {
+          file_path: { type: "string", description: "absolute path to audio file (.ogg, .mp3, .m4a, .wav, .webm, .opus)" },
+          base64: { type: "string", description: "alternative to file_path — raw base64 audio bytes (or 'data:audio/...;base64,...' data URI)" },
+          format: { type: "string", description: "file extension hint when using base64 (default 'ogg')" },
+          provider: { type: "string", description: "override the configured provider: 'auto' | 'local' | 'openai'" },
+          model: { type: "string", description: "local model size: tiny | base | small | medium | large | large-v2 | large-v3 (default medium)" },
+          language: { type: "string", description: "ISO 639-1 code (e.g. 'es', 'en') or 'auto' for detection" },
+          device: { type: "string", description: "local device: cpu | cuda (default cpu)" },
+          compute_type: { type: "string", description: "local quantization: int8 | int8_float16 | float16 | float32 (default int8)" },
+        },
+      },
+    },
+  },
+  makeHandler: () => async ({ file_path, base64, format = "ogg", provider, model, language, device, compute_type } = {}) => {
+    if (!file_path && !base64) throw new Error("transcribe_audio: file_path or base64 required");
+
+    let pathToUse = file_path;
+    let cleanupTmp = false;
+
+    if (!pathToUse && base64) {
+      const clean = String(base64).replace(/^data:audio\/[a-z]+;base64,/, "");
+      const buf = Buffer.from(clean, "base64");
+      const tmpDir = path.join(os.tmpdir(), "apx-transcribe");
+      fs.mkdirSync(tmpDir, { recursive: true });
+      const id = crypto.randomBytes(6).toString("hex");
+      pathToUse = path.join(tmpDir, `audio-${id}.${String(format).replace(/^\./, "") || "ogg"}`);
+      fs.writeFileSync(pathToUse, buf);
+      cleanupTmp = true;
+    }
+
+    try {
+      const overrides = {};
+      if (provider) overrides.provider = provider;
+      if (model) overrides.model = model;
+      if (language) overrides.language = language;
+      if (device) overrides.device = device;
+      if (compute_type) overrides.compute_type = compute_type;
+      return await transcribe(pathToUse, overrides);
+    } finally {
+      if (cleanupTmp) {
+        try { fs.unlinkSync(pathToUse); } catch { /* ignore */ }
+      }
+    }
+  },
+};

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

package/src/daemon/transcription.js

@@ -0,0 +1,193 @@
+// daemon/transcription.js
+// Audio transcription dispatcher. Two backends:
+//
+//   - LOCAL (faster-whisper via Python subprocess) — ported from Panda's
+//     transcription_service.py. Same defaults: model "medium", device "cpu",
+//     compute_type "int8", beam_size 5, auto language detection. Requires
+//     `pip3 install faster-whisper` on the host.
+//
+//   - OPENAI (Whisper-1 cloud API) — needs OPENAI_API_KEY or
+//     engines.openai.api_key in config.
+//
+// Provider selection in ~/.apx/config.json:
+//   "transcription": {
+//     "provider": "auto" | "local" | "openai",   // default "auto"
+//     "local": {
+//       "model": "medium",            // tiny | base | small | medium | large | large-v2 | large-v3
+//       "device": "cpu",              // cpu | cuda
+//       "compute_type": "int8",       // int8 | int8_float16 | float16 | float32
+//       "language": "auto",           // ISO 639-1 code or "auto"
+//       "beam_size": 5
+//     }
+//   }
+//
+// "auto" tries local first; on failure falls back to openai.
+
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __filename  = fileURLToPath(import.meta.url);
+const __dirname   = path.dirname(__filename);
+const PYTHON_HELPER = path.join(__dirname, "whisper-transcribe.py");
+
+const DEFAULT_LOCAL = {
+  model: "medium",
+  device: "cpu",
+  compute_type: "int8",
+  language: "auto",
+  beam_size: 5,
+};
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+async function getConfig() {
+  try {
+    const { readConfig } = await import("../core/config.js");
+    const cfg = readConfig() || {};
+    const t = cfg.transcription || {};
+    const openaiKey = cfg.engines?.openai?.api_key || process.env.OPENAI_API_KEY || "";
+    return {
+      provider: t.provider || "auto",
+      local: { ...DEFAULT_LOCAL, ...(t.local || {}) },
+      openaiKey,
+    };
+  } catch {
+    return {
+      provider: "auto",
+      local: { ...DEFAULT_LOCAL },
+      openaiKey: process.env.OPENAI_API_KEY || "",
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Local backend (Python + faster-whisper)
+// ---------------------------------------------------------------------------
+
+function transcribeLocal(filePath, opts) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      PYTHON_HELPER,
+      filePath,
+      "--model",       String(opts.model || DEFAULT_LOCAL.model),
+      "--language",    String(opts.language || DEFAULT_LOCAL.language),
+      "--device",      String(opts.device || DEFAULT_LOCAL.device),
+      "--compute-type", String(opts.compute_type || DEFAULT_LOCAL.compute_type),
+      "--beam-size",   String(opts.beam_size || DEFAULT_LOCAL.beam_size),
+    ];
+    execFile("python3", args, { maxBuffer: 16 * 1024 * 1024, timeout: 5 * 60_000 }, (err, stdout, stderr) => {
+      if (err) {
+        const tail = (stderr || err.message || "").slice(-300);
+        return reject(new Error(`local transcription failed: ${tail}`));
+      }
+      let parsed;
+      try { parsed = JSON.parse(String(stdout).trim().split("\n").pop()); }
+      catch (e) {
+        return reject(new Error(`could not parse helper output: ${stdout.slice(0, 300)}`));
+      }
+      if (!parsed.ok) return reject(new Error(parsed.error || "unknown local transcription error"));
+      resolve({
+        ok: true,
+        backend: "local",
+        text: parsed.text || "",
+        language: parsed.language || null,
+        language_probability: parsed.language_probability ?? null,
+        duration: parsed.duration ?? null,
+        model: parsed.model,
+        compute_type: parsed.compute_type,
+      });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// OpenAI backend (Whisper-1 cloud)
+// ---------------------------------------------------------------------------
+
+async function transcribeOpenAI(filePath, apiKey) {
+  if (!apiKey) throw new Error("OPENAI_API_KEY not set (env or engines.openai.api_key)");
+
+  const fileBuf = fs.readFileSync(filePath);
+  const ext = path.extname(filePath).slice(1).toLowerCase() || "ogg";
+  const mimeMap = {
+    oga: "audio/ogg", ogg: "audio/ogg", opus: "audio/ogg",
+    mp3: "audio/mpeg", m4a: "audio/mp4", mp4: "audio/mp4",
+    wav: "audio/wav", webm: "audio/webm",
+  };
+  const blob = new Blob([fileBuf], { type: mimeMap[ext] || "audio/ogg" });
+
+  const form = new FormData();
+  form.append("file", blob, `audio.${ext}`);
+  form.append("model", "whisper-1");
+
+  const res = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    body: form,
+  });
+  if (!res.ok) {
+    const err = await res.text().catch(() => "");
+    throw new Error(`Whisper API ${res.status}: ${err.slice(0, 200)}`);
+  }
+  const json = await res.json();
+  return {
+    ok: true,
+    backend: "openai",
+    text: String(json.text || "").trim(),
+    language: null,
+    language_probability: null,
+    duration: null,
+    model: "whisper-1",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Transcribe an audio file using the configured backend.
+ * Returns { ok, backend, text, language?, language_probability?, duration?, model? }.
+ *
+ * @param {string} filePath   absolute path to audio file
+ * @param {object} overrides  optional: { provider, model, language, ... }
+ */
+export async function transcribe(filePath, overrides = {}) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    throw new Error(`transcribe: file not found: ${filePath}`);
+  }
+  const cfg = await getConfig();
+  const provider = overrides.provider || cfg.provider;
+  const localOpts = { ...cfg.local, ...overrides };
+
+  if (provider === "openai") {
+    return transcribeOpenAI(filePath, cfg.openaiKey);
+  }
+  if (provider === "local") {
+    return transcribeLocal(filePath, localOpts);
+  }
+
+  // auto: local first, fall back to openai
+  try {
+    return await transcribeLocal(filePath, localOpts);
+  } catch (localErr) {
+    if (!cfg.openaiKey) {
+      throw new Error(
+        `local transcription failed and no OpenAI fallback available: ${localErr.message}`
+      );
+    }
+    return transcribeOpenAI(filePath, cfg.openaiKey);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+
+export const TRANSCRIPTION_PATHS = {
+  python_helper: PYTHON_HELPER,
+};

package/src/daemon/whisper-transcribe.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""
+Local audio transcription via faster-whisper. Mirrors the implementation in
+the Panda project (transcription_service.py): same default model "medium",
+device cpu, compute_type int8, beam_size 5. Lazy singleton model cache.
+
+Invoked by APX daemon (Node) as a subprocess. Args:
+  whisper-transcribe.py <audio_path> [--model medium] [--language auto] [--device cpu] [--compute-type int8] [--beam-size 5]
+
+Outputs JSON on stdout:
+  { "ok": true,  "text": "...", "language": "es", "language_probability": 0.98, "duration": 12.4 }
+  { "ok": false, "error": "..." }
+"""
+import argparse
+import json
+import os
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("audio_path")
+    parser.add_argument("--model", default="medium")
+    parser.add_argument("--language", default="auto")
+    parser.add_argument("--device", default="cpu")
+    parser.add_argument("--compute-type", dest="compute_type", default="int8")
+    parser.add_argument("--beam-size", dest="beam_size", type=int, default=5)
+    args = parser.parse_args()
+
+    if not os.path.exists(args.audio_path):
+        print(json.dumps({"ok": False, "error": f"file not found: {args.audio_path}"}))
+        return 1
+
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError as e:
+        print(json.dumps({
+            "ok": False,
+            "error": "faster-whisper not installed. Run: pip3 install faster-whisper",
+            "import_error": str(e),
+        }))
+        return 1
+
+    try:
+        model = WhisperModel(args.model, device=args.device, compute_type=args.compute_type)
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": f"failed to load model '{args.model}': {e}"}))
+        return 1
+
+    language = None if args.language == "auto" else args.language
+
+    try:
+        segments, info = model.transcribe(args.audio_path, beam_size=args.beam_size, language=language)
+        text = " ".join(seg.text.strip() for seg in segments).strip()
+        print(json.dumps({
+            "ok": True,
+            "text": text,
+            "language": info.language,
+            "language_probability": round(info.language_probability, 4),
+            "duration": round(info.duration, 2),
+            "model": args.model,
+            "compute_type": args.compute_type,
+        }))
+        return 0
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": f"transcription failed: {e}"}))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())