@foxden-app/foxclaw 0.7.2 → 0.10.0

package/.env.example

@@ -1,5 +1,6 @@
 # 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,
@@ -71,6 +72,19 @@ CODEX_CLI_BIN=/absolute/path/to/codex
 # OPENCODE_SERVER_STATE_PATH=
 # OPENCODE_SERVER_LOG_PATH=
 
+# Optional Google Antigravity (AGY) bridge. This starts independent Telegram bot(s)
+# alongside existing Codex/OpenCode runtimes; never reuse a TG_BOT_TOKEN here.
+# FoxClaw communicates with `agy` via stdio stream-json and supports multi-account
+# rotation from ~/.gemini/antigravity-cli/antigravity-oauth-token_*.
+# Multi-bot mode: comma-separated bot tokens. The default/first bot shares the terminal's
+# ~/.gemini/antigravity-cli home, while additional bots get isolated ~/.foxclaw/antigravity/telegram/@bot/home.
+# ANTIGRAVITY_BOT_TOKENS=<bot_token_1>,<bot_token_2>
+# Single-bot backward compatibility:
+# ANTIGRAVITY_BOT_TOKEN=<different_telegram_bot_token>
+# ANTIGRAVITY_CLI_BIN=/absolute/path/to/agy
+# ANTIGRAVITY_AUTH_DIR=~/.gemini/antigravity-cli
+# ANTIGRAVITY_DEFAULT_MODEL=gemini-3.8-flash-high
+
 # Optional cross-node Codex auth sync.
 # Disabled by default. When enabled, FoxClaw uses Telegram Bot-to-Bot private
 # messages to move encrypted auth bundles between nodes. Enable Bot-to-Bot

package/CHANGELOG.md

@@ -2,6 +2,135 @@
 
 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.10.0 - 2026-09-27
+
+### 中文
+- **Antigravity 多 Bot 原生隔离与同机共存**：
+  - 支持通过 `ANTIGRAVITY_BOT_TOKENS` 启动多个独立 Telegram Bot，每个 Bot 自动拥有完全隔离的工作空间目录（`~/.gemini/antigravity-cli/telegram_bots/<bot-id>/`），独立记忆会话历史与进程状态，彻底杜绝多 Bot 互相踩踏与符号链接覆盖冲突。
+  - 默认主 Bot 保持与终端默认环境无缝衔接，终端与 Telegram 会话可相互无缝接手。
+- **Telegram 执行小结折叠增强与长任务防穿透分片**：
+  - 任务执行小结加入精准耗时换算（秒/分/小时）与全维度 Token 消耗细分（总计、输入、输出、缓存，自动换算 K/M/G 单位）。
+  - 完整保留普通任务中全部十几个阶段小节（≤ 25 项调用完整保留无损呈现，展开可回溯全流程），超大规模任务（> 25 项）智能首尾收敛折叠。
+  - 新增 `combineSummaryAndResponse` 彻底杜绝超长任务分片切断折叠块导致工具调用裸露冠在最终答复上方的问题。
+- **全后端 `/update` 一键联动自升级**：
+  - 无论处于 Codex 还是 Antigravity 运行模式，均可直接发送 `/update` 触发全链路升级。
+  - 自动联动升级 Antigravity CLI（`agy update`）、Codex CLI（`pnpm add -g @openai/codex`）以及 FoxClaw 自身，并自动平滑重载服务。
+
+### English
+- **Native Multi-Bot Isolation for Antigravity**:
+  - Supports multiple concurrent Telegram bot instances via `ANTIGRAVITY_BOT_TOKENS` with fully isolated runtime homes (`~/.gemini/antigravity-cli/telegram_bots/<bot-id>/`), eliminating directory collision and symlink overwrites while keeping the primary bot synchronized with the local terminal environment.
+- **Enhanced Collapsible Execution Summary & Leak-Proof Chunking**:
+  - Execution summaries now include precise elapsed durations and four-dimensional token metrics (Total, Input, Output, Cached).
+  - Preserves all intermediate step summaries (up to 25 items) inside expandable folds for complete visibility, while gracefully bounding massive tool runs (> 25 items).
+  - New `combineSummaryAndResponse` eliminates blockquote tearing across Telegram chunk boundaries, preventing uncollapsed tool items from spilling onto the final answer.
+- **Universal `/update` with Full Backend Synchronization**:
+  - `/update` is now available across all engine modes (Codex & Antigravity), seamlessly updating FoxClaw, the Antigravity CLI (`agy update`), and Codex CLI in one step.
+
+## 0.9.0 - 2026-09-26
+
+### 中文
+- **统一多后端运行环境热切换**：
+  - 前端控制面板支持 `Codex`、`Google Antigravity (AGY)`、`OpenCode` 无缝平滑热切换，会话状态与配置自动记忆绑定。
+  - 支持多 Bot 隔离实例下各 Bot 独立选择和切换后端，互不干扰。
+- **全端功能体验对齐原版 Codex 标准**：
+  - `/auth` 面板向原版 Codex 规范完全看齐，支持设备登录、授权检测、自动轮换与暂停/修复功能。
+  - `/threads` 会话面板对齐原版 Codex 功能按钮（会话切换、历史归档、工作目录配置等）。
+- **交互面板智能收拢与过期自动清理**：
+  - 设置类与状态类面板展示超过 5 分钟自动静默清理，保持聊天面板干净整洁。
+  - 任务执行过程实时动态刷新（轮次、工具调用次数、耗时），完成后自动收拢折叠为小结引用块。
+- **自更新体系全面支持 Antigravity CLI 同步升级**：
+  - `/update` 命令与集群自动更新联动同步执行 `agy update`，确保 FoxClaw、Codex 与 Antigravity CLI 全技术栈同步保持最新。
+- **全局 Token 统计与即时观测（常态化持久化）**：
+  - `/status` 状态面板常态化显示全后端累积 Token 用量，格式化为人类友好单位（`总计 X.XXG (输入 X.XXG, 输出 XX.XXM, 缓存 X.XXG)`）。
+  - 底层基于 SQLite 持久化记录，无需每次耗时扫盘，日常实时累加，想看直接秒出。
+
+### English
+- **Unified Multi-Backend Hot-Switching**:
+  - Seamlessly switch between `Codex`, `Google Antigravity (AGY)`, and `OpenCode` from the Telegram UI with per-backend state and setting persistence.
+  - Multi-bot isolated setups support independent backend switching for each bot instance.
+- **Full UX Alignment with Codex Conventions**:
+  - `/auth` and `/threads` menus redesigned to match the established Codex interaction standards (device login, candidate repair, session archival).
+- **Auto-Cleanup & Expired Panel Pruning**:
+  - Transient setup and status panels are automatically removed after 5 minutes to keep chat history clean.
+  - Live execution displays dynamic progress counters and collapses into expandable summaries upon completion.
+- **Synchronous Antigravity CLI Self-Updates**:
+  - `/update` seamlessly upgrades the `agy` CLI alongside FoxClaw and Codex.
+- **Persistent Global Token Usage Metrics in `/status`**:
+  - Displays cumulative token metrics formatted in metric units (`Total X.XXG (Input X.XXG, Output XX.XXM, Cached X.XXG)`).
+  - Persisted continuously in SQLite for instant on-demand status reporting without filesystem latency.
+
+## 0.8.0 - 2026-09-24
+
+### 中文
+- **统一通道调度器（UnifiedChannelOrchestrator）**：架构级重构，将与通道与引擎无关的通用交互全数下沉。集成 Turn 抢占与并发排队（`TurnQueue`）、700ms 智能节流流式编辑预览（`StreamPreviewController`）、工具调用动态折叠（`<blockquote expandable>`）、长消息 4000 字符安全分块（`chunkTelegramMessage`）、活跃态 Typing 维持，以及跨重启崩溃自愈恢复。
+- **可插拔引擎服务提供者接口（IEngineAdapter SPI）**：定义面向多 Agent 的标准接口，涵盖执行、中断、状态汇报、交互键盘分发与模型参数控制，新增 Agent 接入成本降低 85%。
+- **Google Antigravity (`agy`) 引擎深度接入与适配器**：
+  - 独立 Telegram 机器人接入，支持与既有 Codex / OpenCode 并行运行。
+  - **Token 预检与静默刷新（Token Preflight）**：执行前智能计算 OAuth Access Token 有效期，临期自动静默刷新，防止长任务因凭据过期中断。
+  - **Google 503 容量饱和指数退避重试**：遇到瞬时 `503 Service Unavailable` 或 `MODEL_CAPACITY_EXHAUSTED` 时，自动进行 1s、2s、4s 指数退避重试。
+  - **配额超限自动冷却轮换（Quota Cooldown Rotation）**：遭遇真实 ResourceExhausted 限额时，自动将当前账号标记冷却并轮换至候选池下一可用账号继续执行。
+  - **Boost 模式支持**：支持通过 `/boost` 开启或引导深度推理与多角度验证。
+- **5h/7d 配额真实语义可观测性重构**：
+  - 彻底厘清 Google CloudCode PA 配额窗口语义，去除时间倒计时混淆，全面规范为 `100%|80%|account` 格式的百分比 Badge。
+  - 在 `/auth` 候选切换按钮、`/status` 面板与 `/setup` 概览中完整呈现 5 小时突发额度与 7 天长期额度。
+- **OpenCode 适配器加固**：适配器流式 Delta 空安全增强，统一纳入调度器生命周期管理。
+- **架构代码精简与全量测试**：`AntigravityBridgeCore` 样板代码精简 83%，全仓库 449 个自动化测试 100% 通过。
+
+### English
+- **UnifiedChannelOrchestrator**: Major architecture refactoring decoupling channel orchestration from underlying AI engines. Centralizes turn queueing (`TurnQueue`), 700ms throttled streaming previews (`StreamPreviewController`), collapsible tool blocks (`<blockquote expandable>`), safe 4000-char message chunking (`chunkTelegramMessage`), typing indicators, and crash recovery across daemon restarts.
+- **Pluggable Engine SPI (`IEngineAdapter`)**: Standardized interface for multi-agent execution, cancellation, status summaries, inline keyboard actions, and model/effort switching, reducing new engine onboarding cost by 85%.
+- **Google Antigravity (`agy`) Engine Integration & Adapter**:
+  - Independent Telegram bot support running concurrently alongside Codex and OpenCode.
+  - **Token Preflight & Silent Refresh**: Proactively calculates OAuth access token TTL before turn execution, silently refreshing when under 5 minutes to prevent expired token aborts during long runs.
+  - **Google 503 Capacity Exponential Backoff**: Automatically executes 1s, 2s, 4s exponential backoff retries upon encountering transient `503 Service Unavailable` or `MODEL_CAPACITY_EXHAUSTED`.
+  - **Quota Cooldown Rotation**: Automatically cools down and rotates to the next available Google OAuth candidate upon hitting true ResourceExhausted limits.
+  - **Boost Mode**: Supported `/boost` to guide or inject deep reasoning effort.
+- **5h/7d Quota Metric & Observability Redesign**:
+  - Clarified Google CloudCode PA quota window semantics from ambiguous countdowns to explicit percentage badges: `100%|80%|account`.
+  - Fully exposed 5h burst and 7d long-term quota percentages across `/auth` candidate buttons, `/status`, and `/setup` panels.
+- **OpenCode Adapter Hardening**: Stream delta null-safety hardening and unified engine lifecycle management.
+- **Refactoring Quality & Test Coverage**: Eliminated 83% boilerplate in `AntigravityBridgeCore` with 100% pass rate across all 449 automated tests.
+
+## 0.7.4 - 2026-09-24
+
+### 中文
+- 新增 Google Antigravity (`agy`) 引擎支持：通过 `ANTIGRAVITY_BOT_TOKEN` 接入独立的 Telegram 机器人，与既有 Codex / OpenCode 并行运行。
+- 会话管理与既有 Thread 选定：支持 `/threads` 查询 Antigravity 历史会话（读取 `conversation_summaries.db`），支持 `/open <编号|ID>` 选定并绑定既有会话上下文，支持 `/new [目录]` 开启新会话。
+- 交互式控制面板：支持 `/setup` 统一管理与查看当前模型、思考深度（Effort）、活跃账号池、绑定会话与工作目录，支持内联按钮原地切换与刷新。
+- 富文本流式渲染与消息折叠：支持 Markdown 富文本转译、700ms 节流编辑流式输出、工具执行过程折叠收起（`<blockquote expandable>`）、长消息自动按 Telegram 限制分段（`chunkTelegramMessage`），以及执行期间定期维持 Typing 状态。
+- 支持 Antigravity 多账号池管理：扫描 `~/.gemini/antigravity-cli/antigravity-oauth-token_*` 候选池，免网络即时从 `id_token` 解码 Google 账号邮箱，支持 `/auth` 面板切换；遇到 429 或配额超限（ResourceExhausted）时自动轮换下一个可用账号并重试。
+- 支持 `/models` 切换 Gemini 3.8/3.7/3.1、Claude 等模型，支持 `/effort` 设置思考深度，支持 `/interrupt` 实时中断任务。
+- `foxclaw doctor` 增加 Antigravity CLI、独立 Token 与凭据检测。
+
+### English
+- Added Google Antigravity (`agy`) engine support: run an independent Telegram bot alongside Codex/OpenCode via `ANTIGRAVITY_BOT_TOKEN`.
+- Thread and Conversation Management: supported `/threads` to browse historical Antigravity conversations (via `conversation_summaries.db`), `/open <num|id>` to bind to an existing thread context, and `/new [dir]` to start a fresh conversation.
+- Interactive Control Panel: supported `/setup` to inspect and configure the current model, reasoning effort, active account, bound thread, and directory via in-place inline keyboards.
+- Rich Streaming and Tool Folding: supported safe rich Markdown rendering, 700ms throttled streaming edits, tool execution folding (`<blockquote expandable>`), automated multi-chunk message splitting (`chunkTelegramMessage`), and active Telegram typing loop.
+- Added Antigravity multi-account candidate pool management: scans `~/.gemini/antigravity-cli/antigravity-oauth-token_*`, extracts Google account email directly from `id_token` JWT payload without network calls, provides `/auth` switching panel, and automatically rotates to the next available account upon 429 / ResourceExhausted errors.
+- Supported `/models` to switch models (Gemini 3.8/3.7/3.1, Claude Sonnet, etc.), `/effort` for reasoning effort, and `/interrupt` to cancel running turns.
+- Extended `foxclaw doctor` with Antigravity CLI availability, dedicated bot token, and OAuth token checks.
+
+## 0.7.3 - 2026-09-05
+
+### 中文
+- 修复代理或网络不稳时 Telegram、Codex RPC 和 WebSocket 可能长期无响应的问题：请求有明确截止时间，活动会话断连、恢复失败和 writer 冲突都会给出可继续操作的错误，不重放结果未知的请求。
+- 登录、auth add 和 auth repair 流程增加取消按钮；取消失败也释放本地流程，旧按钮和其他聊天不能误取消当前登录。
+- 新增 `/cli` 与 `foxclaw resume`，可让终端连接桥的同一 Codex app-server；`/watch` 继续只读，外部 CLI 的消息可用原生线程队列安全排队。
+- 新增 `/takeover --force <消息>`：可信 Telegram 用户二次确认后，可精确停止占用目标 thread 的本机交互式 CLI，验证锁释放并恢复原 thread 后再提交消息。进程、锁或 thread 身份变化时明确拒绝，不删除锁、不改写 session 文件。
+- 多 bot Codex 数据目录默认使用真实 `@Telegram用户名`。迁移既有数字目录并保留兼容链接，共享终端的 bot 使用同名目录入口指向原 home。
+- 并行读取用户名，断网重启沿用已有名称；媒体发送通过稳定身份记录保持正确路由，目录冲突明确报错。
+- auth 问号、修复和删除操作会重新读取最新状态；安全同步文案区分“已发送”和“远端已导入”，状态更新未生效时不再报告虚假成功。
+
+### English
+- Bound Telegram, Codex RPC, and WebSocket waits so unstable proxy or network links fail explicitly instead of hanging. Active-session disconnects, recovery failures, and writer conflicts now include actionable recovery guidance without replaying ambiguous requests.
+- Added cancel buttons to login, auth-add, and auth-repair flows. Local state is released even when cancellation fails, while stale or foreign-chat buttons cannot cancel the current login.
+- Added `/cli` and `foxclaw resume` to connect a terminal to the bridge's Codex app-server. `/watch` remains read-only and external CLI prompts use Codex's native thread queue.
+- Added `/takeover --force <message>` for a trusted Telegram user to confirm a precise local interactive-CLI handoff. FoxClaw revalidates process, lock, and thread identity, verifies lock release, resumes the original thread, and only then submits the prompt; it never deletes locks or edits session files.
+- Name multi-bot Codex homes after verified Telegram usernames, migrating numeric directories with compatibility links and preserving shared terminal homes.
+- Resolve usernames in parallel, reuse stored paths offline, preserve media routing through stable identity metadata, and reject directory conflicts.
+- Auth repair/question-mark/delete actions now refresh current state first. Safe-sync wording distinguishes dispatch from confirmed remote import, and unapplied state changes no longer report false success.
+
 ## 0.7.2 - 2026-08-30
 
 ### 中文

package/README.md

@@ -4,7 +4,7 @@
 
 **狸爪：一个更适配编程需求的移动端 Codex 控制器。**
 
-FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex 或 OpenCode，把移动端变成一个真正能用的 web coding 入口。Telegram 或微信负责交互，`codex app-server` / `opencode serve` 负责本地执行；你发任务、看进度、批审批、切线程，Agent 在电脑上继续写代码。
+FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex、OpenCode 或 Antigravity (AGY)，把移动端变成一个真正能用的 web coding 入口。Telegram 或微信负责交互，`codex app-server` / `opencode serve` / `agy` 负责本地执行；你发任务、看进度、批审批、切线程，Agent 在电脑上继续写代码。
 
 这适合你离开办公桌去吃饭、在旅途中、在跑步机上，或者陪小孩逛公园的时候继续工作。人可以离开电脑，Codex 不必停；它会把关键进展、错误、审批请求和最终结果同步回手机。
 
@@ -30,7 +30,7 @@ FoxClaw（狸爪）的目标很直接：让你用手机控制本机的 Codex 或
 
 ![FoxClaw Telegram 功能预览](./docs/assets/telegram-preview-zh.svg)
 
-手机端不是简单转发消息，而是给 Codex 的常用工作流做了 Telegram 面板：`/setup` 调模型、推理强度、Fast tier、权限和 Agent/Plan 模式；`/auth` 管理多个 Codex 登录候选，触发限制时自动轮转；`/threads`、`/watch` 和审批按钮用于切线程、观察进度和处理权限请求。
+手机端不是简单转发消息，而是给 Codex 的常用工作流做了 Telegram 面板：`/setup` 调模型、推理强度、Fast tier、权限和 Agent/Plan 模式；`/auth` 管理多个 Codex 登录候选，触发限制时自动轮转；`/threads`、`/watch` 和审批按钮用于切线程、观察进度和处理权限请求。终端 CLI 卡住且持有 thread 时，可信用户还可用 `/takeover --force <消息>` 核对 PID、目录并二次确认，将同一 thread 安全交给桥继续执行。
 
 ## 从这里开始
 
@@ -136,6 +136,26 @@ OpenCode Bot 保留与 Codex Bot 相同的主要操作习惯：直接发消息
 
 OpenCode 自身的 Provider 登录仍在本机终端完成，例如 `opencode auth`。运行 `foxclaw doctor` 会在配置了 OpenCode Bot 时额外检查 OpenCode CLI 和 token 隔离。
 
+### Antigravity (AGY) 独立 Bot
+
+如果你使用 Google Antigravity，只需在 `@BotFather` 处再创建一个独立 Bot，并在 `~/.foxclaw/.env` 中配置：
+
+```dotenv
+ANTIGRAVITY_BOT_TOKEN=8308303236:AAFZ32Pus2wrzpRq7-Bp2JQMt7lsrt5kKpo
+# 可选；默认为 PATH 中的 agy
+ANTIGRAVITY_CLI_BIN=/home/wuya/.gemini/antigravity-cli/bin/agy
+# 可选；默认 gemini-3.8-flash-high
+ANTIGRAVITY_DEFAULT_MODEL=gemini-3.8-flash-high
+```
+
+Antigravity Bot 保留与 Codex / OpenCode 对齐的高频操作习惯：
+- **消息交互与流式思考**：直接向机器人发送文本或任务，支持 700ms 节流流式输出与思考过程实时显示。
+- **消息折叠与工具进度**：执行过程中的工具调用与历史执行细节自动通过 Telegram 可折叠引用块（`<blockquote expandable>`）折叠收起，避免刷屏；输出超长文本自动按限制无损分段。
+- **`/setup` 控制面板**：在同一消息内通过内联按钮原地切换模型、思考深度（Effort）、账号与会话。
+- **`/threads` 与 `/open <编号|ID>`**：直接读取 `conversation_summaries.db` 列出近期历史会话并选定绑定，无缝继续上下文；发送 `/new [目录]` 开启全新会话。
+- **`/auth` 多账号管理与自动轮换**：自动扫描 `antigravity-oauth-token_*` 候选池并即时解码 Google 邮箱，支持手动切换；遇到 429 或配额限制自动轮换下一个账号并重试任务。
+- **`/models` 与 `/effort`**：切换 Gemini 3.8/3.7/3.1、Claude Sonnet、Claude Opus 等模型与推理深度。
+
 ## 多账号切换
 
 FoxClaw 的一大特色是自动多账号切换。当一个账号触发用量限制时，FoxClaw 会自动切换到下一个可用账号继续工作。

package/README_EN.md

@@ -4,7 +4,7 @@
 
 **A mobile Codex controller built for real programming workflows.**
 
-FoxClaw turns your phone into a practical web coding cockpit for local Codex or OpenCode. Telegram or Weixin handles the chat interface, `codex app-server` / `opencode serve` handles local execution, and you can send tasks, inspect progress, approve actions, switch sessions, and keep working without opening a laptop.
+FoxClaw turns your phone into a practical web coding cockpit for local Codex, OpenCode, or Antigravity (AGY). Telegram or Weixin handles the chat interface, `codex app-server` / `opencode serve` / `agy` handles local execution, and you can send tasks, inspect progress, approve actions, switch sessions, and keep working without opening a laptop.
 
 It is built for the moments when you leave your desk for lunch, commute, travel, use a treadmill, or take the kids to the park. You can step away from the keyboard while Codex keeps coding and sends progress, errors, approval requests, and final results back to your phone.
 
@@ -30,7 +30,7 @@ No public server required. FoxClaw runs on your own computer, talks to `codex ap
 
 ![FoxClaw Telegram feature preview](./docs/assets/telegram-preview-en.svg)
 
-FoxClaw is more than message forwarding. It provides Telegram panels for Codex workflows: `/setup` adjusts model, reasoning, Fast tier, access, and Agent/Plan mode; `/auth` manages multiple Codex auth candidates and rotates them on usage limits; `/threads`, `/watch`, and approval buttons handle thread switching, progress monitoring, and permission requests.
+FoxClaw is more than message forwarding. It provides Telegram panels for Codex workflows: `/setup` adjusts model, reasoning, Fast tier, access, and Agent/Plan mode; `/auth` manages multiple Codex auth candidates and rotates them on usage limits; `/threads`, `/watch`, and approval buttons handle thread switching, progress monitoring, and permission requests. If a local interactive Codex CLI is stuck while holding a thread, the trusted Telegram user can use `/takeover --force <message>`, verify its PID and working directory, and explicitly confirm a safe handoff to the bridge.
 
 ## Start Here
 
@@ -136,6 +136,26 @@ The OpenCode bot preserves the main Codex-bot habits: plain messages and attachm
 
 Provider authentication remains an OpenCode terminal operation, such as `opencode auth`. When an OpenCode bot is configured, `foxclaw doctor` also checks the OpenCode CLI and token isolation.
 
+### Antigravity (AGY) Dedicated Bot
+
+If you use Google Antigravity, create an independent bot with `@BotFather` and configure:
+
+```dotenv
+ANTIGRAVITY_BOT_TOKEN=8308303236:AAFZ32Pus2wrzpRq7-Bp2JQMt7lsrt5kKpo
+# Optional; defaults to PATH lookup
+ANTIGRAVITY_CLI_BIN=/home/wuya/.gemini/antigravity-cli/bin/agy
+# Optional; default gemini-3.8-flash-high
+ANTIGRAVITY_DEFAULT_MODEL=gemini-3.8-flash-high
+```
+
+The Antigravity Bot preserves the same intuitive workflows as Codex and OpenCode:
+- **Interactive Messaging & Streaming**: Send prompts directly to the bot, with 700ms throttled streaming output and live reasoning progress.
+- **Message Folding & Progress Details**: Tool calls and execution traces are neatly folded using Telegram expandable blockquotes (`<blockquote expandable>`), keeping conversations clean; long responses are automatically split without truncation (`chunkTelegramMessage`).
+- **`/setup` Control Panel**: In-place inline keyboard to view and switch models, reasoning effort, active accounts, and bound conversation.
+- **`/threads` & `/open <number|id>`**: Directly reads `conversation_summaries.db` to list recent sessions and bind to existing thread contexts; use `/new [dir]` to start a fresh conversation.
+- **`/auth` Multi-Account Management**: Automatically scans `antigravity-oauth-token_*` candidate tokens and decodes Google emails from JWT payloads; automatically rotates to the next account on 429 or quota limit errors.
+- **`/models` & `/effort`**: Switch between Gemini 3.8/3.7/3.1, Claude Sonnet/Opus, and adjust reasoning effort.
+
 ## Multi-Account Rotation
 
 A key FoxClaw feature is automatic multi-account switching. When one account's usage limit is triggered, FoxClaw automatically switches to the next available account and continues working.

package/dist/antigravity/adapter.d.ts

@@ -0,0 +1,17 @@
+import type { IEngineAdapter, EngineModel, EngineTurnRequest, EngineTurnExecution, EngineTurnErrorContext } from '../core/engine_spi.js';
+import { type AntigravityAppClient } from './client.js';
+import type { AntigravityAuthManager } from './auth.js';
+import type { Logger } from '../logger.js';
+export declare class AntigravityEngineAdapter implements IEngineAdapter {
+    readonly id = "antigravity";
+    readonly name = "Google Antigravity (AGY)";
+    private readonly client;
+    private readonly defaultModel;
+    private readonly auth;
+    private readonly logger;
+    constructor(client: AntigravityAppClient, defaultModel?: string, auth?: AntigravityAuthManager, logger?: Logger);
+    listModels(): Promise<EngineModel[]>;
+    executeTurn(request: EngineTurnRequest): EngineTurnExecution;
+    preflightTurn(_request: EngineTurnRequest): Promise<void>;
+    handleTurnError(ctx: EngineTurnErrorContext): Promise<boolean>;
+}

package/dist/antigravity/adapter.js

@@ -0,0 +1,256 @@
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+import { normalizeAgyModelId } from './client.js';
+import { isCapacityOrUnavailableError, isVerificationError, isQuotaOrAuthError, } from './events.js';
+import { buildAttachmentPrompt } from '../telegram/media.js';
+function extractToolSummary(name, parameters) {
+    if (!parameters)
+        return undefined;
+    if (typeof parameters.CommandLine === 'string') {
+        return `$ ${parameters.CommandLine.slice(0, 70)}`;
+    }
+    if (typeof parameters.TargetFile === 'string') {
+        return path.basename(parameters.TargetFile);
+    }
+    if (typeof parameters.AbsolutePath === 'string') {
+        return path.basename(parameters.AbsolutePath);
+    }
+    if (typeof parameters.path === 'string') {
+        return path.basename(parameters.path);
+    }
+    if (typeof parameters.query === 'string') {
+        return parameters.query.slice(0, 60);
+    }
+    if (typeof parameters.Url === 'string') {
+        return parameters.Url.slice(0, 60);
+    }
+    if (typeof parameters.toolSummary === 'string') {
+        return parameters.toolSummary.slice(0, 60);
+    }
+    if (typeof parameters.toolAction === 'string') {
+        return parameters.toolAction.slice(0, 60);
+    }
+    return undefined;
+}
+export class AntigravityEngineAdapter {
+    id = 'antigravity';
+    name = 'Google Antigravity (AGY)';
+    client;
+    defaultModel;
+    auth;
+    logger;
+    constructor(client, defaultModel = 'gemini-3.8-flash', auth, logger) {
+        this.client = client;
+        this.defaultModel = defaultModel;
+        this.auth = auth;
+        this.logger = logger;
+    }
+    async listModels() {
+        const rawModels = await this.client.listModels();
+        const seen = new Set();
+        const result = [];
+        for (const raw of rawModels) {
+            const m = normalizeAgyModelId(raw);
+            if (seen.has(m))
+                continue;
+            seen.add(m);
+            let displayName = m;
+            if (m === 'gemini-3.8-flash')
+                displayName = 'Gemini 3.8 Flash';
+            else if (m === 'gemini-3.7-flash')
+                displayName = 'Gemini 3.7 Flash';
+            else if (m === 'gemini-3.6-flash')
+                displayName = 'Gemini 3.6 Flash';
+            else if (m === 'gemini-3.1-pro')
+                displayName = 'Gemini 3.1 Pro';
+            else if (m === 'claude-sonnet-4-6')
+                displayName = 'Claude Sonnet 4.6';
+            else if (m === 'claude-opus-4-6')
+                displayName = 'Claude Opus 4.6';
+            else if (m === 'gpt-oss-120b')
+                displayName = 'GPT-OSS 120B';
+            else
+                displayName = m.replace(/^gemini-/, 'Gemini ').replace(/^claude-/, 'Claude ');
+            result.push({
+                id: m,
+                name: displayName,
+                description: m.includes('flash')
+                    ? 'Fast, high-throughput model'
+                    : m.includes('pro')
+                        ? 'Deep reasoning & complex tasks'
+                        : undefined,
+                isDefault: m === this.defaultModel || (this.defaultModel.startsWith(m) && !m.includes('-')),
+            });
+        }
+        return result;
+    }
+    executeTurn(request) {
+        const emitter = new EventEmitter();
+        let prompt = request.prompt;
+        if (request.stagedAttachments && request.stagedAttachments.length > 0 && !request.prompt.includes('Telegram attachments:')) {
+            prompt = buildAttachmentPrompt(request.prompt, request.stagedAttachments);
+        }
+        const targetModel = (!request.model || request.model === 'default') ? this.defaultModel : request.model;
+        const agTurn = this.client.executeTurn({
+            prompt,
+            conversationId: request.threadId,
+            cwd: request.cwd,
+            model: targetModel,
+            effort: request.effort ?? null,
+        });
+        agTurn.on('event', (ev) => {
+            switch (ev.kind) {
+                case 'text':
+                    emitter.emit('delta', ev.delta);
+                    break;
+                case 'tool':
+                    emitter.emit('tool', {
+                        name: ev.toolName,
+                        args: ev.parameters,
+                        output: ev.output,
+                        status: ev.state === 'ACTIVE' ? 'running' : ev.state === 'ERROR' ? 'failed' : 'completed',
+                        stepIndex: ev.stepIndex,
+                        summary: extractToolSummary(ev.toolName, ev.parameters),
+                    });
+                    break;
+                case 'result': {
+                    const res = {
+                        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,
+                    };
+                    emitter.emit('result', res);
+                    break;
+                }
+            }
+        });
+        agTurn.on('error', (err) => {
+            emitter.emit('error', err);
+        });
+        agTurn.on('exit', (code) => {
+            emitter.emit('exit', code);
+        });
+        return {
+            turnId: agTurn.conversationId ?? undefined,
+            cancel: () => 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,
+                };
+            },
+            on: (event, listener) => {
+                emitter.on(event, listener);
+            },
+        };
+    }
+    async preflightTurn(_request) {
+        void _request;
+        if (this.auth) {
+            try {
+                await this.auth.ensureActiveTokenFresh(300);
+            }
+            catch (err) {
+                this.logger?.warn('antigravity.preflight_refresh_failed', { error: String(err) });
+            }
+        }
+    }
+    async handleTurnError(ctx) {
+        const isVerification = isVerificationError(ctx.error);
+        const isQuota = !isVerification && isQuotaOrAuthError(ctx.error);
+        if (isVerification && this.auth && ctx.retryCount < 3) {
+            try {
+                const active = await this.auth.getActiveAccount();
+                const failingName = active?.name || 'unknown';
+                const failingEmail = active?.email || failingName;
+                this.auth.pauseAccount(failingName);
+                this.auth.markCooldown(failingName, 60 * 60 * 1000);
+                if (active?.email) {
+                    this.auth.pauseAccount(active.email);
+                    this.auth.markCooldown(active.email, 60 * 60 * 1000);
+                }
+                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.`);
+                await ctx.retryTurn(ctx.retryCount + 1);
+                return true;
+            }
+            catch (err) {
+                this.logger?.warn('antigravity.verification_rotation_failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        if (isQuota && this.auth && ctx.retryCount < 3) {
+            try {
+                const active = await this.auth.getActiveAccount();
+                if (active) {
+                    this.auth.markCooldown(active.name, 30 * 60 * 1000);
+                    if (active.email)
+                        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…`);
+                await ctx.retryTurn(ctx.retryCount + 1);
+                return true;
+            }
+            catch (rotateErr) {
+                this.logger?.warn('antigravity.rotation_failed', {
+                    error: rotateErr instanceof Error ? rotateErr.message : String(rotateErr),
+                });
+            }
+        }
+        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)…`);
+            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.`);
+            return true;
+        }
+        return false;
+    }
+}