@agentprojectcontext/apx 1.14.0 → 1.15.0

package/src/core/logging.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import { APX_HOME } from "./config.js";
+
+export const LOG_DIR = path.join(APX_HOME, "logs");
+export const ERROR_TRACE_PATH = path.join(LOG_DIR, "errors.jsonl");
+
+const SECRET_KEY_RE = /(token|secret|password|api[_-]?key|authorization|bot[_-]?token)/i;
+
+function redact(value, seen = new WeakSet()) {
+  if (value === null || value === undefined) return value;
+  if (typeof value !== "object") return value;
+  if (seen.has(value)) return "[circular]";
+  seen.add(value);
+
+  if (Array.isArray(value)) return value.map((item) => redact(item, seen));
+
+  const out = {};
+  for (const [key, val] of Object.entries(value)) {
+    out[key] = SECRET_KEY_RE.test(key) ? "[redacted]" : redact(val, seen);
+  }
+  return out;
+}
+
+export function appendErrorTrace(record) {
+  fs.mkdirSync(LOG_DIR, { recursive: true });
+  const entry = {
+    ts: new Date().toISOString(),
+    ...redact(record),
+  };
+  fs.appendFileSync(ERROR_TRACE_PATH, JSON.stringify(entry) + "\n", "utf8");
+}
+
+export function previewText(text, max = 500) {
+  const clean = String(text || "").replace(/\s+/g, " ").trim();
+  return clean.length > max ? clean.slice(0, max - 1) + "…" : clean;
+}

package/src/core/scaffold.js

@@ -6,9 +6,43 @@ import { fileURLToPath } from "node:url";
 import { readAgents, readAgentsFromDir, VAULT_DIR } from "./parser.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const BUNDLED_SKILLS_DIR = path.join(PACKAGE_ROOT, "skills");
+const RUNTIME_SKILLS_DIR = path.join(__dirname, "runtime-skills");
 
 export const SPEC_VERSION = "0.1.0";
 
+// ---------------------------------------------------------------------------
+// Bundled skills — single source of truth lives at <packageRoot>/skills/<slug>/SKILL.md
+// with proper frontmatter. The `apc-context` copy is refreshed on every
+// install/update from the canonical APC repo (see src/cli/postinstall.js).
+// ---------------------------------------------------------------------------
+
+function readBundledSkill(slug) {
+  const file = path.join(BUNDLED_SKILLS_DIR, slug, "SKILL.md");
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, "utf8");
+}
+
+// Split frontmatter and body from a SKILL.md. Used by IDE targets that need
+// to re-wrap the body in their own rule-file frontmatter.
+function splitFrontmatter(raw) {
+  if (!raw.startsWith("---")) return { fm: "", body: raw };
+  const end = raw.indexOf("\n---", 3);
+  if (end < 0) return { fm: "", body: raw };
+  const fm = raw.slice(0, end + 4);
+  const body = raw.slice(end + 4).replace(/^\n/, "");
+  return { fm, body };
+}
+
+// Pull description from frontmatter so cursor/.mdc rule files can advertise
+// the same activation trigger.
+function readDescription(raw) {
+  const { fm } = splitFrontmatter(raw);
+  const m = fm.match(/^description:\s*"?(.*?)"?\s*$/m);
+  return m ? m[1] : "";
+}
+
 // ---------------------------------------------------------------------------
 // IDE skill targets — written during `apx init` and `apx skills add`
 // ---------------------------------------------------------------------------
@@ -21,7 +55,8 @@ export const IDE_TARGETS = [
     label: "Claude Code",
     ideDir: ".claude",
     file: ".claude/skills/apx/SKILL.md",
-    render: (c) => buildSkillMd(c),
+    // Claude Code consumes SKILL.md with its native frontmatter as-is.
+    render: (raw) => raw,
     append: false,
   },
   {
@@ -29,8 +64,11 @@ export const IDE_TARGETS = [
     label: "Cursor",
     ideDir: ".cursor",
     file: ".cursor/rules/apx.mdc",
-    render: (c) =>
-      `---\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      const desc = readDescription(raw);
+      return `---\ndescription: ${desc}\n---\n\n${body}`;
+    },
     append: false,
   },
   {
@@ -38,8 +76,11 @@ export const IDE_TARGETS = [
     label: "Windsurf",
     ideDir: ".windsurf",
     file: ".windsurf/rules/apx.md",
-    render: (c) =>
-      `---\ntrigger: model_decision\ndescription: APX CLI skill. Activate when the user asks about running agents, coordinating between agents, or uses apx commands (apx run, apx exec, apx memory, apx mcp, apx session, apx messages).\n---\n\n${c}`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      const desc = readDescription(raw);
+      return `---\ntrigger: model_decision\ndescription: ${desc}\n---\n\n${body}`;
+    },
     append: false,
   },
   {
@@ -47,7 +88,10 @@ export const IDE_TARGETS = [
     label: "GitHub Copilot",
     ideDir: ".github",
     file: ".github/copilot-instructions.md",
-    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      return `\n<!-- apx-skill -->\n${body}\n<!-- /apx-skill -->\n`;
+    },
     append: true,
     guard: "<!-- apx-skill -->",
   },
@@ -56,13 +100,16 @@ export const IDE_TARGETS = [
     label: "Trae",
     ideDir: ".trae",
     file: ".trae/rules/project_rules.md",
-    render: (c) => `\n<!-- apx-skill -->\n${c}\n<!-- /apx-skill -->\n`,
+    render: (raw) => {
+      const { body } = splitFrontmatter(raw);
+      return `\n<!-- apx-skill -->\n${body}\n<!-- /apx-skill -->\n`;
+    },
     append: true,
     guard: "<!-- apx-skill -->",
   },
 ];
 
-// Global targets (absolute paths, use ~/<dir>/skills/apx/SKILL.md format).
+// Global targets (absolute paths, use ~/<dir>/skills/<slug>/SKILL.md format).
 // These dirs are read by Claude Code, Cursor (compat), and tools adopting the skills.sh spec.
 const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".claude", "skills"),    // Claude Code + Cursor legacy compat
@@ -71,52 +118,23 @@ const GLOBAL_SKILL_DIRS = [
   path.join(os.homedir(), ".agents", "skills"),    // Antigravity/other skills.sh adopters
 ];
 
-function buildApcContextSkillMd(content) {
-  const frontmatter = [
-    "---",
-    "name: apc-context",
-    "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.\"",
-    "homepage: https://github.com/agentprojectcontext/agentprojectcontext",
-    "---",
-    "",
-  ].join("\n");
-  return frontmatter + content;
-}
-
-function buildSkillMd(content) {
-  const frontmatter = [
-    "---",
-    "name: apx",
-    "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'.\"",
-    "homepage: https://github.com/agentprojectcontext/apx",
-    "---",
-    "",
-  ].join("\n");
-  return frontmatter + content;
-}
-
 function readRuntimeSkillFiles() {
-  const skillsDir = path.join(__dirname, "runtime-skills");
-  if (!fs.existsSync(skillsDir)) return [];
-
-  return fs.readdirSync(skillsDir)
+  if (!fs.existsSync(RUNTIME_SKILLS_DIR)) return [];
+  return fs.readdirSync(RUNTIME_SKILLS_DIR)
     .filter((name) => name.endsWith(".md"))
     .sort()
     .map((name) => ({
       slug: path.basename(name, ".md"),
-      md: fs.readFileSync(path.join(skillsDir, name), "utf8").trim(),
+      md: fs.readFileSync(path.join(RUNTIME_SKILLS_DIR, name), "utf8").trim(),
     }));
 }
 
 // Install APX + APC context skills into IDE rule files. Returns an array of result objects.
 // targetIds: array of target ids to install; null = all project targets.
 export function installIdeSkills(root, targetIds = null) {
-  const apxSrc = path.join(__dirname, "apx-skill.md");
-  const apcSrc = path.join(__dirname, "apc-context-skill.md");
-  if (!fs.existsSync(apxSrc)) return [];
-
-  const apxContent = fs.readFileSync(apxSrc, "utf8").trim();
-  const apcContent = fs.existsSync(apcSrc) ? fs.readFileSync(apcSrc, "utf8").trim() : null;
+  const apxRaw = readBundledSkill("apx");
+  const apcRaw = readBundledSkill("apc-context");
+  if (!apxRaw) return [];
 
   const targets = targetIds
     ? IDE_TARGETS.filter((t) => targetIds.includes(t.id))
@@ -129,10 +147,9 @@ export function installIdeSkills(root, targetIds = null) {
       continue;
     }
 
-    // Install APX skill
     const dest = path.join(root, t.file);
     fs.mkdirSync(path.dirname(dest), { recursive: true });
-    const rendered = t.render(apxContent);
+    const rendered = t.render(apxRaw);
     if (t.append) {
       const existing = fs.existsSync(dest) ? fs.readFileSync(dest, "utf8") : "";
       if (t.guard && existing.includes(t.guard)) {
@@ -147,31 +164,28 @@ export function installIdeSkills(root, targetIds = null) {
       results.push({ ...t, status: existed ? "updated" : "created" });
     }
 
-    // Install APC context skill alongside (only for non-append targets with a skills dir)
-    if (apcContent && t.id === "claude-code") {
+    // Install APC context skill alongside Claude Code (dir-style skills dir).
+    if (apcRaw && t.id === "claude-code") {
       const apcDest = path.join(root, ".claude", "skills", "apc-context", "SKILL.md");
       fs.mkdirSync(path.dirname(apcDest), { recursive: true });
       const existed = fs.existsSync(apcDest);
-      fs.writeFileSync(apcDest, buildApcContextSkillMd(apcContent), "utf8");
+      fs.writeFileSync(apcDest, apcRaw, "utf8");
       results.push({ ...t, id: "claude-code/apc-context", label: "Claude Code (apc-context)", file: apcDest, status: existed ? "updated" : "created" });
     }
   }
   return results;
 }
 
-// Install both APX and APC context skills to global ~/.../skills/ dirs.
+// Install bundled APX/APC skills + runtime docs to global ~/.../skills/ dirs.
 // Returns an array of result objects with { dir, skill, status }.
 export function installGlobalSkills() {
   const results = [];
 
-  const apxSrc = path.join(__dirname, "apx-skill.md");
-  const apcSrc = path.join(__dirname, "apc-context-skill.md");
-
   const skills = [];
-  if (fs.existsSync(apxSrc))
-    skills.push({ slug: "apx", md: buildSkillMd(fs.readFileSync(apxSrc, "utf8").trim()) });
-  if (fs.existsSync(apcSrc))
-    skills.push({ slug: "apc-context", md: buildApcContextSkillMd(fs.readFileSync(apcSrc, "utf8").trim()) });
+  const apxRaw = readBundledSkill("apx");
+  const apcRaw = readBundledSkill("apc-context");
+  if (apxRaw) skills.push({ slug: "apx", md: apxRaw });
+  if (apcRaw) skills.push({ slug: "apc-context", md: apcRaw });
   skills.push(...readRuntimeSkillFiles());
 
   for (const base of GLOBAL_SKILL_DIRS) {

package/src/daemon/api.js

@@ -1,6 +1,7 @@
 // Express REST API for APX. See APC docs reference/apx-daemon.
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import express from "express";
 import { buildBrowserRouter } from "./tools/browser.js";
@@ -49,6 +50,7 @@ import { readAgents } from "../core/parser.js";
 import { parseSessionFrontmatter } from "../core/parser.js";
 import { writeAgentFile, ensureAgentDir, regenerateAgentsMd } from "../core/scaffold.js";
 import { buildAgentSystem } from "../core/agent-system.js";
+import { appendErrorTrace, previewText } from "../core/logging.js";
 import {
   createArtifact,
   listArtifacts,
@@ -58,11 +60,34 @@ import {
 
 const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
+function appendSuperAgentErrorTrace(req, error, details = {}) {
+  appendErrorTrace({
+    trace_id: req.apxTraceId,
+    surface: "daemon_api",
+    route: `${req.method} ${req.route?.path || req.path}`,
+    project_id: req.params?.pid || null,
+    channel: /Channel:\s*([^\n]+)/i.exec(details.contextNote || "")?.[1]?.trim() || null,
+    model: details.model || null,
+    stream: !!details.stream,
+    prompt_preview: previewText(details.prompt),
+    previous_messages: Array.isArray(details.previousMessages) ? details.previousMessages.length : 0,
+    error: {
+      message: error?.message || String(error),
+      stack: error?.stack || null,
+    },
+  });
+}
+
 export function buildApi({ projects, registries, plugins, scheduler, version, startedAt, addProjectGlobally, config }) {
   const telegram = plugins?.get("telegram");
 
   const app = express();
   app.use(express.json({ limit: "2mb" }));
+  app.use((req, res, next) => {
+    req.apxTraceId = req.get("x-apx-trace-id") || randomUUID();
+    res.setHeader("x-apx-trace-id", req.apxTraceId);
+    next();
+  });
 
   // ---- Tool routers (fetch / browser / search / glob / grep / registry) ----
   // fetch  = native HTTP, no Chromium  → fast, cheap, default for REST/HTML
@@ -636,7 +661,8 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
       });
       res.end();
     } catch (e) {
-      send({ type: "error", error: e.message });
+      appendSuperAgentErrorTrace(req, e, { prompt, contextNote, previousMessages, model, stream: true });
+      send({ type: "error", trace_id: req.apxTraceId, error: `${e.message} (trace: ${req.apxTraceId})` });
       res.end();
     }
   });
@@ -665,7 +691,8 @@ export function buildApi({ projects, registries, plugins, scheduler, version, st
         trace: saResult.trace,
       });
     } catch (e) {
-      res.status(500).json({ error: e.message });
+      appendSuperAgentErrorTrace(req, e, { prompt, contextNote, previousMessages, model, stream: false });
+      res.status(500).json({ error: e.message, trace_id: req.apxTraceId });
     }
   });
 

package/src/daemon/engines/anthropic.js

@@ -11,7 +11,7 @@ function getKey(config) {
 export default {
   id: "anthropic",
 
-  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice }) {
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("anthropic: no api_key (set ANTHROPIC_API_KEY or engines.anthropic.api_key)");
     if (!model) throw new Error("anthropic: model required");
@@ -47,6 +47,7 @@ export default {
         "anthropic-version": API_VERSION,
       },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

package/src/daemon/engines/gemini.js

@@ -10,7 +10,7 @@ function getKey(config) {
 export default {
   id: "gemini",
 
-  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, config = {} }) {
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, config = {}, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("gemini: no api_key (set GEMINI_API_KEY or engines.gemini.api_key)");
     if (!model) throw new Error("gemini: model required");
@@ -33,6 +33,7 @@ export default {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

package/src/daemon/engines/index.js

@@ -46,11 +46,10 @@ export function getAdapter(provider) {
   return a;
 }
 
-export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice }) {
+export async function callEngine({ modelId, system, messages, config, temperature, maxTokens, tools, toolChoice, signal }) {
   const { provider, model } = resolveProvider(modelId);
   const adapter = getAdapter(provider);
-  const providerCfg =
-    (config && config.engines && config.engines[provider]) || {};
+  const providerCfg = (config && config.engines && config.engines[provider]) || {};
   return adapter.chat({
     system,
     messages,
@@ -60,6 +59,7 @@ export async function callEngine({ modelId, system, messages, config, temperatur
     tools,
     toolChoice,
     config: providerCfg,
+    signal,
   });
 }
 

package/src/daemon/engines/ollama.js

@@ -8,7 +8,7 @@ function baseUrl(config) {
 export default {
   id: "ollama",
 
-  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {} }) {
+  async chat({ system, messages, model, temperature = 0.7, maxTokens = 1024, tools, config = {}, signal }) {
     if (!model) throw new Error("ollama: model required");
 
     // The caller can pass `messages` as either:
@@ -45,6 +45,7 @@ export default {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body),
+      signal,
     });
     if (!res.ok) {
       const text = await res.text();

package/src/daemon/engines/openai.js

@@ -10,7 +10,7 @@ function getKey(config) {
 export default {
   id: "openai",
 
-  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice }) {
+  async chat({ system, messages, model, temperature = 1.0, maxTokens = 1024, config = {}, tools, toolChoice, signal }) {
     const key = getKey(config);
     if (!key) throw new Error("openai: no api_key (set OPENAI_API_KEY or engines.openai.api_key)");
     if (!model) throw new Error("openai: model required");
@@ -52,6 +52,7 @@ export default {
         authorization: `Bearer ${key}`,
       },
       body: JSON.stringify(body),
+      signal,
     });
     const json = await res.json();
     if (!res.ok) {

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();
@@ -256,6 +290,7 @@ class ChannelPoller {
     this.polling = false;
     this.lastError = null;
     this.lastUpdateAt = null;
+    this.activeRequests = new Map(); // chat_id -> AbortController
   }
 
   resolveProject() {
@@ -356,7 +391,19 @@ class ChannelPoller {
         ? "@" + msg.from.username
         : `${msg.from?.first_name || ""} ${msg.from?.last_name || ""}`.trim() || "unknown";
     const chat_id = msg.chat?.id;
-    const text = msg.text || msg.caption || "";
+
+    // Default Interrupt: abort any running request for this chat_id
+    if (chat_id) {
+      const prev = this.activeRequests.get(chat_id);
+      if (prev) {
+        this.log(`telegram[${this.channel.name}] interrupting previous request for chat ${chat_id}`);
+        prev.abort();
+      }
+    }
+    const abortCtrl = new AbortController();
+    if (chat_id) this.activeRequests.set(chat_id, abortCtrl);
+
+    let text = msg.text || msg.caption || "";
 
     // ── Incoming photo handling ───────────────────────────────────────────
     if (msg.photo && msg.photo.length > 0) {
@@ -583,16 +630,22 @@ class ChannelPoller {
           prompt: text,
           previousMessages,
           contextNote: `You are replying inside Telegram right now. Telegram channel="${this.channel.name}", author=${author}, chat_id=${chat_id}. Keep the reply plain-text and concise. Previous turns of this chat are included only for local conversational context; re-call tools for facts.`,
+          signal: abortCtrl.signal,
         });
         replyText = sa.text;
         replyAuthor = sa.name;
         saTrace = sa.trace;
         saUsage = sa.usage;
       } catch (e) {
+        if (abortCtrl.signal.aborted) {
+          this.log(`telegram[${this.channel.name}] request aborted for chat ${chat_id}`);
+          return; // don't send reply if aborted
+        }
         this.log(`telegram[${this.channel.name}] super-agent failed: ${e.message}`);
       }
     }
 
+    if (chat_id) this.activeRequests.delete(chat_id);
     if (!replyText) {
       stopTyping();
       return;
@@ -724,6 +777,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 +909,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