@foxden-app/foxclaw 0.5.53 → 0.5.55

package/.env.example

@@ -32,9 +32,13 @@ LOG_LEVEL=info
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write
-TELEGRAM_POLL_INTERVAL_MS=1200
-TELEGRAM_PREVIEW_THROTTLE_MS=800
-THREAD_LIST_LIMIT=10
+TELEGRAM_POLL_INTERVAL_MS=1200
+TELEGRAM_PREVIEW_THROTTLE_MS=800
+# Delete folded operation-detail messages after the final answer is sent.
+# Set to false if you prefer to keep "read files / edited files / ran command"
+# detail cards in the chat history.
+# TELEGRAM_DELETE_TOOL_DETAILS_AFTER_FINAL=true
+THREAD_LIST_LIMIT=10
 CODEX_CLI_BIN=/absolute/path/to/codex
 
 # Optional cross-node Codex auth sync.
@@ -59,6 +63,7 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # your own speech host; HTTP mode calls your own VOICE_TTS_URL and converts
 # locally. FoxClaw does not ship with a public TTS backend.
 # VOICE_TTS_ENABLED=false
+# VOICE_TTS_ENGINE=qwen
 # HTTP backend example: compatible service exposing /v1/tts/custom or
 # /v1/tts/design and returning WAV audio. Local ffmpeg is required.
 # VOICE_TTS_MODE=http
@@ -70,11 +75,13 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # VOICE_TTS_MODE=ssh
 # VOICE_TTS_SSH_HOST=<ssh-host>
 # VOICE_TTS_SSH_DIR=/path/to/qwen-speech-server
+# For SoulX-compatible backends, set VOICE_TTS_ENGINE=soulx and point
+# VOICE_TTS_URL at the SoulX service, for example http://127.0.0.1:18082.
 # VOICE_TTS_DESIGN_INSTRUCT=用自然清晰的中文女声朗读，语速适中。
 # VOICE_SUMMARY_BUTTON_ENABLED=true
 # VOICE_SUMMARY_TEXT_LIMIT=180
 # VOICE_TEXT_LIMIT=2800
-# VOICE_TTS_TIMEOUT_MS=120000
+# VOICE_TTS_TIMEOUT_MS=60000
 
 # 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.55 - 2026-06-21
+
+### 中文
+- 最终答复发出后，默认删除已折叠的工具操作明细消息，让 Telegram 回顾时更接近“一问一答”；新增 `TELEGRAM_DELETE_TOOL_DETAILS_AFTER_FINAL=false` 可保留这些明细。
+- “听总结”新增 `VOICE_TTS_ENGINE=soulx`，SSH 模式会先检查 SoulX `/health`，再调用 `/v1/tts` 并转成 Telegram voice；语音 TTS 默认超时缩短到 60 秒。
+- 降噪内部状态通知：不再向 Telegram 展示“目标已清除”“线程 active/running”“MCP ready/starting”等低价值生命周期消息，错误和需要处理的状态仍会提示。
+
+### English
+- After a final answer is sent, FoxClaw now deletes archived tool-detail messages by default so Telegram history reads closer to one user turn and one final reply. Set `TELEGRAM_DELETE_TOOL_DETAILS_AFTER_FINAL=false` to keep them.
+- Added `VOICE_TTS_ENGINE=soulx` for voice summaries. SSH mode checks the SoulX `/health` endpoint, calls `/v1/tts`, and converts the result to Telegram voice; the default TTS timeout is now 60 seconds.
+- Reduced noisy internal lifecycle notifications: Telegram no longer shows low-value "goal cleared", active/running thread status, or MCP ready/starting messages, while errors and actionable states are still reported.
+
+## 0.5.54 - 2026-06-20
+
+### 中文
+- 修复升级到 Codex CLI `0.141.0` 后 Telegram 看不到工具执行明细的问题；FoxClaw 现在支持现代 app-server 的 `item/started` / `item/completed` 工具生命周期。
+- 命令执行、文件修改、网页搜索、MCP/动态工具、图片查看和生成、协作 Agent 操作会重新实时显示；阶段结束后仍压缩为可展开明细，最终过程汇报继续独立折叠。
+- 保留旧版 `codex/event/exec_command_begin/end` 兼容，避免旧节点或旧 Codex CLI 失去过程状态。
+
+### English
+- Fixed Telegram tool activity details disappearing after upgrading to Codex CLI `0.141.0`; FoxClaw now supports the modern app-server `item/started` and `item/completed` tool lifecycle.
+- Command execution, file changes, web search, MCP/dynamic tools, image activity, and collaborative agent operations are visible in real time again, then archived into expandable stage details.
+- Kept compatibility with legacy `codex/event/exec_command_begin/end` notifications for older Codex CLI installations.
+
 ## 0.5.53 - 2026-06-20
 
 ### 中文

package/dist/config.d.ts

@@ -40,6 +40,7 @@ export interface AppConfig {
     defaultSandboxMode: SandboxModeValue;
     telegramPollIntervalMs: number;
     telegramPreviewThrottleMs: number;
+    telegramDeleteToolDetailsAfterFinal: boolean;
     threadListLimit: number;
     statusPath: string;
     logPath: string;
@@ -64,6 +65,7 @@ export interface AppConfig {
     authSyncTempDir: string;
     authAutoDeleteNeedsRepair: boolean;
     voiceTtsEnabled: boolean;
+    voiceTtsEngine: 'qwen' | 'soulx';
     voiceTtsMode: 'http' | 'ssh';
     voiceTtsUrl: string | null;
     voiceTtsToken: string | null;

package/dist/config.js

@@ -77,6 +77,7 @@ export function loadConfig() {
         defaultSandboxMode: parseSandboxMode(process.env.DEFAULT_SANDBOX_MODE || 'workspace-write'),
         telegramPollIntervalMs: intEnv('TELEGRAM_POLL_INTERVAL_MS', 1200),
         telegramPreviewThrottleMs: intEnv('TELEGRAM_PREVIEW_THROTTLE_MS', 800),
+        telegramDeleteToolDetailsAfterFinal: boolEnv('TELEGRAM_DELETE_TOOL_DETAILS_AFTER_FINAL', true),
         threadListLimit: intEnv('THREAD_LIST_LIMIT', 10),
         statusPath: DEFAULT_STATUS_PATH,
         logPath: DEFAULT_LOG_PATH,
@@ -98,6 +99,7 @@ export function loadConfig() {
         authSyncTempDir: process.env.AUTH_SYNC_TEMP_DIR || DEFAULT_AUTH_SYNC_TEMP_DIR,
         authAutoDeleteNeedsRepair: boolEnv('AUTH_AUTO_DELETE_NEEDS_REPAIR', false),
         voiceTtsEnabled: boolEnv('VOICE_TTS_ENABLED', false),
+        voiceTtsEngine: parseVoiceTtsEngine(process.env.VOICE_TTS_ENGINE || 'qwen'),
         voiceTtsMode: parseVoiceTtsMode(process.env.VOICE_TTS_MODE || (process.env.VOICE_TTS_SSH_HOST?.trim() ? 'ssh' : 'http')),
         voiceTtsUrl: optional('VOICE_TTS_URL'),
         voiceTtsToken: optional('VOICE_TTS_TOKEN'),
@@ -108,7 +110,7 @@ export function loadConfig() {
         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),
+        voiceTtsTimeoutMs: intEnv('VOICE_TTS_TIMEOUT_MS', 60_000),
     };
     ensureAppDirs(config);
     return config;
@@ -197,6 +199,9 @@ function parseSandboxMode(value) {
 function parseVoiceTtsMode(value) {
     return value.trim().toLowerCase() === 'http' ? 'http' : 'ssh';
 }
+function parseVoiceTtsEngine(value) {
+    return value.trim().toLowerCase() === 'soulx' ? 'soulx' : 'qwen';
+}
 function resolveCommand(commandName) {
     try {
         const which = process.platform === 'win32' ? 'where' : 'which';

package/dist/controller/activity.js

@@ -52,6 +52,10 @@ function normalizeStartedEvent(params) {
             state: 'thinking',
         };
     }
+    const toolEvent = normalizeThreadItemToolEvent(params, 'tool_started');
+    if (toolEvent) {
+        return toolEvent;
+    }
     if (!isRelayableTextItemType(itemType)) {
         return null;
     }
@@ -113,6 +117,10 @@ function normalizeCompletedEvent(params) {
             state: 'thinking',
         };
     }
+    const toolEvent = normalizeThreadItemToolEvent(params, 'tool_completed');
+    if (toolEvent) {
+        return toolEvent;
+    }
     if (!isRelayableTextItemType(itemType)) {
         return null;
     }
@@ -161,6 +169,86 @@ function normalizeToolEvent(params, kind) {
         state: inferToolActivityState(exec),
     };
 }
+function normalizeThreadItemToolEvent(params, kind) {
+    const turnId = extractTurnId(params);
+    const item = params?.item;
+    const itemId = extractItemId(item);
+    const itemType = normalizeEventItemType(item);
+    if (!turnId || !itemId || !itemType) {
+        return null;
+    }
+    let command = [];
+    let cwd = null;
+    let parsedCmd = [];
+    switch (itemType) {
+        case 'commandexecution':
+            command = typeof item.command === 'string' ? [item.command] : [];
+            cwd = typeof item.cwd === 'string' ? item.cwd : null;
+            parsedCmd = normalizeCommandActions(item.commandActions);
+            break;
+        case 'filechange':
+            parsedCmd = normalizeFileChanges(item.changes);
+            break;
+        case 'websearch':
+            parsedCmd = [{
+                    type: 'search',
+                    query: typeof item.query === 'string' ? item.query : '',
+                    path: null,
+                }];
+            break;
+        case 'imageview':
+            parsedCmd = [{ type: 'read', path: typeof item.path === 'string' ? item.path : null }];
+            break;
+        case 'mcptoolcall':
+            command = [`MCP ${String(item.server ?? 'server')}/${String(item.tool ?? 'tool')}`];
+            break;
+        case 'dynamictoolcall':
+            command = [`Tool ${item.namespace ? `${String(item.namespace)}/` : ''}${String(item.tool ?? 'tool')}`];
+            break;
+        case 'collabagenttoolcall':
+            command = [`Agent ${String(item.tool ?? 'operation')}`];
+            break;
+        case 'imagegeneration':
+            command = ['Image generation'];
+            break;
+        default:
+            return null;
+    }
+    const exec = {
+        callId: itemId,
+        turnId,
+        command,
+        cwd,
+        parsedCmd,
+    };
+    return {
+        kind,
+        turnId,
+        exec,
+        state: inferToolActivityState(exec),
+    };
+}
+function normalizeCommandActions(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => {
+        const type = typeof entry?.type === 'string' ? entry.type : '';
+        if (type === 'listFiles') {
+            return { ...entry, type: 'list_files' };
+        }
+        return entry;
+    });
+}
+function normalizeFileChanges(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((entry) => ({
+        type: 'apply_patch',
+        path: typeof entry?.path === 'string' ? entry.path : null,
+    }));
+}
 export function classifyAgentOutput(phase, completed) {
     if (!phase) {
         return completed ? 'final_answer' : 'commentary';

package/dist/controller/controller.d.ts

@@ -239,7 +239,7 @@ export declare class BridgeSessionCore {
     private sendTyping;
     private sendObservedCliUserMessage;
     private collapseTurnCommentary;
-    private cleanupObservedTransientMessages;
+    private cleanupTransientProgressMessages;
     private hasObservedPersistentReply;
     private ensureThreadReady;
     private handleAsyncError;

package/dist/controller/controller.js

@@ -1495,6 +1495,9 @@ export class BridgeSessionCore {
         if (status === 'idle') {
             return;
         }
+        if (status === 'active' || status === 'running') {
+            return;
+        }
         const locale = this.localeForChat(scopeId);
         await this.sendMessage(scopeId, t(locale, 'thread_status_changed', { threadId, status }));
     }
@@ -1534,7 +1537,6 @@ export class BridgeSessionCore {
         }
         const locale = this.localeForChat(scopeId);
         if (method === 'thread/goal/cleared') {
-            await this.sendMessage(scopeId, t(locale, 'goal_cleared_notification', { threadId }));
             return;
         }
         const goal = mapGoalNotification(params?.goal);
@@ -1828,6 +1830,10 @@ export class BridgeSessionCore {
         const message = params?.error
             ? `MCP ${name}: ${status} (${String(params.error)})`
             : `MCP ${name}: ${status}`;
+        const normalized = status.toLowerCase();
+        if (!params?.error && ['ready', 'running', 'starting', 'connected'].includes(normalized)) {
+            return;
+        }
         await this.notifyBoundScopes(message);
     }
     async handleMcpOauthLoginCompleted(params) {
@@ -1877,7 +1883,7 @@ export class BridgeSessionCore {
         }
         try {
             await this.completeTurn(active);
-            await this.cleanupObservedTransientMessages(active);
+            await this.cleanupTransientProgressMessages(active);
             await this.finalizeUserInputsForTurn(active, 'resolved');
             this.markQueuedTurnCompleted(active);
         }
@@ -3234,7 +3240,7 @@ export class BridgeSessionCore {
                 try {
                     this.promoteReadyToolBatch(active);
                     await this.completeTurn(active);
-                    await this.cleanupObservedTransientMessages(active);
+                    await this.cleanupTransientProgressMessages(active);
                     await this.finalizeUserInputsForTurn(active, active.interruptRequested ? 'interrupted' : 'resolved');
                     await this.maybeSendPlanImplementationPrompt(active);
                     this.markQueuedTurnCompleted(active);
@@ -3481,21 +3487,25 @@ export class BridgeSessionCore {
             segment.messages = [];
         }
     }
-    async cleanupObservedTransientMessages(active) {
-        if (!active.isObserved || !this.hasObservedPersistentReply(active)) {
+    async cleanupTransientProgressMessages(active) {
+        if (!this.hasObservedPersistentReply(active)) {
             return;
         }
         const messageIds = new Set();
-        for (const segment of active.segments) {
-            if (segment.outputKind === 'final_answer') {
-                continue;
-            }
-            for (const message of segment.messages) {
-                messageIds.add(message.messageId);
+        if (active.isObserved) {
+            for (const segment of active.segments) {
+                if (segment.outputKind === 'final_answer') {
+                    continue;
+                }
+                for (const message of segment.messages) {
+                    messageIds.add(message.messageId);
+                }
             }
         }
-        for (const messageId of active.archivedMessageIds) {
-            messageIds.add(messageId);
+        if (this.config.telegramDeleteToolDetailsAfterFinal) {
+            for (const messageId of active.archivedMessageIds) {
+                messageIds.add(messageId);
+            }
         }
         for (const messageId of messageIds) {
             try {
@@ -3503,7 +3513,7 @@ export class BridgeSessionCore {
             }
             catch (error) {
                 if (!isTelegramMessageGone(error)) {
-                    this.logger.warn('telegram.observed_cleanup_delete_failed', {
+                    this.logger.warn('telegram.transient_progress_cleanup_delete_failed', {
                         error: String(error),
                         turnId: active.turnId,
                         messageId,
@@ -8080,7 +8090,7 @@ export class BridgeSessionCore {
                 else {
                     messageId = await this.sendMessage(active.scopeId, content.text);
                 }
-                if (active.isObserved && messageId !== null) {
+                if (messageId !== null) {
                     active.archivedMessageIds.push(messageId);
                 }
             }
@@ -8098,9 +8108,7 @@ export class BridgeSessionCore {
             else {
                 await this.editMessage(active.scopeId, active.previewMessageId, content.text, []);
             }
-            if (active.isObserved) {
-                active.archivedMessageIds.push(active.previewMessageId);
-            }
+            active.archivedMessageIds.push(active.previewMessageId);
         }
         catch (error) {
             if (isTelegramMessageGone(error)) {

package/dist/voice/tts.js

@@ -41,6 +41,9 @@ async function synthesizeViaHttp(text, config) {
     if (!config.voiceTtsUrl) {
         throw new Error('VOICE_TTS_URL is not configured');
     }
+    if (config.voiceTtsEngine === 'soulx') {
+        return convertToOggOpus(await requestTtsWav(config, '/v1/tts', { text, seed: '7' }), config.voiceFfmpegBin);
+    }
     try {
         return convertToOggOpus(await requestTtsWav(config, '/v1/tts/custom', { text, language: 'zh' }), config.voiceFfmpegBin);
     }
@@ -114,6 +117,9 @@ async function synthesizeViaSsh(text, config) {
     if (!config.voiceTtsSshDir) {
         throw new Error('VOICE_TTS_SSH_DIR is not configured');
     }
+    if (config.voiceTtsEngine === 'soulx') {
+        return synthesizeSoulxViaSsh(text, config);
+    }
     const encodedText = Buffer.from(text, 'utf8').toString('base64');
     const script = String.raw `set -euo pipefail
 TEXT="$(printf '%s' "$1" | base64 -d)"
@@ -177,6 +183,63 @@ PY
         config.voiceTtsDesignInstruct,
     ], script, config.voiceTtsTimeoutMs);
 }
+async function synthesizeSoulxViaSsh(text, config) {
+    const sshHost = config.voiceTtsSshHost;
+    const envDir = config.voiceTtsSshDir;
+    if (!sshHost) {
+        throw new Error('VOICE_TTS_SSH_HOST is not configured');
+    }
+    if (!envDir) {
+        throw new Error('VOICE_TTS_SSH_DIR is not configured');
+    }
+    const encodedText = Buffer.from(text, 'utf8').toString('base64');
+    const baseUrl = config.voiceTtsUrl || 'http://127.0.0.1:18082';
+    const script = String.raw `set -euo pipefail
+TEXT="$(printf '%s' "$1" | base64 -d)"
+ENV_DIR="$2"
+BASE_URL="$3"
+cd "$ENV_DIR"
+set -a
+. ./.env
+set +a
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+curl -sS "\${BASE_URL}/health" >/dev/null
+TEXT="$TEXT" python3 - <<'PY' > "$tmp/body.json"
+import json
+import os
+print(json.dumps({"text": os.environ["TEXT"], "seed": 7, "dialect_prompt": ""}, ensure_ascii=False))
+PY
+status="$(curl -sS -w '%{http_code}' -X POST "\${BASE_URL}/v1/tts" \
+  -H "Authorization: Bearer $QWEN_SPEECH_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  --data-binary "@$tmp/body.json" \
+  --output "$tmp/tts.wav")"
+if [[ "$status" != "200" ]]; then
+  python3 - "$tmp/tts.wav" <<'PY' >&2
+import pathlib
+import sys
+sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
+PY
+  exit 22
+fi
+ffmpeg -nostdin -hide_banner -loglevel error -y -i "$tmp/tts.wav" -ac 1 -c:a libopus -b:a 32k "$tmp/voice.ogg"
+python3 - "$tmp/voice.ogg" <<'PY'
+import pathlib
+import sys
+sys.stdout.buffer.write(pathlib.Path(sys.argv[1]).read_bytes())
+PY
+`;
+    return runSshBinary([
+        sshHost,
+        'bash',
+        '-s',
+        '--',
+        encodedText,
+        envDir,
+        baseUrl,
+    ], script, config.voiceTtsTimeoutMs);
+}
 async function runSshBinary(args, stdin, timeoutMs) {
     return new Promise((resolve, reject) => {
         const child = spawn('ssh', args, { stdio: ['pipe', 'pipe', 'pipe'] });

package/package.json

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