@foxden-app/foxclaw 0.5.49 → 0.5.51

package/.env.example

@@ -72,7 +72,9 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # VOICE_TTS_SSH_DIR=/path/to/qwen-speech-server
 # VOICE_TTS_DESIGN_INSTRUCT=用自然清晰的中文女声朗读，语速适中。
 # VOICE_SUMMARY_BUTTON_ENABLED=true
+# VOICE_SUMMARY_TEXT_LIMIT=180
 # VOICE_TEXT_LIMIT=2800
+# VOICE_TTS_TIMEOUT_MS=120000
 
 # Optional: standard HTTP(S) proxy for Telegram and ChatGPT/Codex backend requests.
 # Put these in the same env file that `foxclaw start` installs into systemd/launchd.

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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.51 - 2026-06-20
+
+### 中文
+- 新增 `/voice file <path> [caption]`，可以把 Codex 已经生成好的本地音频文件直接作为 Telegram voice 发出去，不再重复 TTS。
+- 支持 `.ogg`、`.opus`、`.oga`、`.mp3`、`.m4a`，相对路径按 `DEFAULT_CWD` 解析，并限制 50MB 以内。
+- Telegram voice multipart 现在会按文件类型设置 content type，避免所有语音文件都被当成 `audio/ogg`。
+
+### English
+- Added `/voice file <path> [caption]` for sending an already-generated local audio file as a Telegram voice message without re-running TTS.
+- Supports `.ogg`, `.opus`, `.oga`, `.mp3`, and `.m4a`; relative paths resolve from `DEFAULT_CWD` and files are capped at 50MB.
+- Telegram voice multipart uploads now set content type by file type instead of treating every voice file as `audio/ogg`.
+
+## 0.5.50 - 2026-06-20
+
+### 中文
+- 给 Telegram “听总结”按钮增加独立的 `VOICE_SUMMARY_TEXT_LIMIT`，默认只朗读短摘要，避免把完整最终回复交给慢速 TTS 后端导致长时间排队或超时。
+- 新增 `VOICE_TTS_TIMEOUT_MS`，HTTP/SSH 语音后端共用该超时配置；SSH 超时会终止远端调用，HTTP 超时会中止请求。
+- `/voice <文本>` 仍使用 `VOICE_TEXT_LIMIT`，方便手动朗读较长文本；最终总结按钮走更短的摘要上限，优先保证可听、及时返回。
+
+### English
+- Added a separate `VOICE_SUMMARY_TEXT_LIMIT` for Telegram "Listen" buttons, so final-answer voice summaries read a short digest instead of sending the entire final response to slow TTS backends.
+- Added `VOICE_TTS_TIMEOUT_MS` for both HTTP and SSH voice backends; SSH calls are terminated on timeout and HTTP requests are aborted.
+- `/voice <text>` still uses `VOICE_TEXT_LIMIT` for manual longer reads, while final-answer buttons use the shorter summary limit for timely playback.
+
 ## 0.5.49 - 2026-06-20
 
 ### 中文

package/dist/channels/bridge_messaging_router.d.ts

@@ -17,7 +17,7 @@ export declare class BridgeMessagingRouter {
     sendHtml(scopeId: string, text: string, keyboard?: InlineKeyboard): Promise<number>;
     sendRichHtml(scopeId: string, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<number>;
     sendRichMarkdown(scopeId: string, markdown: string, fallbackText: string, keyboard?: InlineKeyboard): Promise<number>;
-    sendVoice(scopeId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
+    sendVoice(scopeId: string, filename: string, contents: Buffer, caption?: string, contentType?: string): Promise<number>;
     editPlain(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
     editHtml(scopeId: string, messageId: number, text: string, keyboard?: InlineKeyboard): Promise<void>;
     editRichHtml(scopeId: string, messageId: number, html: string, fallbackHtml: string, keyboard?: InlineKeyboard): Promise<void>;

package/dist/channels/bridge_messaging_router.js

@@ -49,11 +49,11 @@ export class BridgeMessagingRouter {
         }
         return this.telegram.sendRichMarkdown(scopeId, markdown, keyboard);
     }
-    sendVoice(scopeId, filename, contents, caption) {
+    sendVoice(scopeId, filename, contents, caption, contentType) {
         if (this.isWeixinScope(scopeId)) {
             throw new Error(`Voice messages are not supported for Weixin scope ${scopeId}`);
         }
-        return this.telegram.sendVoice(scopeId, filename, contents, caption);
+        return this.telegram.sendVoice(scopeId, filename, contents, caption, contentType);
     }
     editPlain(scopeId, messageId, text, keyboard) {
         if (this.isWeixinScope(scopeId)) {

package/dist/channels/telegram/telegram_messaging_port.d.ts

@@ -15,7 +15,7 @@ export declare class TelegramMessagingPort implements ChannelPort {
     sendHtml(bridgeScopeId: string, text: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     sendRichHtml(bridgeScopeId: string, html: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
     sendRichMarkdown(bridgeScopeId: string, markdown: string, inlineKeyboard?: InlineKeyboard): Promise<number>;
-    sendVoice(bridgeScopeId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
+    sendVoice(bridgeScopeId: string, filename: string, contents: Buffer, caption?: string, contentType?: string): Promise<number>;
     editPlain(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     editHtml(bridgeScopeId: string, messageId: number, text: string, inlineKeyboard?: InlineKeyboard): Promise<void>;
     editRichHtml(bridgeScopeId: string, messageId: number, html: string, inlineKeyboard?: InlineKeyboard): Promise<void>;

package/dist/channels/telegram/telegram_messaging_port.js

@@ -24,9 +24,9 @@ export class TelegramMessagingPort {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
         return this.gateway.sendRichMessage(target.chatId, telegramRichMarkdown(markdown, { skipEntityDetection: true }), inlineKeyboard, target.topicId);
     }
-    async sendVoice(bridgeScopeId, filename, contents, caption) {
+    async sendVoice(bridgeScopeId, filename, contents, caption, contentType) {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);
-        return this.gateway.sendVoice(target.chatId, filename, contents, caption, target.topicId);
+        return this.gateway.sendVoice(target.chatId, filename, contents, caption, target.topicId, contentType);
     }
     async editPlain(bridgeScopeId, messageId, text, inlineKeyboard) {
         const target = parseTelegramTargetFromBridgeScope(bridgeScopeId);

package/dist/config.d.ts

@@ -72,7 +72,9 @@ export interface AppConfig {
     voiceTtsDesignInstruct: string;
     voiceFfmpegBin: string;
     voiceSummaryButtonEnabled: boolean;
+    voiceSummaryTextLimit: number;
     voiceTextLimit: number;
+    voiceTtsTimeoutMs: number;
 }
 export declare function loadConfig(): AppConfig;
 export declare function selectDefaultRuntimeBotToken(configuredTokens: string[], legacyToken: string | null): string | null;

package/dist/config.js

@@ -106,7 +106,9 @@ export function loadConfig() {
         voiceTtsDesignInstruct: process.env.VOICE_TTS_DESIGN_INSTRUCT?.trim() || '用自然清晰的中文女声朗读，语速适中。',
         voiceFfmpegBin: process.env.VOICE_FFMPEG_BIN?.trim() || 'ffmpeg',
         voiceSummaryButtonEnabled: boolEnv('VOICE_SUMMARY_BUTTON_ENABLED', true),
+        voiceSummaryTextLimit: intEnv('VOICE_SUMMARY_TEXT_LIMIT', 180),
         voiceTextLimit: intEnv('VOICE_TEXT_LIMIT', 2800),
+        voiceTtsTimeoutMs: intEnv('VOICE_TTS_TIMEOUT_MS', 120_000),
     };
     ensureAppDirs(config);
     return config;

package/dist/controller/controller.d.ts

@@ -319,6 +319,7 @@ export declare class BridgeSessionCore {
     private handleQuotaCommand;
     private handleQuotaNudgeCommand;
     private handleVoiceCommand;
+    private handleVoiceFileCommand;
     private handleVoiceCallback;
     private sendVoiceForText;
     private handleLoginDeviceCommand;

package/dist/controller/controller.js

@@ -5175,6 +5175,10 @@ export class BridgeSessionCore {
         await this.sendMessage(scopeId, t(locale, 'quota_nudge_sent'));
     }
     async handleVoiceCommand(scopeId, locale, args) {
+        if (args[0]?.toLowerCase() === 'file' || args[0]?.toLowerCase() === 'send') {
+            await this.handleVoiceFileCommand(scopeId, locale, args.slice(1));
+            return;
+        }
         const raw = args.join(' ').trim();
         const snippetId = raw.toLowerCase() === 'last' ? this.latestVoiceSnippetByScope.get(scopeId) ?? null : null;
         const text = snippetId ? this.voiceSnippets.get(snippetId)?.text ?? '' : raw;
@@ -5184,6 +5188,47 @@ export class BridgeSessionCore {
         }
         await this.sendVoiceForText(scopeId, locale, text);
     }
+    async handleVoiceFileCommand(scopeId, locale, args) {
+        if (scopeId.startsWith(BRIDGE_SCOPE_WEIXIN_PREFIX)) {
+            await this.sendMessage(scopeId, locale === 'zh' ? '当前只有 Telegram 支持语音消息。' : 'Voice messages are currently supported only on Telegram.');
+            return;
+        }
+        const fileArg = args[0]?.trim();
+        if (!fileArg) {
+            await this.sendMessage(scopeId, locale === 'zh'
+                ? '用法：/voice file /path/to/audio.ogg [说明]'
+                : 'Usage: /voice file /path/to/audio.ogg [caption]');
+            return;
+        }
+        const filePath = path.resolve(this.config.defaultCwd, fileArg);
+        const contentType = telegramVoiceContentType(filePath);
+        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.');
+            return;
+        }
+        const stat = await fs.stat(filePath).catch(() => null);
+        if (!stat?.isFile()) {
+            await this.sendMessage(scopeId, locale === 'zh' ? `找不到音频文件：${filePath}` : `Audio file not found: ${filePath}`);
+            return;
+        }
+        if (stat.size > 50 * 1024 * 1024) {
+            await this.sendMessage(scopeId, locale === 'zh' ? 'Telegram voice 文件不能超过 50MB。' : 'Telegram voice files must be 50MB or smaller.');
+            return;
+        }
+        try {
+            const contents = await fs.readFile(filePath);
+            const caption = args.slice(1).join(' ').trim() || (locale === 'zh' ? 'FoxClaw 语音文件' : 'FoxClaw voice file');
+            await this.messaging.sendVoice(scopeId, path.basename(filePath), contents, caption, contentType);
+        }
+        catch (error) {
+            this.logger.warn('voice.file_send_failed', { scopeId, filePath, error: toErrorMeta(error) });
+            await this.sendMessage(scopeId, locale === 'zh'
+                ? `语音文件发送失败：${formatUserError(error)}`
+                : `Voice file send failed: ${formatUserError(error)}`);
+        }
+    }
     async handleVoiceCallback(event, localId, locale) {
         const snippet = this.voiceSnippets.get(localId);
         if (!snippet || snippet.scopeId !== event.scopeId) {
@@ -8394,7 +8439,7 @@ export class BridgeSessionCore {
     }
     registerVoiceSnippet(scopeId, text) {
         this.pruneVoiceSnippets();
-        const normalized = normalizeVoiceText(text, this.config.voiceTextLimit);
+        const normalized = normalizeVoiceText(text, this.config.voiceSummaryTextLimit);
         const id = crypto.randomBytes(6).toString('hex');
         this.voiceSnippets.set(id, { scopeId, text: normalized, createdAt: Date.now() });
         this.latestVoiceSnippetByScope.set(scopeId, id);
@@ -8451,6 +8496,21 @@ 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/i18n.d.ts

@@ -46,6 +46,7 @@ declare const MESSAGES: {
         readonly cmd_desc_fast: "Toggle Fast mode";
         readonly cmd_desc_active: "Active-turn message behavior";
         readonly cmd_desc_rich: "Telegram RichMessage demo";
+        readonly cmd_desc_voice: "Send voice from text or file";
         readonly cmd_desc_status: "Bridge status";
         readonly cmd_desc_update: "Update and restart FoxClaw";
         readonly cmd_desc_account: "Codex account";
@@ -745,6 +746,7 @@ declare const MESSAGES: {
         readonly cmd_desc_fast: "切换 Fast 模式";
         readonly cmd_desc_active: "运行中新消息处理方式";
         readonly cmd_desc_rich: "Telegram RichMessage 演示";
+        readonly cmd_desc_voice: "朗读文本或发送语音文件";
         readonly cmd_desc_status: "查看桥接状态";
         readonly cmd_desc_update: "升级并重启 FoxClaw";
         readonly cmd_desc_account: "Codex 账号";

package/dist/i18n.js

@@ -44,6 +44,7 @@ const MESSAGES = {
         cmd_desc_fast: 'Toggle Fast mode',
         cmd_desc_active: 'Active-turn message behavior',
         cmd_desc_rich: 'Telegram RichMessage demo',
+        cmd_desc_voice: 'Send voice from text or file',
         cmd_desc_status: 'Bridge status',
         cmd_desc_update: 'Update and restart FoxClaw',
         cmd_desc_account: 'Codex account',
@@ -743,6 +744,7 @@ const MESSAGES = {
         cmd_desc_fast: '切换 Fast 模式',
         cmd_desc_active: '运行中新消息处理方式',
         cmd_desc_rich: 'Telegram RichMessage 演示',
+        cmd_desc_voice: '朗读文本或发送语音文件',
         cmd_desc_status: '查看桥接状态',
         cmd_desc_update: '升级并重启 FoxClaw',
         cmd_desc_account: 'Codex 账号',
@@ -1417,6 +1419,7 @@ export function getTelegramCommands(locale) {
         { command: 'fast', description: t(locale, 'cmd_desc_fast') },
         { command: 'active', description: t(locale, 'cmd_desc_active') },
         { command: 'rich', description: t(locale, 'cmd_desc_rich') },
+        { command: 'voice', description: t(locale, 'cmd_desc_voice') },
         { command: 'account', description: t(locale, 'cmd_desc_account') },
         { command: 'quota', description: t(locale, 'cmd_desc_quota') },
         { command: 'login_device', description: t(locale, 'cmd_desc_login_device') },

package/dist/telegram/gateway.d.ts

@@ -68,7 +68,7 @@ export declare class TelegramGateway extends EventEmitter {
         callback_data: string;
     }>>, messageThreadId?: number | null): Promise<number>;
     sendDocument(chatId: string, filename: string, contents: Buffer, caption?: string): Promise<number>;
-    sendVoice(chatId: string, filename: string, contents: Buffer, caption?: string, messageThreadId?: number | null): Promise<number>;
+    sendVoice(chatId: string, filename: string, contents: Buffer, caption?: string, messageThreadId?: number | null, contentType?: string): Promise<number>;
     sendMessageDraft(chatId: string, draftId: number, text: string, messageThreadId?: number | null): Promise<void>;
     sendRichMessageDraft(chatId: string, draftId: number, richMessage: TelegramInputRichMessage, messageThreadId?: number | null): Promise<void>;
     editMessage(chatId: string, messageId: number, text: string, inlineKeyboard?: Array<Array<{

package/dist/telegram/gateway.js

@@ -83,7 +83,7 @@ export class TelegramGateway extends EventEmitter {
         }
         return result.result.message_id;
     }
-    async sendVoice(chatId, filename, contents, caption, messageThreadId) {
+    async sendVoice(chatId, filename, contents, caption, messageThreadId, contentType = 'audio/ogg') {
         const result = await callTelegramMultipartApi(this.botToken, 'sendVoice', {
             chat_id: chatId,
             ...(caption ? { caption } : {}),
@@ -92,7 +92,7 @@ export class TelegramGateway extends EventEmitter {
                 fieldName: 'voice',
                 filename,
                 contents,
-                contentType: 'audio/ogg',
+                contentType,
             }]);
         if (!result.ok || !result.result) {
             throw new Error(result.description || 'Failed to send Telegram voice message');

package/dist/voice/tts.js

@@ -61,14 +61,17 @@ async function requestTtsWav(config, pathname, body) {
         throw new Error('VOICE_TTS_URL is not configured');
     }
     const endpoint = new URL(pathname, config.voiceTtsUrl.endsWith('/') ? config.voiceTtsUrl : `${config.voiceTtsUrl}/`);
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), config.voiceTtsTimeoutMs);
     const response = await fetch(endpoint, {
         method: 'POST',
+        signal: abortController.signal,
         headers: {
             'content-type': 'application/json',
             ...(config.voiceTtsToken ? { authorization: `Bearer ${config.voiceTtsToken}` } : {}),
         },
         body: JSON.stringify(body),
-    });
+    }).finally(() => clearTimeout(timer));
     if (!response.ok) {
         throw new Error(`TTS request failed: ${response.status} ${response.statusText}: ${await response.text().catch(() => '')}`);
     }
@@ -172,9 +175,9 @@ PY
         encodedText,
         config.voiceTtsSshDir,
         config.voiceTtsDesignInstruct,
-    ], script);
+    ], script, config.voiceTtsTimeoutMs);
 }
-async function runSshBinary(args, stdin) {
+async function runSshBinary(args, stdin, timeoutMs) {
     return new Promise((resolve, reject) => {
         const child = spawn('ssh', args, { stdio: ['pipe', 'pipe', 'pipe'] });
         const stdout = [];
@@ -182,7 +185,7 @@ async function runSshBinary(args, stdin) {
         const timer = setTimeout(() => {
             child.kill('SIGTERM');
             reject(new Error('remote TTS timed out'));
-        }, 120_000);
+        }, timeoutMs);
         child.stdout.on('data', (chunk) => {
             stdout.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
         });

package/package.json

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