@foxden-app/foxclaw 0.5.51 → 0.5.52

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.52 - 2026-06-20
+
+### 中文
+- 新增 `telegram-voice-delivery` Codex Skill；FoxClaw 启动时会把它同步到每个 Telegram runtime 的 `CODEX_HOME`，Codex 生成音频后可自动投递到当前 Telegram 私聊，不再要求用户输入 `/voice file`。
+- 新增 `foxclaw send-voice <path> [caption]` CLI；它会从当前 `CODEX_HOME` 识别 bot，并从 FoxClaw 本地数据库读取该 bot 最近记录的私聊目标。
+- CLI 支持 `--bot-id`、`--chat-id` 显式覆盖，复用 Telegram voice 的格式和 50MB 限制，并且不会输出或暴露 bot token。
+
+### English
+- Added the `telegram-voice-delivery` Codex skill. FoxClaw syncs it into every Telegram runtime's `CODEX_HOME` at startup, allowing Codex to automatically deliver generated audio to the current Telegram private chat without asking the user to enter `/voice file`.
+- Added `foxclaw send-voice <path> [caption]`; it infers the bot from the current `CODEX_HOME` and reads that bot's most recently remembered private chat from the FoxClaw store.
+- The CLI supports explicit `--bot-id` and `--chat-id` overrides, reuses Telegram voice format and 50MB limits, and never prints bot tokens.
+
 ## 0.5.51 - 2026-06-20
 
 ### 中文

package/README.md

@@ -310,7 +310,7 @@ foxclaw weixin-login
 
 ## Codex Skill
 
-仓库自带一个 Codex skill。用法看 [FoxClaw Skill 中文说明](./docs/zh/foxclaw-skill.md)。它可以让 Codex 通过 SSH 在本机或远程 Mac 上 bootstrap FoxClaw——写 `.env`、构建、跑 doctor、装 launchd、引导首次消息验证，一条龙。
+仓库自带 FoxClaw 安装维护 Skill 和 `telegram-voice-delivery` 语音投递 Skill。用法看 [FoxClaw Skill 中文说明](./docs/zh/foxclaw-skill.md)。FoxClaw 启动时会把语音投递 Skill 自动同步到每个 Telegram runtime 的 `CODEX_HOME`；Codex 生成音频后可直接执行 `foxclaw send-voice`，自动把文件送回当前 Telegram 私聊，无需用户再输入 `/voice file`。
 
 ## 故障排查
 

package/README_EN.md

@@ -310,7 +310,7 @@ Weixin runtime files default to `~/.foxclaw/weixin`. When `TG_BOT_TOKENS` is ena
 
 ## Codex Skill
 
-This repo ships a Codex skill at [`skills/foxclaw`](./skills/foxclaw). Use it when you want Codex to bootstrap FoxClaw locally or on another Mac over SSH — write `.env`, build, run doctor, install launchd, and guide first-message validation.
+This repo ships the FoxClaw deployment skill and a [`telegram-voice-delivery`](./skills/telegram-voice-delivery) skill. FoxClaw automatically syncs the delivery skill into every Telegram runtime's `CODEX_HOME` at startup. Codex can then run `foxclaw send-voice` after generating audio and deliver the file to the current Telegram private chat without asking the user to enter `/voice file`.
 
 ## Troubleshooting
 

package/dist/codex_skills.d.ts

@@ -0,0 +1 @@
+export declare function installBundledCodexSkills(packageRoot: string, codexHome: string): string[];

package/dist/codex_skills.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const BUNDLED_CODEX_SKILLS = ['telegram-voice-delivery'];
+export function installBundledCodexSkills(packageRoot, codexHome) {
+    const installed = [];
+    for (const skillName of BUNDLED_CODEX_SKILLS) {
+        const sourceDir = path.join(packageRoot, 'skills', skillName);
+        if (!fs.existsSync(path.join(sourceDir, 'SKILL.md')))
+            continue;
+        const destinationDir = path.join(codexHome, 'skills', skillName);
+        fs.mkdirSync(destinationDir, { recursive: true, mode: 0o700 });
+        fs.cpSync(sourceDir, destinationDir, { recursive: true, force: true });
+        installed.push(skillName);
+    }
+    return installed;
+}

package/dist/controller/controller.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { TELEGRAM_VOICE_MAX_BYTES, TELEGRAM_VOICE_SUPPORTED_EXTENSIONS, telegramVoiceContentType, } from '../voice/files.js';
 import { normalizeLocale, t } from '../i18n.js';
 import { chatGptAuthMetadataMatchesCandidateName, parseChatGptAuthMetadata, readChatGptAuthRecord, readChatGptAuthMetadata, } from '../auth/mirror.js';
 import { readAccessTokenExpiresAtMs } from '../auth/cross_node_sync.js';
@@ -5205,7 +5206,7 @@ export class BridgeSessionCore {
         if (!contentType) {
             await this.sendMessage(scopeId, locale === 'zh'
                 ? '只支持作为 Telegram voice 发送的音频格式：.ogg、.opus、.oga、.mp3、.m4a。'
-                : 'Supported Telegram voice file formats: .ogg, .opus, .oga, .mp3, .m4a.');
+                : `Supported Telegram voice file formats: ${TELEGRAM_VOICE_SUPPORTED_EXTENSIONS}.`);
             return;
         }
         const stat = await fs.stat(filePath).catch(() => null);
@@ -5213,7 +5214,7 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, locale === 'zh' ? `找不到音频文件：${filePath}` : `Audio file not found: ${filePath}`);
             return;
         }
-        if (stat.size > 50 * 1024 * 1024) {
+        if (stat.size > TELEGRAM_VOICE_MAX_BYTES) {
             await this.sendMessage(scopeId, locale === 'zh' ? 'Telegram voice 文件不能超过 50MB。' : 'Telegram voice files must be 50MB or smaller.');
             return;
         }
@@ -8496,21 +8497,6 @@ function ensureTurnSegment(active, itemId, phase, outputKind, isPlan) {
     active.segments.push(segment);
     return segment;
 }
-function telegramVoiceContentType(filePath) {
-    const extension = path.extname(filePath).toLowerCase();
-    switch (extension) {
-        case '.ogg':
-        case '.oga':
-        case '.opus':
-            return 'audio/ogg';
-        case '.mp3':
-            return 'audio/mpeg';
-        case '.m4a':
-            return 'audio/mp4';
-        default:
-            return null;
-    }
-}
 function renderCollapsedCommentary(locale, segments) {
     const firstAt = segments[0]?.startedAtMs ?? Date.now();
     const lastSegment = segments[segments.length - 1];

package/dist/main.js

@@ -9,11 +9,13 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
 import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
+import { installBundledCodexSkills } from './codex_skills.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
 import { readRuntimeStatus, writeRuntimeStatus } from './runtime.js';
 import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from './launchd.js';
 import { buildFoxclawSystemdUnitText, buildSystemdRestartHelperArgs, cgroupContainsSystemdUnit, refreshFoxclawExecStartDropIns, removeFoxclawExecStartDropIns, } from './systemd.js';
 import { clearPendingClusterUpdateBroadcast, createSelfUpdateRuntime, inferPnpmHomeFromEntryPoint, performSelfUpdate, readPendingClusterUpdateBroadcast, readSelfUpdateStatus, writeSelfUpdateStatus, } from './update.js';
+import { TELEGRAM_VOICE_MAX_BYTES, TELEGRAM_VOICE_SUPPORTED_EXTENSIONS, telegramVoiceContentType, } from './voice/files.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -227,6 +229,11 @@ async function main() {
         await runWeixinLoginCli();
         return;
     }
+    if (command === 'send-voice' || command === 'voice-file') {
+        requireNode24(command);
+        await runSendVoiceCli();
+        return;
+    }
     if (command !== 'serve') {
         console.error(`Unknown command: ${command}`);
         printUsage();
@@ -263,12 +270,109 @@ Usage:
   foxclaw status
   foxclaw start|restart|stop
   foxclaw update
+  foxclaw send-voice <path> [caption]
   foxclaw install-systemd|uninstall-systemd
   foxclaw install-launchd|uninstall-launchd
   foxclaw weixin-login [account-id]
   foxclaw --version
   foxclaw --help`);
 }
+async function runSendVoiceCli() {
+    const parsed = parseSendVoiceCliArgs(process.argv.slice(3));
+    if (!parsed.fileArg) {
+        console.error('Usage: foxclaw send-voice <path> [caption] [--bot-id <bot-id>] [--chat-id <chat-id>]');
+        process.exitCode = 1;
+        return;
+    }
+    const config = loadConfig();
+    const filePath = path.resolve(config.defaultCwd, parsed.fileArg);
+    const contentType = telegramVoiceContentType(filePath);
+    if (!contentType) {
+        throw new Error(`Unsupported Telegram voice file format. Supported formats: ${TELEGRAM_VOICE_SUPPORTED_EXTENSIONS}.`);
+    }
+    const stat = await fs.promises.stat(filePath).catch(() => null);
+    if (!stat?.isFile()) {
+        throw new Error(`Audio file not found: ${filePath}`);
+    }
+    if (stat.size > TELEGRAM_VOICE_MAX_BYTES) {
+        throw new Error('Telegram voice files must be 50MB or smaller.');
+    }
+    const botId = parsed.botId ?? inferTelegramBotId(process.env.CODEX_HOME) ?? inferTelegramBotId(config.codexHome);
+    const botToken = resolveTelegramBotToken(config.tgBotTokens, botId);
+    const { BridgeStore } = await import('./store/database.js');
+    const store = new BridgeStore(config.storePath);
+    let chatId = parsed.chatId;
+    try {
+        chatId ??= botId ? store.getTelegramPrivateScope(botId)?.chatId ?? null : null;
+    }
+    finally {
+        store.close();
+    }
+    if (!chatId) {
+        const target = botId ? ` for ${botId}` : '';
+        throw new Error(`No remembered Telegram private chat${target}. Send /status to the bot once, or pass --chat-id <chat-id>.`);
+    }
+    const contents = await fs.promises.readFile(filePath);
+    const { callTelegramMultipartApi } = await import('./telegram/api.js');
+    const result = await callTelegramMultipartApi(botToken, 'sendVoice', {
+        chat_id: chatId,
+        caption: parsed.caption || 'FoxClaw voice',
+    }, [{
+            fieldName: 'voice',
+            filename: path.basename(filePath),
+            contents,
+            contentType,
+        }]);
+    if (!result.ok || !result.result) {
+        throw new Error(result.description || 'Telegram sendVoice failed.');
+    }
+    console.log(`Sent Telegram voice message ${result.result.message_id}: ${filePath}`);
+}
+function parseSendVoiceCliArgs(args) {
+    const positional = [];
+    let botId = null;
+    let chatId = null;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--bot-id' || arg === '--chat-id') {
+            const value = args[index + 1]?.trim();
+            if (!value) {
+                throw new Error(`${arg} requires a value.`);
+            }
+            if (arg === '--bot-id')
+                botId = value;
+            else
+                chatId = value;
+            index += 1;
+            continue;
+        }
+        positional.push(arg);
+    }
+    return {
+        fileArg: positional[0]?.trim() || null,
+        caption: positional.slice(1).join(' ').trim(),
+        botId,
+        chatId,
+    };
+}
+function inferTelegramBotId(codexHome) {
+    if (!codexHome)
+        return null;
+    const match = codexHome.match(/(?:^|[\\/])(bot\d+)(?:[\\/]|$)/i);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+function resolveTelegramBotToken(tokens, botId) {
+    if (botId) {
+        const numericId = botId.replace(/^bot/i, '');
+        const matched = tokens.find(token => token.startsWith(`${numericId}:`));
+        if (matched)
+            return matched;
+        throw new Error(`No configured Telegram token matches ${botId}. Pass --bot-id for a configured bot.`);
+    }
+    if (tokens.length === 1)
+        return tokens[0];
+    throw new Error('Cannot infer the Telegram bot from this Codex session. Pass --bot-id <bot-id>.');
+}
 function formatRuntimeStatusSummary(status) {
     const lines = [];
     const age = formatAge(status.updatedAt);
@@ -388,6 +492,7 @@ async function runServeCli() {
                 if (!sharedDefaultRuntime) {
                     fs.mkdirSync(home, { recursive: true, mode: 0o700 });
                 }
+                installBundledCodexSkills(packageRoot, home);
                 const runtimeConfig = {
                     ...config,
                     tgBotToken: token,
@@ -670,6 +775,8 @@ async function runServeCli() {
             process.on('SIGTERM', () => void shutdown('SIGTERM'));
             return;
         }
+        const singleCodexHome = config.codexHome ?? path.join(os.homedir(), '.codex');
+        installBundledCodexSkills(packageRoot, singleCodexHome);
         const bot = new TelegramGateway(config.tgBotToken, config.tgAllowedUserId, config.tgAllowedChatId, config.telegramPollIntervalMs, store, logger);
         const app = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger);
         const telegramMessaging = new TelegramMessagingPort(bot);

package/dist/voice/files.d.ts

@@ -0,0 +1,3 @@
+export declare const TELEGRAM_VOICE_MAX_BYTES: number;
+export declare const TELEGRAM_VOICE_SUPPORTED_EXTENSIONS = ".ogg, .opus, .oga, .mp3, .m4a";
+export declare function telegramVoiceContentType(filePath: string): string | null;

package/dist/voice/files.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+export const TELEGRAM_VOICE_MAX_BYTES = 50 * 1024 * 1024;
+export const TELEGRAM_VOICE_SUPPORTED_EXTENSIONS = '.ogg, .opus, .oga, .mp3, .m4a';
+export function telegramVoiceContentType(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    switch (extension) {
+        case '.ogg':
+        case '.oga':
+        case '.opus':
+            return 'audio/ogg';
+        case '.mp3':
+            return 'audio/mpeg';
+        case '.m4a':
+            return 'audio/mp4';
+        default:
+            return null;
+    }
+}

package/docs/zh/foxclaw-skill.md

@@ -2,6 +2,8 @@
 
 仓库内置的 `skills/foxclaw` 是给 Codex 使用的安装技能。它的用途是让 Codex 在本机或远程 Mac 上自动完成 FoxClaw bootstrap，包括写 `.env`、安装依赖、构建、跑 `doctor`、安装 launchd 服务，并引导你完成第一次 Telegram 消息验证。
 
+仓库还内置 `skills/telegram-voice-delivery`。FoxClaw 启动时会把它自动同步到每个 Telegram runtime 的 `CODEX_HOME`。当 Codex 已经生成音频时，它会直接运行 `foxclaw send-voice <path> [caption]`，从当前 `CODEX_HOME` 识别 Telegram bot，并将音频投递到该 bot 最近记录的私聊，不需要用户再输入命令。
+
 ## 适合什么时候用
 
 - 你想让 Codex 通过 SSH 帮另一台 Mac 安装 FoxClaw。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.51",
+  "version": "0.5.52",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",

package/skills/telegram-voice-delivery/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: telegram-voice-delivery
+description: Deliver an audio file from Codex to the current Telegram conversation through FoxClaw. Use when Codex has generated or found speech, narration, a podcast, or another audio file that the user should receive in Telegram without manually running a FoxClaw command.
+---
+
+# Telegram Voice Delivery
+
+Send completed audio artifacts back to the active FoxClaw Telegram conversation without asking the user to operate `/voice`.
+
+## Workflow
+
+1. Finish generating the audio file before attempting delivery.
+2. Prefer `.ogg` or `.opus` for Telegram voice playback. `.oga`, `.mp3`, and `.m4a` are also accepted.
+3. Keep the file at or below 50MB.
+4. Run:
+
+```bash
+foxclaw send-voice "/absolute/path/to/audio.ogg" "Short caption"
+```
+
+5. Treat a successful command as delivery confirmation and tell the user the audio was sent.
+
+FoxClaw infers the current Telegram bot from `CODEX_HOME`, reads that bot's remembered private chat from its local store, and calls Telegram `sendVoice`. Do not read, print, or expose Telegram bot tokens.
+
+If an audio file already exists, send it directly instead of regenerating it. If FoxClaw reports that no private chat is remembered, ask the user to send `/status` to that bot once; use `--bot-id <bot-id>` or `--chat-id <chat-id>` only when automatic session inference is unavailable.

package/skills/telegram-voice-delivery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Telegram Voice Delivery"
+  short_description: "Send generated audio back through FoxClaw"
+  default_prompt: "Use $telegram-voice-delivery to send a completed audio file to the current Telegram conversation through FoxClaw."