@foxden-app/foxclaw 0.10.0 → 0.11.0

package/.env.example

@@ -1,11 +1,12 @@
-# Required for new installs: one or more bot tokens for this host.
-# Comma-separated bot tokens. By default, each bot gets an independent Codex runtime/auth selection.
-# Homes use ~/.foxclaw/codex/telegram/@TelegramUsername/home (old numeric paths remain as links).
-TG_BOT_TOKENS=<telegram_bot_token>
-# Backward-compatible single-runtime setup.
-# In TG_BOT_TOKENS mode, if this exact token is also present in TG_BOT_TOKENS,
-# that bot uses the default terminal CODEX_HOME/auth instead of an isolated home.
-# TG_BOT_TOKEN=<telegram_bot_token>
+# Required: one or more Telegram bot tokens for Codex execution.
+# Comma-separated bot tokens. The 1st bot shares the default terminal CODEX_HOME (~/.codex).
+# Additional bots receive independent isolated homes (~/.foxclaw/codex/telegram/@TelegramUsername/home).
+CODEX_BOT_TOKENS=<codex_telegram_bot_token>
+
+# Optional: one or more Telegram bot tokens for Google Antigravity execution.
+# Comma-separated bot tokens. The 1st bot shares the default Antigravity home (~/.gemini/antigravity-cli).
+# Additional bots receive independent isolated homes (~/.foxclaw/antigravity/telegram/@TelegramUsername/home).
+# ANTIGRAVITY_BOT_TOKENS=<antigravity_telegram_bot_token>
 
 # Required: only this Telegram user can control the bridge
 TG_ALLOWED_USER_ID=<telegram_user_id>

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.11.0 - 2026-09-30
+
+### 中文
+- **多后端 Telegram Bot 变量重构与后端原生隔离**：
+  - 弃用原有的 `TG_BOT_TOKEN`/`TG_BOT_TOKENS`，引入面向具体执行后端的 `CODEX_BOT_TOKENS` 与 `ANTIGRAVITY_BOT_TOKENS`。
+  - 每类后端的首个 Bot 默认与本地终端 CLI 共享主目录（Codex 共享 `~/.codex`，Antigravity 共享 `~/.gemini/antigravity-cli`），后续实例自动创建隔离主目录。
+  - 隔离目录路径统一升级为人类可读格式（如 `@WallianBot`、`@waxiaosheBot`），彻底告别原有的裸数字 ID 目录。
+- **作用域会话继承与迁移容错增强**：
+  - 修复多 Bot 模式下旧未命名空间会话因历史脏数据导致无法自动迁移的问题；加入 `updated_at` 时间戳比对，自动无缝承接最新正在执行的任务线程。
+  - 增强 `scope_backend_bindings` 的自动迁移与跨引擎会话保持能力。
+- **网络鲁棒性与服务重启自愈**：
+  - 强化 Telegram 长轮询与分片投递在网络断连、代理抖动时的自动恢复机制。
+  - 修复服务重启后活跃任务的断点自动续跑逻辑。
+
+### English
+- **Backend-Centric Bot Variables & Native Home Isolation**:
+  - Deprecated legacy `TG_BOT_TOKEN`/`TG_BOT_TOKENS` in favor of backend-specific `CODEX_BOT_TOKENS` and `ANTIGRAVITY_BOT_TOKENS`.
+  - The first bot of each backend type shares the default terminal CLI home (`~/.codex` for Codex, `~/.gemini/antigravity-cli` for Antigravity), while additional bots receive fully isolated homes.
+  - Isolated directories are now standardized to human-readable Telegram usernames (e.g. `@WallianBot`, `@waxiaosheBot`).
+- **Resilient Scope Migration & Session Inheritance**:
+  - Resolved scope migration conflicts where stale historical records blocked recent unnamespaced turns from being adopted under multi-bot mode.
+  - Added timestamp-based migration for `chat_bindings` and `scope_backend_bindings` to ensure seamless continuation of active sessions across restarts.
+- **Network Resilience & Service Auto-Recovery**:
+  - Enhanced polling and chunk delivery retry mechanisms during transient network resets and proxy timeouts.
+
 ## 0.10.0 - 2026-09-27
 
 ### 中文

package/dist/antigravity/adapter.d.ts

@@ -9,7 +9,8 @@ export declare class AntigravityEngineAdapter implements IEngineAdapter {
     private readonly defaultModel;
     private readonly auth;
     private readonly logger;
-    constructor(client: AntigravityAppClient, defaultModel?: string, auth?: AntigravityAuthManager, logger?: Logger);
+    private readonly baseDir;
+    constructor(client: AntigravityAppClient, defaultModel?: string, auth?: AntigravityAuthManager, logger?: Logger, baseDir?: string);
     listModels(): Promise<EngineModel[]>;
     executeTurn(request: EngineTurnRequest): EngineTurnExecution;
     preflightTurn(_request: EngineTurnRequest): Promise<void>;

package/dist/antigravity/adapter.js

@@ -1,8 +1,9 @@
 import { EventEmitter } from 'node:events';
 import path from 'node:path';
 import { normalizeAgyModelId } from './client.js';
-import { isCapacityOrUnavailableError, isVerificationError, isQuotaOrAuthError, } from './events.js';
+import { isCapacityOrUnavailableError, isVerificationError, isQuotaOrAuthError, isTransientNetworkError, } from './events.js';
 import { buildAttachmentPrompt } from '../telegram/media.js';
+import { AntigravitySubagentTracker } from './subagents.js';
 function extractToolSummary(name, parameters) {
     if (!parameters)
         return undefined;
@@ -39,11 +40,13 @@ export class AntigravityEngineAdapter {
     defaultModel;
     auth;
     logger;
-    constructor(client, defaultModel = 'gemini-3.8-flash', auth, logger) {
+    baseDir;
+    constructor(client, defaultModel = 'gemini-3.8-flash', auth, logger, baseDir) {
         this.client = client;
         this.defaultModel = defaultModel;
         this.auth = auth;
         this.logger = logger;
+        this.baseDir = baseDir ?? auth?.authDir;
     }
     async listModels() {
         const rawModels = await this.client.listModels();
@@ -98,7 +101,67 @@ export class AntigravityEngineAdapter {
             model: targetModel,
             effort: request.effort ?? null,
         });
+        let subagentTracker = null;
+        let pollTimer = null;
+        let turnFinished = false;
+        const ensureTracker = (convId) => {
+            if (!convId || subagentTracker)
+                return;
+            subagentTracker = new AntigravitySubagentTracker(convId, this.baseDir, this.logger);
+        };
+        if (request.threadId) {
+            ensureTracker(request.threadId);
+        }
+        const stopSubagentPolling = () => {
+            turnFinished = true;
+            if (pollTimer) {
+                clearInterval(pollTimer);
+                pollTimer = null;
+            }
+        };
+        const startSubagentPolling = () => {
+            if (pollTimer || turnFinished)
+                return;
+            pollTimer = setInterval(async () => {
+                if (turnFinished) {
+                    stopSubagentPolling();
+                    return;
+                }
+                if (!subagentTracker && agTurn.conversationId) {
+                    ensureTracker(agTurn.conversationId);
+                }
+                if (subagentTracker) {
+                    try {
+                        const res = await subagentTracker.poll();
+                        if (res.newToolEvents && res.newToolEvents.length > 0) {
+                            for (const ev of res.newToolEvents) {
+                                emitter.emit('tool', {
+                                    name: `[${ev.subagentName}] ${ev.toolName}`,
+                                    args: ev.args,
+                                    status: ev.status,
+                                    stepIndex: ev.stepIndex,
+                                    summary: ev.summary,
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        // ignore polling errors
+                    }
+                }
+            }, 1000);
+            pollTimer.unref?.();
+        };
+        startSubagentPolling();
+        let emittedConvId = null;
         agTurn.on('event', (ev) => {
+            if (ev.conversationId) {
+                ensureTracker(ev.conversationId);
+                if (emittedConvId !== ev.conversationId) {
+                    emittedConvId = ev.conversationId;
+                    emitter.emit('conversation', ev.conversationId);
+                }
+            }
             switch (ev.kind) {
                 case 'text':
                     emitter.emit('delta', ev.delta);
@@ -114,6 +177,7 @@ export class AntigravityEngineAdapter {
                     });
                     break;
                 case 'result': {
+                    stopSubagentPolling();
                     const res = {
                         kind: 'result',
                         status: ev.status === 'SUCCESS' ? 'SUCCESS' : 'ERROR',
@@ -135,33 +199,45 @@ export class AntigravityEngineAdapter {
             }
         });
         agTurn.on('error', (err) => {
+            stopSubagentPolling();
             emitter.emit('error', err);
         });
         agTurn.on('exit', (code) => {
+            stopSubagentPolling();
             emitter.emit('exit', code);
         });
         return {
-            turnId: agTurn.conversationId ?? undefined,
-            cancel: () => agTurn.cancel(),
+            get turnId() {
+                return agTurn.conversationId ?? undefined;
+            },
+            cancel: () => {
+                stopSubagentPolling();
+                agTurn.cancel();
+            },
             waitForResult: async () => {
-                const ev = await agTurn.waitForResult();
-                if (!ev || ev.kind !== 'result')
-                    return null;
-                return {
-                    kind: 'result',
-                    status: ev.status === 'SUCCESS' ? 'SUCCESS' : 'ERROR',
-                    response: ev.response || ev.error || (ev.status === 'ERROR' ? 'Antigravity execution failed' : ''),
-                    error: ev.error || (ev.status === 'ERROR' ? 'Antigravity execution failed' : undefined),
-                    conversationId: ev.conversationId,
-                    usage: ev.usage
-                        ? {
-                            inputTokens: ev.usage.input_tokens,
-                            outputTokens: ev.usage.output_tokens,
-                            cachedTokens: ev.usage.cache_read_tokens,
-                            totalTokens: ev.usage.total_tokens,
-                        }
-                        : undefined,
-                };
+                try {
+                    const ev = await agTurn.waitForResult();
+                    if (!ev || ev.kind !== 'result')
+                        return null;
+                    return {
+                        kind: 'result',
+                        status: ev.status === 'SUCCESS' ? 'SUCCESS' : 'ERROR',
+                        response: ev.response || ev.error || (ev.status === 'ERROR' ? 'Antigravity execution failed' : ''),
+                        error: ev.error || (ev.status === 'ERROR' ? 'Antigravity execution failed' : undefined),
+                        conversationId: ev.conversationId,
+                        usage: ev.usage
+                            ? {
+                                inputTokens: ev.usage.input_tokens,
+                                outputTokens: ev.usage.output_tokens,
+                                cachedTokens: ev.usage.cache_read_tokens,
+                                totalTokens: ev.usage.total_tokens,
+                            }
+                            : undefined,
+                    };
+                }
+                finally {
+                    stopSubagentPolling();
+                }
             },
             on: (event, listener) => {
                 emitter.on(event, listener);
@@ -195,17 +271,22 @@ export class AntigravityEngineAdapter {
                 }
                 const rotated = await this.auth.rotateNextCandidate(failingName);
                 const nextAccountName = rotated.account.email || rotated.account.name;
-                await ctx.sendMessage(ctx.request.locale === 'zh'
-                    ? `🛡️ **检测到 Google 安全验证风控 (Verification Required)**\n\n` +
-                        `• **受限账号**: \`${failingEmail}\` (已自动暂停并冷却)\n` +
-                        `• **故障恢复**: 已无感切换至备用账号 \`${nextAccountName}\`，正在继续执行您的任务…\n\n` +
-                        `💡 **如何人工解除该账号风控**：\n` +
-                        `1. 可在终端/CLI 执行 \`agy -p "hi"\`，在弹出的浏览器完成人机验证；\n` +
-                        `2. 或在 Telegram 发送 \`/login\` 重新授权该账号后即可恢复。`
-                    : `🛡️ **Google Security Verification Triggered (Verification Required)**\n\n` +
-                        `• **Affected**: \`${failingEmail}\` (paused & cooling)\n` +
-                        `• **Failover**: Switched to \`${nextAccountName}\`, continuing your task…\n\n` +
-                        `💡 **How to resolve**: Complete verification via \`agy -p "hi"\` in browser or run \`/login\` in Telegram.`);
+                try {
+                    await ctx.sendMessage(ctx.request.locale === 'zh'
+                        ? `🛡️ **检测到 Google 安全验证风控 (Verification Required)**\n\n` +
+                            `• **受限账号**: \`${failingEmail}\` (已自动暂停并冷却)\n` +
+                            `• **故障恢复**: 已无感切换至备用账号 \`${nextAccountName}\`，正在继续执行您的任务…\n\n` +
+                            `💡 **如何人工解除该账号风控**：\n` +
+                            `1. 可在终端/CLI 执行 \`agy -p "hi"\`，在弹出的浏览器完成人机验证；\n` +
+                            `2. 或在 Telegram 发送 \`/login\` 重新授权该账号后即可恢复。`
+                        : `🛡️ **Google Security Verification Triggered (Verification Required)**\n\n` +
+                            `• **Affected**: \`${failingEmail}\` (paused & cooling)\n` +
+                            `• **Failover**: Switched to \`${nextAccountName}\`, continuing your task…\n\n` +
+                            `💡 **How to resolve**: Complete verification via \`agy -p "hi"\` in browser or run \`/login\` in Telegram.`);
+                }
+                catch {
+                    /* messaging may fail during network glitch */
+                }
                 await ctx.retryTurn(ctx.retryCount + 1);
                 return true;
             }
@@ -224,9 +305,14 @@ export class AntigravityEngineAdapter {
                         this.auth.markCooldown(active.email, 30 * 60 * 1000);
                 }
                 const rotated = await this.auth.rotateNextCandidate(active?.name);
-                await ctx.sendMessage(ctx.request.locale === 'zh'
-                    ? `⚠️ 检测到当前账号配额超限或凭据失效，已标记进入 30 分钟冷却，自动切换到账号 \`${rotated.account.email || rotated.account.name}\` 并重试…`
-                    : `⚠️ Quota or auth issue detected. Marked account into 30m cooldown, switched to \`${rotated.account.email || rotated.account.name}\` and retrying…`);
+                try {
+                    await ctx.sendMessage(ctx.request.locale === 'zh'
+                        ? `⚠️ 检测到当前账号配额超限或凭据失效，已标记进入 30 分钟冷却，自动切换到账号 \`${rotated.account.email || rotated.account.name}\` 并重试…`
+                        : `⚠️ Quota or auth issue detected. Marked account into 30m cooldown, switched to \`${rotated.account.email || rotated.account.name}\` and retrying…`);
+                }
+                catch {
+                    /* messaging may fail during network glitch */
+                }
                 await ctx.retryTurn(ctx.retryCount + 1);
                 return true;
             }
@@ -238,17 +324,69 @@ export class AntigravityEngineAdapter {
         }
         const isCapacity = isCapacityOrUnavailableError(ctx.error);
         if (isCapacity && ctx.retryCount < 2) {
-            await ctx.sendMessage(ctx.request.locale === 'zh'
-                ? `⏳ Google 模型服务临时繁忙 (503 Unavailable)，等待 2 秒后自动重试 (第 ${ctx.retryCount + 1}/2 次)…`
-                : `⏳ Google model temporarily unavailable (503), retrying in 2s (attempt ${ctx.retryCount + 1}/2)…`);
+            try {
+                await ctx.sendMessage(ctx.request.locale === 'zh'
+                    ? `⏳ Google 模型服务临时繁忙 (503 Unavailable)，等待 2 秒后自动重试 (第 ${ctx.retryCount + 1}/2 次)…`
+                    : `⏳ Google model temporarily unavailable (503), retrying in 2s (attempt ${ctx.retryCount + 1}/2)…`);
+            }
+            catch {
+                /* messaging may fail during network glitch */
+            }
             await new Promise((r) => setTimeout(r, 2000));
             await ctx.retryTurn(ctx.retryCount + 1);
             return true;
         }
         if (isCapacity) {
-            await ctx.sendMessage(ctx.request.locale === 'zh'
-                ? `⚠️ **Google 模型容量繁忙 (503 UNAVAILABLE)**\n\nGoogle 服务端当前模型 (\`${ctx.request.model}\`) 暂时无可用容量。\n\n💡 **建议方案**：\n• 稍等 1 分钟后重试\n• 发送 /setup 或 /models 切换为 \`gemini-3.1-pro-high\` 继续`
-                : `⚠️ **Model Capacity Unavailable (503)**\n\nGoogle servers have no capacity for \`${ctx.request.model}\` right now.\n\n💡 Tip: Wait 1 minute or switch model via /setup or /models.`);
+            try {
+                await ctx.sendMessage(ctx.request.locale === 'zh'
+                    ? `⚠️ **Google 模型容量繁忙 (503 UNAVAILABLE)**\n\nGoogle 服务端当前模型 (\`${ctx.request.model}\`) 暂时无可用容量。\n\n💡 **建议方案**：\n• 稍等 1 分钟后重试\n• 发送 /setup 或 /models 切换为 \`gemini-3.1-pro-high\` 继续`
+                    : `⚠️ **Model Capacity Unavailable (503)**\n\nGoogle servers have no capacity for \`${ctx.request.model}\` right now.\n\n💡 Tip: Wait 1 minute or switch model via /setup or /models.`);
+            }
+            catch {
+                /* messaging may fail during network glitch */
+            }
+            return true;
+        }
+        const isNetwork = isTransientNetworkError(ctx.error);
+        if (isNetwork && ctx.retryCount < 3) {
+            const backoffMs = Math.min(15000, 3000 * Math.pow(2, ctx.retryCount));
+            const delaySec = Math.round(backoffMs / 1000);
+            try {
+                await ctx.sendMessage(ctx.request.locale === 'zh'
+                    ? `🌐 **检测到网络波动或连接中断**\n\n` +
+                        `• **错误提示**: \`${ctx.error.slice(0, 100)}\`\n` +
+                        `• **安全重试**: 将在 ${delaySec} 秒后自动重试并在网络恢复后继续执行 (第 ${ctx.retryCount + 1}/3 次)…`
+                    : `🌐 **Network Fluctuation Detected**\n\n` +
+                        `• **Error**: \`${ctx.error.slice(0, 100)}\`\n` +
+                        `• **Auto-Retry**: Retrying in ${delaySec}s to resume execution after network recovery (attempt ${ctx.retryCount + 1}/3)…`);
+            }
+            catch {
+                /* messaging may fail during network glitch */
+            }
+            await new Promise((r) => setTimeout(r, backoffMs));
+            try {
+                await ctx.retryTurn(ctx.retryCount + 1);
+            }
+            catch (err) {
+                this.logger?.error('antigravity.retry_turn_failed', { error: String(err) });
+            }
+            return true;
+        }
+        if (isNetwork) {
+            try {
+                await ctx.sendMessage(ctx.request.locale === 'zh'
+                    ? `⚠️ **网络连接连续中断 (已重试 3 次)**\n\n` +
+                        `• **错误详情**: \`${ctx.error.slice(0, 150)}\`\n` +
+                        `• **说明**: 代理或网络暂时无法稳定连接 Google 服务端。\n\n` +
+                        `💡 **建议方案**：\n• 请检查本机网络与代理设置（如 Clash / v2ray / proxy）\n• 网络恢复后直接再次发送您的指令即可继续`
+                    : `⚠️ **Network Connection Failed (Retried 3 times)**\n\n` +
+                        `• **Error**: \`${ctx.error.slice(0, 150)}\`\n` +
+                        `• **Note**: Unable to reach Google servers stably.\n\n` +
+                        `💡 Tip: Please check your network/proxy connection, and send your message again once restored.`);
+            }
+            catch {
+                /* messaging may fail during network glitch */
+            }
             return true;
         }
         return false;

package/dist/antigravity/auth.d.ts

@@ -119,3 +119,8 @@ export declare class AntigravityAuthManager {
     private atomicCopy;
     private atomicWriteJson;
 }
+/**
+ * Links Antigravity OAuth tokens and paused account state from sourceAuthDir into targetAuthDir.
+ * Does NOT link conversation_summaries.db or brain/ to keep conversation history isolated per bot.
+ */
+export declare function linkAntigravityAuthTokens(sourceAuthDir: string, targetAuthDir: string): void;

package/dist/antigravity/auth.js

@@ -894,3 +894,40 @@ export class AntigravityAuthManager {
         await fs.rename(tempPath, destPath);
     }
 }
+/**
+ * Links Antigravity OAuth tokens and paused account state from sourceAuthDir into targetAuthDir.
+ * Does NOT link conversation_summaries.db or brain/ to keep conversation history isolated per bot.
+ */
+export function linkAntigravityAuthTokens(sourceAuthDir, targetAuthDir) {
+    const resolvedSource = path.resolve(sourceAuthDir);
+    const resolvedTarget = path.resolve(targetAuthDir);
+    if (resolvedSource === resolvedTarget)
+        return;
+    fsSync.mkdirSync(resolvedTarget, { recursive: true, mode: 0o700 });
+    if (!fsSync.existsSync(resolvedSource))
+        return;
+    const entries = fsSync.readdirSync(resolvedSource, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isFile() &&
+            (entry.name === 'antigravity-oauth-token' ||
+                entry.name.startsWith('antigravity-oauth-token_') ||
+                entry.name === 'paused-accounts.json')) {
+            const sourceFile = path.join(resolvedSource, entry.name);
+            const targetFile = path.join(resolvedTarget, entry.name);
+            try {
+                if (fsSync.existsSync(targetFile) || fsSync.lstatSync(targetFile, { throwIfNoEntry: false })) {
+                    fsSync.unlinkSync(targetFile);
+                }
+                fsSync.symlinkSync(sourceFile, targetFile);
+            }
+            catch {
+                try {
+                    fsSync.copyFileSync(sourceFile, targetFile);
+                }
+                catch {
+                    // best-effort fallback
+                }
+            }
+        }
+    }
+}

package/dist/antigravity/client.js

@@ -183,8 +183,14 @@ export class AntigravityAppClient {
                 conversationId: activeConversationId,
                 stderr: stderrBuffer ? stderrBuffer.slice(-200) : undefined,
             });
-            if (!finalResultEvent && code !== 0) {
-                const errorMsg = stderrBuffer.trim() || `Process exited with code ${code}${signal ? ` (${signal})` : ''}`;
+            if (!finalResultEvent) {
+                const isCanceled = signal === 'SIGINT' || signal === 'SIGTERM';
+                const errorMsg = isCanceled
+                    ? 'Execution canceled'
+                    : (stderrBuffer.trim() ||
+                        (code !== 0
+                            ? `Process exited with code ${code}${signal ? ` (${signal})` : ''}`
+                            : 'Process exited unexpectedly before producing a result'));
                 const errResult = {
                     kind: 'result',
                     conversationId: activeConversationId || '',

package/dist/antigravity/controller.d.ts

@@ -12,6 +12,7 @@ import type { CodexAppClient, CodexAppServerRuntimeStatus } from '../codex_app/c
 import { OpencodeEngineAdapter } from '../opencode/adapter.js';
 import type { OpencodeAppClient } from '../opencode/client.js';
 import { BridgeSessionCore } from '../controller/controller.js';
+import type { SelfUpdateRuntime } from '../update.js';
 export interface UnifiedBridgeRuntimeStatus {
     running: boolean;
     connected: boolean;
@@ -33,6 +34,7 @@ export interface UnifiedBridgeCoreOptions {
     opencodeApp?: OpencodeAppClient | undefined;
     opencodeAdapter?: OpencodeEngineAdapter | undefined;
     defaultBackendId?: 'antigravity' | 'codex' | 'opencode' | string | undefined;
+    selfUpdater?: SelfUpdateRuntime | undefined;
 }
 export declare class UnifiedBridgeCore {
     private readonly config;
@@ -49,6 +51,7 @@ export declare class UnifiedBridgeCore {
     readonly codexCore?: BridgeSessionCore | undefined;
     private readonly opencodeAdapter?;
     private readonly defaultBackendId;
+    private readonly selfUpdater?;
     private readonly orchestrator;
     private readonly watchers;
     private readonly pendingAgyRenames;
@@ -87,6 +90,8 @@ export declare class UnifiedBridgeCore {
     private watchConversation;
     private unwatchConversation;
     private scheduleWatcherPoll;
+    private getScopeLocale;
+    private renderWatcherProgressUpdate;
     private pollWatcher;
     private handleWatcherTranscriptEntry;
     private sendAuthMenu;