@foxden-app/foxclaw 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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.7.2 - 2026-08-30
+
+### 中文
+- 为 Codex CLI 0.151.0 及以上版本接入原生跨客户端线程队列。在 Telegram `/watch` 观察电脑端 CLI 会话时，直接发送文字或使用 `/queue <消息>` 会把下一轮任务排入同一线程，由桌面 CLI 在当前轮结束后继续执行。
+- 保持观察模式的 writer 安全边界：FoxClaw 不会 `resume`、中断或接管外部 CLI，`/steer` 仍明确拒绝；旧版 Codex 缺少队列接口时会提示升级，不会改写 session 文件或报告虚假成功。
+
+### English
+- Added the native cross-client thread queue available in Codex CLI 0.151.0 and later. While Telegram `/watch` observes a desktop CLI session, plain text or `/queue <message>` now queues the next task on the same thread for the desktop CLI to continue after its current turn.
+- Preserved the writer-safety boundary of watch mode: FoxClaw does not resume, interrupt, or take over the external CLI, and `/steer` remains explicitly unavailable. Older Codex versions receive an upgrade notice instead of session-file mutation or false success.
+
 ## 0.7.1 - 2026-08-30
 
 ### 中文

package/dist/codex_app/client.d.ts

@@ -98,6 +98,9 @@ export declare class CodexAppClient extends EventEmitter {
     steerTurn(threadId: string, expectedTurnId: string, input: TurnInput[]): Promise<{
         turnId: string;
     }>;
+    queueThreadInput(threadId: string, clientUserMessageId: string, input: TurnInput[]): Promise<{
+        queuedSubmissionId: string;
+    }>;
     forkThread(options: {
         threadId: string;
         cwd: string | null;

package/dist/codex_app/client.js

@@ -186,6 +186,14 @@ export class CodexAppClient extends EventEmitter {
         const result = await this.request('turn/steer', { threadId, expectedTurnId, input });
         return { turnId: String(result?.turnId ?? expectedTurnId) };
     }
+    async queueThreadInput(threadId, clientUserMessageId, input) {
+        const result = await this.request('thread/queue/add', { threadId, clientUserMessageId, input });
+        const queuedSubmissionId = result?.queuedSubmission?.id;
+        if (typeof queuedSubmissionId !== 'string' || !queuedSubmissionId) {
+            throw new Error('thread/queue/add returned no queued submission id');
+        }
+        return { queuedSubmissionId };
+    }
     async forkThread(options) {
         const params = {
             threadId: options.threadId,

package/dist/controller/controller.d.ts

@@ -289,6 +289,7 @@ export declare class BridgeSessionCore {
     private handleTakeoverCommand;
     private handleQueueCommand;
     private handleActiveTurnInboundMessage;
+    private queueObservedThreadMessage;
     private queuePromptAfterActiveTurn;
     private steerActiveTurn;
     private enqueuePreparedTurnInput;

package/dist/controller/controller.js

@@ -359,6 +359,9 @@ export class BridgeSessionCore {
                 await this.sendMessage(scopeId, t(locale, 'auth_sync_validation_busy'));
                 return;
             }
+            if (await this.queueObservedThreadMessage(event, locale, event.text.trim())) {
+                return;
+            }
             await this.startBoundTurnFromEvent(event, locale, event.text.trim());
             return;
         }
@@ -417,6 +420,9 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, t(locale, 'auth_sync_validation_busy'));
             return;
         }
+        if (await this.queueObservedThreadMessage(event, locale, decision.text)) {
+            return;
+        }
         await this.startBoundTurnFromEvent(event, locale, decision.text);
     }
     async handleCommand(event, locale, name, args) {
@@ -4269,12 +4275,15 @@ export class BridgeSessionCore {
             return;
         }
         const active = this.findActiveTurn(scopeId);
-        if (!active) {
-            await this.startBoundTurnFromEvent(event, locale, nextPrompt);
+        const observedThreadId = active?.isObserved
+            ? active.threadId
+            : this.observedThreadWatchers.get(scopeId)?.threadId ?? null;
+        if (observedThreadId) {
+            await this.queueObservedThreadMessage(event, locale, nextPrompt, observedThreadId);
             return;
         }
-        if (active.isObserved) {
-            await this.sendMessage(scopeId, t(locale, 'watch_read_only_active'));
+        if (!active) {
+            await this.startBoundTurnFromEvent(event, locale, nextPrompt);
             return;
         }
         await this.queuePromptAfterActiveTurn(event, locale, nextPrompt);
@@ -4285,7 +4294,7 @@ export class BridgeSessionCore {
             return;
         }
         if (active.isObserved) {
-            await this.sendMessage(event.scopeId, t(locale, 'watch_read_only_active'));
+            await this.queueObservedThreadMessage(event, locale, text, active.threadId);
             return;
         }
         const settings = this.store.getChatSettings(event.scopeId);
@@ -4311,6 +4320,34 @@ export class BridgeSessionCore {
             await this.startBoundTurnFromEvent(event, locale, text);
         }
     }
+    async queueObservedThreadMessage(event, locale, text, threadId = this.observedThreadWatchers.get(event.scopeId)?.threadId ?? null) {
+        if (!threadId) {
+            return false;
+        }
+        const input = await this.buildTurnInput({
+            threadId,
+            cwd: this.store.getBinding(event.scopeId)?.cwd ?? this.config.defaultCwd,
+        }, { ...event, text }, locale);
+        const clientUserMessageId = `foxclaw:${event.scopeId}:${event.messageId}`;
+        try {
+            const queued = await this.app.queueThreadInput(threadId, clientUserMessageId, input);
+            await this.sendMessage(event.scopeId, t(locale, 'watch_prompt_queued', {
+                id: shortId(queued.queuedSubmissionId),
+            }));
+        }
+        catch (error) {
+            if (!isThreadQueueUnsupportedError(error)) {
+                throw error;
+            }
+            this.logger.warn('codex.observed_thread_queue_unsupported', {
+                scopeId: event.scopeId,
+                threadId,
+                error: toErrorMeta(error),
+            });
+            await this.sendMessage(event.scopeId, t(locale, 'watch_queue_unsupported'));
+        }
+        return true;
+    }
     async queuePromptAfterActiveTurn(event, locale, text) {
         const active = this.findActiveTurn(event.scopeId);
         if (!active) {
@@ -5601,6 +5638,10 @@ export class BridgeSessionCore {
             await this.sendMessage(scopeId, t(locale, 'no_active_turn'));
             return;
         }
+        if (active.isObserved) {
+            await this.sendMessage(scopeId, t(locale, 'watch_read_only_active'));
+            return;
+        }
         await this.app.steerTurn(active.threadId, active.turnId, [{
                 type: 'text',
                 text,
@@ -11811,6 +11852,12 @@ function isThreadActiveWriterError(error) {
 function isNoActiveTurnToSteerError(error) {
     return error instanceof Error && /no active turn to steer/i.test(error.message);
 }
+function isThreadQueueUnsupportedError(error) {
+    const message = formatUserError(error).toLowerCase();
+    return message.includes('method not found')
+        || message.includes('unknown method')
+        || message.includes('thread/queue/add') && message.includes('not supported');
+}
 function isThreadNewCwdCreateConfirmation(text) {
     return /^(y|yes|ok|okay|confirm|create|mkdir|确定|确认|创建|新建|好)$/i.test(text.trim());
 }

package/dist/i18n.d.ts

@@ -309,7 +309,9 @@ declare const MESSAGES: {
         readonly watch_already_enabled: "Already watching thread {threadId}.";
         readonly watch_started_active: "Watching thread {threadId}. Live Codex updates from the current turn will appear here.";
         readonly watch_started_idle: "Watching thread {threadId}. I will mirror the next live turn from Codex CLI here.";
-        readonly watch_read_only_active: "This chat is watching that turn read-only. Use approval commands if needed, or /unwatch before sending a new prompt.";
+        readonly watch_read_only_active: "This chat is watching that turn read-only, so this operation cannot take ownership. Send plain text or use /queue to queue the next prompt, or /unwatch to start separately.";
+        readonly watch_prompt_queued: "Queued for the watched Codex CLI session ({id}). The CLI will continue with it after the current turn.";
+        readonly watch_queue_unsupported: "This Codex version does not support cross-client session queues. Update Codex to 0.151.0 or later.";
         readonly watch_not_enabled: "This chat is not watching any thread.";
         readonly watch_stopped: "Stopped watching thread {threadId}.";
         readonly queued_prompt_set: "Queued #{position} ({id}). I will send it after the current turn finishes.";
@@ -1035,7 +1037,9 @@ declare const MESSAGES: {
         readonly watch_already_enabled: "已经在观察线程 {threadId}。";
         readonly watch_started_active: "已开始观察线程 {threadId}。当前这轮 Codex 更新会同步到这里。";
         readonly watch_started_idle: "已开始观察线程 {threadId}。之后 CLI 里这条线程一旦有新 live turn，我会同步到这里。";
-        readonly watch_read_only_active: "当前聊天正在只读观察这轮。需要审批时可用审批命令；要发送新 prompt 请先 /unwatch。";
+        readonly watch_read_only_active: "当前聊天正在只读观察这轮，不能接管这项操作。直接发送文字或使用 /queue 可排入下一轮；要另行启动请先 /unwatch。";
+        readonly watch_prompt_queued: "已排入正在观察的 Codex CLI 会话（{id}）。当前轮结束后，CLI 会自动接着执行。";
+        readonly watch_queue_unsupported: "当前 Codex 不支持跨客户端会话队列，请升级到 Codex 0.151.0 或更高版本。";
         readonly watch_not_enabled: "当前没有正在观察的线程。";
         readonly watch_stopped: "已停止观察线程 {threadId}。";
         readonly queued_prompt_set: "已排队 #{position}（{id}）。当前回复结束后我会自动发送。";

package/dist/i18n.js

@@ -307,7 +307,9 @@ const MESSAGES = {
         watch_already_enabled: 'Already watching thread {threadId}.',
         watch_started_active: 'Watching thread {threadId}. Live Codex updates from the current turn will appear here.',
         watch_started_idle: 'Watching thread {threadId}. I will mirror the next live turn from Codex CLI here.',
-        watch_read_only_active: 'This chat is watching that turn read-only. Use approval commands if needed, or /unwatch before sending a new prompt.',
+        watch_read_only_active: 'This chat is watching that turn read-only, so this operation cannot take ownership. Send plain text or use /queue to queue the next prompt, or /unwatch to start separately.',
+        watch_prompt_queued: 'Queued for the watched Codex CLI session ({id}). The CLI will continue with it after the current turn.',
+        watch_queue_unsupported: 'This Codex version does not support cross-client session queues. Update Codex to 0.151.0 or later.',
         watch_not_enabled: 'This chat is not watching any thread.',
         watch_stopped: 'Stopped watching thread {threadId}.',
         queued_prompt_set: 'Queued #{position} ({id}). I will send it after the current turn finishes.',
@@ -1033,7 +1035,9 @@ const MESSAGES = {
         watch_already_enabled: '已经在观察线程 {threadId}。',
         watch_started_active: '已开始观察线程 {threadId}。当前这轮 Codex 更新会同步到这里。',
         watch_started_idle: '已开始观察线程 {threadId}。之后 CLI 里这条线程一旦有新 live turn，我会同步到这里。',
-        watch_read_only_active: '当前聊天正在只读观察这轮。需要审批时可用审批命令；要发送新 prompt 请先 /unwatch。',
+        watch_read_only_active: '当前聊天正在只读观察这轮，不能接管这项操作。直接发送文字或使用 /queue 可排入下一轮；要另行启动请先 /unwatch。',
+        watch_prompt_queued: '已排入正在观察的 Codex CLI 会话（{id}）。当前轮结束后，CLI 会自动接着执行。',
+        watch_queue_unsupported: '当前 Codex 不支持跨客户端会话队列，请升级到 Codex 0.151.0 或更高版本。',
         watch_not_enabled: '当前没有正在观察的线程。',
         watch_stopped: '已停止观察线程 {threadId}。',
         queued_prompt_set: '已排队 #{position}（{id}）。当前回复结束后我会自动发送。',

package/docs/user-manual.md

@@ -353,7 +353,9 @@ Usage:
 - `/watch <n>`: watch item n from the latest `/threads` list.
 - `/unwatch`: stop watching.
 
-Watch mode mirrors live turn progress and approval requests. The watching chat is read-only for normal prompts during the observed turn. Send `/unwatch` before starting a new prompt from that chat, or wait for the turn to finish.
+Watch mode mirrors live turn progress and approval requests. It still does not take ownership of the CLI writer, and `/steer` cannot modify the in-flight turn. With Codex CLI 0.151.0 or later, however, plain text and `/queue <message>` use Codex's cross-client queue for the same thread. The desktop CLI automatically continues with those messages, in order, after the current turn finishes.
+
+Older Codex versions do not expose this queue API. FoxClaw reports the required upgrade instead of falling back to writer takeover or session-file mutation. Use `/unwatch` first only when you want Telegram to start a separate turn itself.
 
 ## 6. Codex Login And Auth Rotation
 

package/docs/zh/user-manual.md

@@ -353,7 +353,9 @@ FoxClaw 的聊天是“绑定线程”的。你在手机上打开某个 Codex
 - `/watch <n>`：观察最近一次 `/threads` 列表里的第 n 个线程。
 - `/unwatch`：停止观察。
 
-观察模式会同步 live turn 进展和审批请求。观察中的聊天默认是只读的，普通 prompt 不会直接插入正在观察的 turn；需要发新任务时先 `/unwatch`，或等当前 turn 完成。
+观察模式会同步 live turn 进展和审批请求。观察中的聊天仍然不接管 CLI writer，也不能用 `/steer` 修改正在执行的 turn；但从 Codex CLI 0.151.0 开始，直接发送文字或使用 `/queue <消息>` 会通过 Codex 的跨客户端队列排入同一线程，由桌面 CLI 在当前 turn 结束后自动继续执行。连续发送多条会按顺序排队。
+
+旧版 Codex 没有这个队列接口，FoxClaw 会明确提示升级，不会退回到抢占 writer 或改写 session 文件。要让 Telegram 自己另行启动 turn，仍需先 `/unwatch`。
 
 ## 6. Codex 登录和 auth 轮转
 

package/package.json

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