metame-cli 1.3.5 → 1.3.7

package/README.md

@@ -182,6 +182,27 @@ Each chat gets a persistent session via `claude -p --resume <session-id>`. This
 
 **Parallel request handling:** The daemon uses async spawning, so multiple users or overlapping requests don't block each other. Each Claude call runs in a non-blocking subprocess.
 
+**Streaming status (v1.3.7):** See Claude's work progress in real-time on your phone:
+
+```
+📖 Read: 「config.yaml」
+✏️ Edit: 「daemon.js」
+💻 Bash: 「git status」
+```
+
+**File sending (v1.3.7):** Ask Claude to send any file to your phone:
+
+```
+You: 把 report.md 发过来
+Claude: 请查收~!
+        [📎 report.md]  ← tap to download
+```
+
+Works for documents, audio, images, etc. Click button to download. Links valid for 30 minutes.
+
+- **Telegram:** Works out of the box
+- **Feishu:** Requires `im:resource` permission in app settings
+
 **Other commands:**
 
 | Command | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "metame-cli",
-    "version": "1.3.5",
+    "version": "1.3.7",
     "description": "The Cognitive Profile Layer for Claude Code. Knows how you think, not just what you said.",
     "main": "index.js",
     "bin": {

package/scripts/daemon-default.yaml

@@ -47,3 +47,10 @@ budget:
 daemon:
   log_max_size: 1048576
   heartbeat_check_interval: 60
+  # Pre-authorize tools for mobile sessions (no permission prompts)
+  # Examples: "Bash(git:*)" "Bash(npm:*)" "Edit" "Write" "WebFetch" "WebSearch"
+  session_allowed_tools:
+    - "WebFetch"
+    - "WebSearch"
+    - "Bash(git:*)"
+    - "Bash(npm:*)"

package/scripts/daemon.js

@@ -655,6 +655,36 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
     return;
   }
 
+  // /file <shortId> — send cached file (from button callback)
+  if (text.startsWith('/file ')) {
+    const shortId = text.slice(6).trim();
+    const filePath = getCachedFile(shortId);
+    if (!filePath) {
+      await bot.sendMessage(chatId, '⏰ 文件链接已过期，请重新生成');
+      return;
+    }
+    if (!fs.existsSync(filePath)) {
+      await bot.sendMessage(chatId, '❌ 文件不存在');
+      return;
+    }
+    if (bot.sendFile) {
+      try {
+        // Insert zero-width space before extension to prevent link parsing
+        const basename = path.basename(filePath);
+        const dotIdx = basename.lastIndexOf('.');
+        const safeBasename = dotIdx > 0 ? basename.slice(0, dotIdx) + '\u200B' + basename.slice(dotIdx) : basename;
+        await bot.sendMessage(chatId, `⏳ 正在发送「${safeBasename}」...`);
+        await bot.sendFile(chatId, filePath);
+      } catch (e) {
+        log('ERROR', `File send failed: ${e.message}`);
+        await bot.sendMessage(chatId, `❌ 发送失败: ${e.message.slice(0, 100)}`);
+      }
+    } else {
+      await bot.sendMessage(chatId, '❌ 当前平台不支持文件发送');
+    }
+    return;
+  }
+
   // /last — smart resume: prefer current cwd, then most recent globally
   if (text === '/last') {
     const curSession = getSession(chatId);
@@ -904,17 +934,22 @@ async function handleCommand(bot, chatId, text, config, executeTaskByName) {
 
   if (text.startsWith('/')) {
     await bot.sendMessage(chatId, [
-      'Commands:',
-      '/last — ⚡ 一键继续最近的 session',
-      '/new [path] [name] — new session',
-      '/resume [name] — 选择/搜索 session',
-      '/continue — resume last in current dir',
-      '/name <name> — name current session',
-      '/cd <path|last> — change workdir (last=最近目录)',
-      '/session — current session info',
-      '/status /tasks /budget /reload',
+      '📱 手机端 Claude Code',
+      '',
+      '⚡ 快速同步电脑工作:',
+      '/last — 继续电脑上最近的对话',
+      '/cd last — 切到电脑最近的项目目录',
+      '',
+      '📂 Session 管理:',
+      '/new [path] [name] — 新建会话',
+      '/resume [name] — 选择/恢复会话',
+      '/name <name> — 命名当前会话',
+      '/cd <path> — 切换工作目录',
+      '/session — 查看当前会话',
       '',
-      'Or just type naturally.',
+      '⚙️ /status /tasks /budget /reload',
+      '',
+      '直接打字即可对话 💬',
     ].join('\n'));
     return;
   }
@@ -947,17 +982,64 @@ function listRecentSessions(limit, cwd) {
   try {
     if (!fs.existsSync(CLAUDE_PROJECTS_DIR)) return [];
     const projects = fs.readdirSync(CLAUDE_PROJECTS_DIR);
-    let all = [];
+
+    // Build a map: sessionId -> entry (for deduplication)
+    const sessionMap = new Map();
+    // Cache: projDirName -> real projectPath (from index)
+    const projPathCache = new Map();
+
     for (const proj of projects) {
-      const indexFile = path.join(CLAUDE_PROJECTS_DIR, proj, 'sessions-index.json');
+      const projDir = path.join(CLAUDE_PROJECTS_DIR, proj);
+
+      // 1. Read from sessions-index.json (Claude's native index)
+      const indexFile = path.join(projDir, 'sessions-index.json');
+      try {
+        if (fs.existsSync(indexFile)) {
+          const data = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
+          if (data.entries && data.entries.length > 0) {
+            // Cache the real projectPath from any indexed session
+            const realPath = data.entries[0].projectPath;
+            if (realPath) projPathCache.set(proj, realPath);
+
+            for (const entry of data.entries) {
+              if (entry.messageCount >= 1) {
+                sessionMap.set(entry.sessionId, entry);
+              }
+            }
+          }
+        }
+      } catch { /* skip */ }
+
+      // 2. Direct scan of .jsonl files (hot reload: catches sessions not yet indexed)
       try {
-        if (!fs.existsSync(indexFile)) continue;
-        const data = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
-        if (data.entries) all = all.concat(data.entries);
+        const files = fs.readdirSync(projDir).filter(f => f.endsWith('.jsonl'));
+        for (const file of files) {
+          const sessionId = file.replace('.jsonl', '');
+          const filePath = path.join(projDir, file);
+          const stat = fs.statSync(filePath);
+          const fileMtime = stat.mtimeMs;
+
+          // Only add if not already in map, or if file is newer
+          const existing = sessionMap.get(sessionId);
+          if (!existing || fileMtime > (existing.fileMtime || 0)) {
+            // Use cached real projectPath, or fall back to lossy decode
+            const projectPath = projPathCache.get(proj) || proj.slice(1).replace(/-/g, '/');
+            sessionMap.set(sessionId, {
+              sessionId,
+              projectPath,
+              fileMtime,
+              modified: new Date(fileMtime).toISOString(),
+              messageCount: 1, // Assume at least 1 if file exists
+              ...(existing || {}), // Preserve existing metadata like customTitle
+              fileMtime, // Override with real mtime
+            });
+          }
+        }
       } catch { /* skip */ }
     }
-    // Filter: must have at least 1 message
-    all = all.filter(s => s.messageCount >= 1);
+
+    let all = Array.from(sessionMap.values());
+
     // Filter by cwd if provided
     if (cwd) {
       const matched = all.filter(s => s.projectPath === cwd);
@@ -1218,6 +1300,205 @@ function spawnClaudeAsync(args, input, cwd, timeoutMs = 300000) {
   });
 }
 
+/**
+ * Tool name to emoji mapping for status display
+ */
+const TOOL_EMOJI = {
+  Read: '📖',
+  Edit: '✏️',
+  Write: '📝',
+  Bash: '💻',
+  Glob: '🔍',
+  Grep: '🔎',
+  WebFetch: '🌐',
+  WebSearch: '🔍',
+  Task: '🤖',
+  default: '🔧',
+};
+
+// Content file extensions (user-facing files, not code/config)
+const CONTENT_EXTENSIONS = new Set([
+  '.md', '.txt', '.rtf',                          // Text
+  '.doc', '.docx', '.pdf', '.odt',                // Documents
+  '.wav', '.mp3', '.m4a', '.ogg', '.flac',        // Audio
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', // Images
+  '.mp4', '.mov', '.avi', '.webm',                // Video
+  '.csv', '.xlsx', '.xls',                        // Data
+  '.html', '.htm',                                // Web content
+]);
+
+// File cache for button callbacks (shortId -> fullPath)
+const fileCache = new Map();
+const FILE_CACHE_TTL = 1800000; // 30 minutes
+
+function cacheFile(filePath) {
+  const shortId = Math.random().toString(36).slice(2, 10);
+  fileCache.set(shortId, { path: filePath, expires: Date.now() + FILE_CACHE_TTL });
+  return shortId;
+}
+
+function getCachedFile(shortId) {
+  const entry = fileCache.get(shortId);
+  if (!entry) return null;
+  if (Date.now() > entry.expires) {
+    fileCache.delete(shortId);
+    return null;
+  }
+  return entry.path;
+}
+
+function isContentFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return CONTENT_EXTENSIONS.has(ext);
+}
+
+/**
+ * Spawn claude with streaming output (stream-json mode).
+ * Calls onStatus callback when tool usage is detected.
+ * Returns { output, error } after process exits.
+ */
+function spawnClaudeStreaming(args, input, cwd, onStatus, timeoutMs = 600000) {
+  return new Promise((resolve) => {
+    // Add stream-json output format (requires --verbose)
+    const streamArgs = [...args, '--output-format', 'stream-json', '--verbose'];
+
+    const child = spawn('claude', streamArgs, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+
+    let buffer = '';
+    let stderr = '';
+    let killed = false;
+    let finalResult = '';
+    let lastStatusTime = 0;
+    const STATUS_THROTTLE = 3000; // Min 3s between status updates
+    const writtenFiles = []; // Track files created/modified by Write tool
+
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill('SIGTERM');
+    }, timeoutMs);
+
+    child.stdout.on('data', (data) => {
+      buffer += data.toString();
+
+      // Process complete JSON lines
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const event = JSON.parse(line);
+
+          // Extract final result text
+          if (event.type === 'assistant' && event.message?.content) {
+            const textBlocks = event.message.content.filter(b => b.type === 'text');
+            if (textBlocks.length > 0) {
+              finalResult = textBlocks.map(b => b.text).join('\n');
+            }
+          }
+
+          // Detect tool usage and send status
+          if (event.type === 'assistant' && event.message?.content) {
+            for (const block of event.message.content) {
+              if (block.type === 'tool_use') {
+                const toolName = block.name || 'Tool';
+
+                // Track files written by Write tool
+                if (toolName === 'Write' && block.input?.file_path) {
+                  const filePath = block.input.file_path;
+                  if (!writtenFiles.includes(filePath)) {
+                    writtenFiles.push(filePath);
+                  }
+                }
+
+                const now = Date.now();
+                if (now - lastStatusTime >= STATUS_THROTTLE) {
+                  lastStatusTime = now;
+                  const emoji = TOOL_EMOJI[toolName] || TOOL_EMOJI.default;
+
+                  // Extract brief context from tool input
+                  let context = '';
+                  if (block.input) {
+                    if (block.input.file_path) {
+                      // Insert zero-width space before extension to prevent link parsing
+                      const basename = path.basename(block.input.file_path);
+                      const dotIdx = basename.lastIndexOf('.');
+                      context = dotIdx > 0 ? basename.slice(0, dotIdx) + '\u200B' + basename.slice(dotIdx) : basename;
+                    } else if (block.input.command) {
+                      context = block.input.command.slice(0, 30);
+                      if (block.input.command.length > 30) context += '...';
+                    } else if (block.input.pattern) {
+                      context = block.input.pattern.slice(0, 20);
+                    } else if (block.input.query) {
+                      context = block.input.query.slice(0, 25);
+                    } else if (block.input.url) {
+                      try {
+                        context = new URL(block.input.url).hostname;
+                      } catch { context = 'web'; }
+                    }
+                  }
+
+                  const status = context
+                    ? `${emoji} ${toolName}: 「${context}」`
+                    : `${emoji} ${toolName}...`;
+
+                  if (onStatus) {
+                    onStatus(status).catch(() => {});
+                  }
+                }
+              }
+            }
+          }
+
+          // Also check for result message type
+          if (event.type === 'result' && event.result) {
+            finalResult = event.result;
+          }
+        } catch {
+          // Not valid JSON, ignore
+        }
+      }
+    });
+
+    child.stderr.on('data', (data) => { stderr += data.toString(); });
+
+    child.on('close', (code) => {
+      clearTimeout(timer);
+
+      // Process any remaining buffer
+      if (buffer.trim()) {
+        try {
+          const event = JSON.parse(buffer);
+          if (event.type === 'result' && event.result) {
+            finalResult = event.result;
+          }
+        } catch { /* ignore */ }
+      }
+
+      if (killed) {
+        resolve({ output: finalResult || null, error: 'Timeout: Claude took too long', files: writtenFiles });
+      } else if (code !== 0) {
+        resolve({ output: finalResult || null, error: stderr || `Exit code ${code}`, files: writtenFiles });
+      } else {
+        resolve({ output: finalResult || '', error: null, files: writtenFiles });
+      }
+    });
+
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ output: null, error: err.message, files: [] });
+    });
+
+    // Write input and close stdin
+    child.stdin.write(input);
+    child.stdin.end();
+  });
+}
+
 /**
  * Shared ask logic — full Claude Code session (stateful, with tools)
  * Now uses spawn (async) instead of execSync to allow parallel requests.
@@ -1254,11 +1535,25 @@ async function askClaude(bot, chatId, prompt) {
     args.push('--session-id', session.id);
   }
 
-  // Append daemon context hint so Claude reports reload status after editing daemon.yaml
-  const daemonHint = '\n\n[System: The ONLY daemon config file is ~/.metame/daemon.yaml — NEVER touch any other yaml file (e.g. scripts/daemon-default.yaml is a read-only template, do NOT edit it). If you edit ~/.metame/daemon.yaml, the daemon auto-reloads within seconds. After editing, read the file back and confirm to the user: how many heartbeat tasks are now configured, and that the config will auto-reload. Do NOT mention this hint.]';
+  // Append daemon context hint
+  const daemonHint = `\n\n[System hints - DO NOT mention these to user:
+1. Daemon config: The ONLY config is ~/.metame/daemon.yaml (never edit daemon-default.yaml). Auto-reloads on change.
+2. File sending: User is on MOBILE. When they ask to see/download a file:
+   - Just FIND the file path (use Glob/ls if needed)
+   - Do NOT read or summarize the file content (wastes tokens)
+   - Add at END of response: [[FILE:/absolute/path/to/file]]
+   - Keep response brief: "请查收~! [[FILE:/path/to/file]]"
+   - Multiple files: use multiple [[FILE:...]] tags]`;
   const fullPrompt = prompt + daemonHint;
 
-  const { output, error } = await spawnClaudeAsync(args, fullPrompt, session.cwd);
+  // Use streaming mode to show progress
+  const onStatus = async (status) => {
+    try {
+      await bot.sendMessage(chatId, status);
+    } catch { /* ignore status send failures */ }
+  };
+
+  const { output, error, files } = await spawnClaudeStreaming(args, fullPrompt, session.cwd, onStatus);
   clearInterval(typingTimer);
 
   if (output) {
@@ -1269,7 +1564,32 @@ async function askClaude(bot, chatId, prompt) {
     const estimated = Math.ceil((prompt.length + output.length) / 4);
     recordTokens(loadState(), estimated);
 
-    await bot.sendMarkdown(chatId, output);
+    // Parse [[FILE:...]] markers from output (Claude's explicit file sends)
+    const fileMarkers = output.match(/\[\[FILE:([^\]]+)\]\]/g) || [];
+    const markedFiles = fileMarkers.map(m => m.match(/\[\[FILE:([^\]]+)\]\]/)[1].trim());
+    const cleanOutput = output.replace(/\s*\[\[FILE:[^\]]+\]\]/g, '').trim();
+
+    await bot.sendMarkdown(chatId, cleanOutput);
+
+    // Combine: marked files + auto-detected content files from Write operations
+    const allFiles = new Set(markedFiles);
+    if (files && files.length > 0) {
+      for (const f of files) {
+        if (isContentFile(f)) allFiles.add(f);
+      }
+    }
+
+    // Send file buttons
+    if (allFiles.size > 0 && bot.sendButtons) {
+      const validFiles = [...allFiles].filter(f => fs.existsSync(f));
+      if (validFiles.length > 0) {
+        const buttons = validFiles.map(filePath => {
+          const shortId = cacheFile(filePath);
+          return [{ text: `📎 ${path.basename(filePath)}`, callback_data: `/file ${shortId}` }];
+        });
+        await bot.sendButtons(chatId, '📂 文件:', buttons);
+      }
+    }
 
     // Auto-name: if this was the first message and session has no name, generate one
     if (wasNew && !getSessionName(session.id)) {
@@ -1287,10 +1607,31 @@ async function askClaude(bot, chatId, prompt) {
       const retryArgs = ['-p', '--session-id', session.id];
       for (const tool of sessionAllowed) retryArgs.push('--allowedTools', tool);
 
-      const retry = await spawnClaudeAsync(retryArgs, prompt, session.cwd);
+      const retry = await spawnClaudeStreaming(retryArgs, prompt, session.cwd, onStatus);
       if (retry.output) {
         markSessionStarted(chatId);
-        await bot.sendMarkdown(chatId, retry.output);
+        // Parse [[FILE:...]] markers
+        const retryFileMarkers = retry.output.match(/\[\[FILE:([^\]]+)\]\]/g) || [];
+        const retryMarkedFiles = retryFileMarkers.map(m => m.match(/\[\[FILE:([^\]]+)\]\]/)[1].trim());
+        const retryCleanOutput = retry.output.replace(/\s*\[\[FILE:[^\]]+\]\]/g, '').trim();
+        await bot.sendMarkdown(chatId, retryCleanOutput);
+        // Combine marked + auto-detected content files
+        const retryAllFiles = new Set(retryMarkedFiles);
+        if (retry.files && retry.files.length > 0) {
+          for (const f of retry.files) {
+            if (isContentFile(f)) retryAllFiles.add(f);
+          }
+        }
+        if (retryAllFiles.size > 0 && bot.sendButtons) {
+          const validFiles = [...retryAllFiles].filter(f => fs.existsSync(f));
+          if (validFiles.length > 0) {
+            const buttons = validFiles.map(filePath => {
+              const shortId = cacheFile(filePath);
+              return [{ text: `📎 ${path.basename(filePath)}`, callback_data: `/file ${shortId}` }];
+            });
+            await bot.sendButtons(chatId, '📂 文件:', buttons);
+          }
+        }
       } else {
         log('ERROR', `askClaude retry failed: ${(retry.error || '').slice(0, 200)}`);
         try { await bot.sendMessage(chatId, `Error: ${(retry.error || '').slice(0, 200)}`); } catch { /* */ }

package/scripts/distill.js

@@ -174,7 +174,7 @@ Do NOT repeat existing unchanged values. Only output NEW or CHANGED fields.`;
     let result;
     try {
       result = execSync(
-        `claude -p --model haiku`,
+        `claude -p --model haiku --no-session-persistence`,
         {
           input: distillPrompt,
           encoding: 'utf8',
@@ -673,7 +673,7 @@ If no clear patterns found: respond with exactly NO_PATTERNS`;
 
   try {
     const result = execSync(
-      `claude -p --model haiku`,
+      `claude -p --model haiku --no-session-persistence`,
       {
         input: patternPrompt,
         encoding: 'utf8',

package/scripts/feishu-adapter.js

@@ -6,6 +6,9 @@
 
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
+
 let Lark;
 try {
   Lark = require('@larksuiteoapi/node-sdk');
@@ -108,6 +111,82 @@ function createBot(config) {
       return { app_id, app_name: 'MetaMe' };
     },
 
+    /**
+     * Send a file/document
+     * @param {string} chatId
+     * @param {string} filePath - Local file path
+     * @param {string} [caption] - Optional caption (sent as separate message)
+     */
+    async sendFile(chatId, filePath, caption) {
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+      }
+      const fileName = path.basename(filePath);
+      const fileSize = fs.statSync(filePath).size;
+
+      // For text files under 4KB, just send as text
+      const ext = path.extname(filePath).toLowerCase();
+      const isText = ['.md', '.txt', '.json', '.yaml', '.yml', '.csv'].includes(ext);
+      if (isText && fileSize < 4096) {
+        const content = fs.readFileSync(filePath, 'utf8');
+        await this.sendMessage(chatId, `📄 ${fileName}:\n\`\`\`\n${content}\n\`\`\``);
+        return;
+      }
+
+      // For larger/binary files, try file upload
+      try {
+        // Use ReadStream as per Feishu SDK docs
+        const fileStream = fs.createReadStream(filePath);
+
+        // 1. Upload file to Feishu
+        const uploadRes = await client.im.file.create({
+          data: {
+            file_type: 'stream',
+            file_name: fileName,
+            file: fileStream,
+          },
+        });
+
+        console.log('[Feishu] Upload response:', JSON.stringify(uploadRes));
+
+        // Response is { code, msg, data: { file_key } }
+        const fileKey = uploadRes?.data?.file_key || uploadRes?.file_key;
+        if (!fileKey) {
+          throw new Error(`No file_key in response: ${JSON.stringify(uploadRes)}`);
+        }
+
+        // 2. Send file message
+        await client.im.message.create({
+          params: { receive_id_type: 'chat_id' },
+          data: {
+            receive_id: chatId,
+            msg_type: 'file',
+            content: JSON.stringify({ file_key: fileKey }),
+          },
+        });
+      } catch (uploadErr) {
+        // Log detailed error
+        const errDetail = uploadErr.response?.data || uploadErr.message || uploadErr;
+        console.error('[Feishu] File upload error:', JSON.stringify(errDetail));
+
+        // Fallback: for text files, send content truncated
+        if (isText) {
+          const content = fs.readFileSync(filePath, 'utf8');
+          const truncated = content.length > 3000 ? content.slice(0, 3000) + '\n...(truncated)' : content;
+          await this.sendMessage(chatId, `📄 ${fileName}:\n\`\`\`\n${truncated}\n\`\`\``);
+        } else {
+          // For binary files, give more helpful error
+          const errMsg = errDetail?.msg || errDetail?.message || '上传失败';
+          throw new Error(`${errMsg} (请检查飞书应用权限: im:resource)`);
+        }
+      }
+
+      // 3. Send caption as separate message if provided
+      if (caption) {
+        await this.sendMessage(chatId, caption);
+      }
+    },
+
     /**
      * Start WebSocket long connection to receive messages
      * @param {function} onMessage - callback(chatId, text, event)

package/scripts/telegram-adapter.js

@@ -7,6 +7,8 @@
 'use strict';
 
 const https = require('https');
+const fs = require('fs');
+const path = require('path');
 
 const API_BASE = 'https://api.telegram.org';
 
@@ -169,6 +171,71 @@ function createBot(token) {
       });
     },
 
+    /**
+     * Send a file/document
+     * @param {number|string} chatId - Target chat ID
+     * @param {string} filePath - Local file path
+     * @param {string} [caption] - Optional caption
+     */
+    async sendFile(chatId, filePath, caption) {
+      if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+      }
+      const fileName = path.basename(filePath);
+      const fileContent = fs.readFileSync(filePath);
+      const boundary = '----MetaMeBoundary' + Date.now();
+
+      // Build multipart form-data
+      let body = '';
+      body += `--${boundary}\r\n`;
+      body += `Content-Disposition: form-data; name="chat_id"\r\n\r\n${chatId}\r\n`;
+      if (caption) {
+        body += `--${boundary}\r\n`;
+        body += `Content-Disposition: form-data; name="caption"\r\n\r\n${caption}\r\n`;
+      }
+      body += `--${boundary}\r\n`;
+      body += `Content-Disposition: form-data; name="document"; filename="${fileName}"\r\n`;
+      body += `Content-Type: application/octet-stream\r\n\r\n`;
+
+      const bodyStart = Buffer.from(body, 'utf8');
+      const bodyEnd = Buffer.from(`\r\n--${boundary}--\r\n`, 'utf8');
+      const fullBody = Buffer.concat([bodyStart, fileContent, bodyEnd]);
+
+      return new Promise((resolve, reject) => {
+        const url = `${API_BASE}/bot${token}/sendDocument`;
+        const urlObj = new URL(url);
+        const options = {
+          hostname: urlObj.hostname,
+          path: urlObj.pathname,
+          method: 'POST',
+          headers: {
+            'Content-Type': `multipart/form-data; boundary=${boundary}`,
+            'Content-Length': fullBody.length,
+          },
+          timeout: 60000,
+        };
+
+        const req = https.request(options, (res) => {
+          let data = '';
+          res.on('data', (chunk) => { data += chunk; });
+          res.on('end', () => {
+            try {
+              const parsed = JSON.parse(data);
+              if (parsed.ok) resolve(parsed.result);
+              else reject(new Error(`Telegram API error: ${parsed.description || 'unknown'}`));
+            } catch (e) {
+              reject(new Error(`Failed to parse response: ${e.message}`));
+            }
+          });
+        });
+
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('Upload timed out')); });
+        req.write(fullBody);
+        req.end();
+      });
+    },
+
 };
 }