@foxden-app/foxclaw 0.5.52 → 0.5.54

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.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
+
+### 中文
+- 修复单 bot 默认 runtime 的 `telegram-voice-delivery` 无法找到私聊的问题：当 `CODEX_HOME` 不含 bot ID 时，`send-voice` 现在会从唯一配置的 Telegram token 安全补全 bot ID，再读取已经记录的私聊目标。
+- 将内置 `telegram-voice-delivery` Skill 的触发说明、工作流和 UI 元数据改为中文，并明确只有确实没有私聊记录时才要求用户发送 `/status`。
+
+### English
+- Fixed `telegram-voice-delivery` failing to find the private chat in a single-bot default runtime. When `CODEX_HOME` has no bot ID, `send-voice` now safely derives it from the only configured Telegram token before reading the remembered chat target.
+- Localized the bundled `telegram-voice-delivery` skill instructions and UI metadata into Chinese, and clarified that users should only be asked to send `/status` when no private chat is actually remembered.
+
 ## 0.5.52 - 2026-06-20
 
 ### 中文

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/main.js

@@ -16,6 +16,7 @@ import { buildFoxclawLaunchdPlistText, extractNodePathFromLaunchdPlist, } from '
 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';
+import { inferTelegramBotId, resolveTelegramVoiceTarget } from './voice/target.js';
 const rawCommand = process.argv[2];
 const command = rawCommand || 'serve';
 loadEnv();
@@ -297,8 +298,8 @@ async function runSendVoiceCli() {
     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 inferredBotId = parsed.botId ?? inferTelegramBotId(process.env.CODEX_HOME) ?? inferTelegramBotId(config.codexHome);
+    const { botId, botToken } = resolveTelegramVoiceTarget(config.tgBotTokens, inferredBotId);
     const { BridgeStore } = await import('./store/database.js');
     const store = new BridgeStore(config.storePath);
     let chatId = parsed.chatId;
@@ -355,24 +356,6 @@ function parseSendVoiceCliArgs(args) {
         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);

package/dist/voice/target.d.ts

@@ -0,0 +1,6 @@
+export type TelegramVoiceTarget = {
+    botId: string;
+    botToken: string;
+};
+export declare function inferTelegramBotId(codexHome: string | null | undefined): string | null;
+export declare function resolveTelegramVoiceTarget(tokens: string[], requestedBotId: string | null): TelegramVoiceTarget;

package/dist/voice/target.js

@@ -0,0 +1,23 @@
+export function inferTelegramBotId(codexHome) {
+    if (!codexHome)
+        return null;
+    const match = codexHome.match(/(?:^|[\\/])(bot\d+)(?:[\\/]|$)/i);
+    return match?.[1]?.toLowerCase() ?? null;
+}
+export function resolveTelegramVoiceTarget(tokens, requestedBotId) {
+    if (requestedBotId) {
+        const numericId = requestedBotId.replace(/^bot/i, '');
+        const matched = tokens.find(token => token.startsWith(`${numericId}:`));
+        if (matched)
+            return { botId: `bot${numericId}`, botToken: matched };
+        throw new Error(`No configured Telegram token matches ${requestedBotId}. Pass --bot-id for a configured bot.`);
+    }
+    if (tokens.length === 1) {
+        const botToken = tokens[0];
+        const numericId = botToken.slice(0, botToken.indexOf(':'));
+        if (/^\d+$/.test(numericId)) {
+            return { botId: `bot${numericId}`, botToken };
+        }
+    }
+    throw new Error('Cannot infer the Telegram bot from this Codex session. Pass --bot-id <bot-id>.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.52",
+  "version": "0.5.54",
   "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

@@ -1,25 +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.
+description: 通过 FoxClaw 将 Codex 已生成或找到的语音、解说、播客等音频文件直接发送到当前 Telegram 会话。需要把音频交付给用户且不应要求用户手动执行 FoxClaw 命令时使用。
 ---
 
-# Telegram Voice Delivery
+# Telegram 语音投递
 
-Send completed audio artifacts back to the active FoxClaw Telegram conversation without asking the user to operate `/voice`.
+把已经完成的音频直接发送到当前 FoxClaw Telegram 私聊，不要让用户操作 `/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:
+1. 确认音频文件已经完整生成。
+2. 优先使用适合 Telegram 语音播放的 `.ogg` 或 `.opus`；也支持 `.oga`、`.mp3` 和 `.m4a`。
+3. 文件不得超过 50MB。
+4. 执行：
 
 ```bash
-foxclaw send-voice "/absolute/path/to/audio.ogg" "Short caption"
+foxclaw send-voice "/音频的绝对路径/audio.ogg" "简短说明"
 ```
 
-5. Treat a successful command as delivery confirmation and tell the user the audio was sent.
+5. 命令成功即表示 Telegram 已接收该语音；随后简短告知用户已经发送。
 
-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.
+FoxClaw 会从 `CODEX_HOME` 推断当前 Telegram bot；单 bot 默认 runtime 会从唯一配置的 token 补全 bot ID。随后从本地数据库读取该 bot 最近记录的私聊，并调用 Telegram `sendVoice`。不要读取、打印或泄露 Telegram bot token。
 
-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.
+音频已经存在时直接发送，不要重新生成。只有 FoxClaw 明确报告没有记录私聊时，才请用户对当前 bot 发送一次 `/status`；仅在自动会话推断确实不可用时使用 `--bot-id <bot-id>` 或 `--chat-id <chat-id>`，不要凭猜测指定其他 bot。

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

@@ -1,4 +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."
+  display_name: "Telegram 语音投递"
+  short_description: "把 Codex 已生成的音频直接发送到当前 Telegram 会话"
+  default_prompt: "使用 $telegram-voice-delivery，把已完成的音频文件发送到当前 Telegram 会话。"