dsh-agy-link 0.3.5 → 0.4.9

package/docs/adr-012-account-pool.md

@@ -0,0 +1,54 @@
+# ADR-012: Multi-Account Pool & Sequential Drain Architecture
+
+## Status
+Proposed (2026-08-20)
+
+## Context
+Google Antigravity (via agy CLI) provides access to Gemini, Claude (Sonnet/Opus), and GPT-OSS models with generous rate limits. However, heavy agentic workflows (large code refactors, multi-step tool loops, reasoning-heavy turns) can hit per-model rate limits (`429 Too Many Requests`, `RESOURCE_EXHAUSTED`, or upstream capacity warnings).
+
+Single-account users face blocking interruptions when an account hits quota. Users with multiple Google accounts (e.g. A, B, C) want to pool their accounts so that when Account A's quota for a model family is exhausted, the system automatically falls back to Account B, then Account C, without manual switching or disrupting active conversations.
+
+### Architectural Approaches Considered
+
+1. **Reverse-Engineering HTTP/SSE Protocol (The `chaos-03x/dsh-agy` approach)**:
+   - *Pros*: Pure TypeScript HTTP requests, sub-millisecond account switching in memory.
+   - *Cons*: High ban/risk profile (needs manual fingerprint spoofing), brittle Tool Calling schema translation (frequent 400 Bad Request crashes on Protobuf / JSON-Schema mismatch, as seen in dsh-agy issues #1, #2, #4), loss of agy's 50+ native tools and subagent execution sandbox.
+
+2. **Multi-Profile agy CLI Process Isolation (Our chosen approach)**:
+   - *Pros*: 100% official Google agy binary execution (zero account ban risk, zero schema translation issues, full native tool execution); clean physical process-level credential isolation via `HOME=~/.dsh/agy-accounts/<id>/`; optional per-account proxy via `ALL_PROXY` injection.
+   - *Cons*: Light process spawn overhead (~50-100ms), requires directory management.
+
+## Decisions
+
+### 1. Multi-Profile Storage Structure
+Each managed account has an isolated home directory under the DSH state directory:
+```
+~/.dsh/agy-accounts/
+├── accounts.json                     # Metadata index (accounts, proxies, aliases, active order)
+├── acc_a1b2c3/                       # Account A isolated environment
+│   └── .gemini/
+│       └── antigravity-cli/          # agy CLI credentials, tokens, settings for Account A
+├── acc_d4e5f6/                       # Account B isolated environment
+│   └── .gemini/
+│       └── antigravity-cli/
+```
+Spawning agy for Account $X$ simply injects `HOME=/path/to/~/.dsh/agy-accounts/acc_X/` into `env`. No Docker containers or root privileges required.
+
+### 2. Sticky Sequential Drain Strategy (按模型家族顺次耗尽)
+- **Family-Scoped Cooldown**: Quota is tracked per model family (`google`, `anthropic`, `openai`). If Account A hits 429 on Claude 4.6, only Account A's `anthropic` family is marked in cooldown. Account A can still serve Gemini 3.7 Flash requests.
+- **Sticky Affinity**: Requests stick to the first healthy account (e.g., Account A) to maximize conversation continuity and token caching.
+- **Transparent Fallback**: When an in-flight request on Account A receives 429 / quota exceeded, the adapter records cooldown on Account A for that family and immediately transparently retries on Account B in the same streaming span. The user experiences zero interruption.
+
+### 3. Cooldown & Reset Handling
+- If the error contains a server reset time (or `Retry-After`), cooldown is set to `Date.now() + resetMs`.
+- Default cooldown window is 10 minutes (tiered up to 60 minutes on consecutive 429s).
+- Cooldown expires automatically; when Account A recovers, it resumes primary position.
+
+### 4. Optional Per-Account Proxy (防关联支持)
+Each account can optionally specify a dedicated proxy URL (`socks5://...` or `http://...`). When set, `ALL_PROXY` / `HTTPS_PROXY` / `HTTP_PROXY` are scoped exclusively to that account's child process. If unconfigured, it inherits the global host environment proxy.
+
+## Consequences
+
+- **Reliability**: No 400 schema crashes, full native tools support.
+- **Smooth UX**: Multiple accounts can be registered via Web QR codes or CLI, providing 3x-5x continuous quota.
+- **Safety**: Safe for single-user multiple accounts without requiring heavy containerization.

package/docs/market-pr-draft.md

@@ -1,41 +1,51 @@
-# Market PR draft (awesome-dsh-plugin)
+# Market PR draft (awesome-dsh-plugin & dsh-market)
 
-Target: awesome-dsh-plugin repository, `data/plugins/<owner>__dsh-agy-link.yml`.
-Replace `<owner>` with the GitHub owner chosen at publish time. File the PR
-after: npm published, GitHub repo created, >= 10 commits, >= 1 day old,
-topic `dsh-plugin` set.
+Target: [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) repository.
+File path: `data/plugins/amlyczz__dsh-agy-link.yml`
+
+> **Note**: Submitting to `awesome-dsh-plugin` automatically indexes the plugin into `dsh-market` (the in-app GUI plugin market inside DeepSeek Harness), `awesome-dsh-plugin.com`, DSH Desktop, and DSH Get!
 
 ---
 
+### `data/plugins/amlyczz__dsh-agy-link.yml`
+
 ```yaml
-name: dsh-agy-link
-description: Google Antigravity (agy CLI) models for DSH — streaming chat, thinking, tool activity, usage, in-GUI Google OAuth login.
-npm: dsh-agy-link
-repository: https://github.com/<owner>/dsh-agy-link
+url: https://github.com/amlyczz/dsh-agy-link
+name: amlyczz/dsh-agy-link
 category: model
-tags:
-  - antigravity
-  - gemini
-  - agy
-  - model-provider
+description:
+  en: 'Google Antigravity (agy CLI) models for DSH — streaming chat with Gemini/Claude/GPT-OSS subscriptions, native tool cards, thinking turns, and in-GUI Google OAuth login.'
+  zh: '将 Google Antigravity (agy CLI) 接入 DSH：无 API Key 使用 Gemini/Claude/GPT-OSS 订阅模型，支持流式对话、原生工具卡片、思考轮次注记及 Web 界面 Google OAuth 扫码登录。'
 ```
 
-PR body draft:
+---
+
+### PR Title & Body Draft
+
+**Title**: `Add amlyczz/dsh-agy-link (model)`
+
+**Body**:
 
 ```markdown
-## Add dsh-agy-link (model)
+## Add amlyczz/dsh-agy-link (model)
 
+- **Repo**: https://github.com/amlyczz/dsh-agy-link
 - **npm**: https://www.npmjs.com/package/dsh-agy-link
-- **repo**: https://github.com/<owner>/dsh-agy-link
-- **category**: model
-
-Brings Google Antigravity models (Gemini / Claude / GPT-OSS slugs exposed by
-the agy CLI) into DSH as a first-class provider route: full streaming with
-thinking and tool-activity annotation, token usage, session-conversation
-binding, model discovery with effort folding, in-GUI Google OAuth login with
-QR, an agy_ask delegation tool, and a /agy command family with a redacted
-doctor export. Dormant-safe when agy is missing or signed out.
-
-Checklist: dsh bundle manifest present; >= 10 commits; repo age >= 1 day;
-`dsh-plugin` topic set on the repository.
+- **Category**: `model`
+
+Brings Google Antigravity models (Gemini / Claude / GPT-OSS slugs exposed by the agy CLI) into DSH as a first-class provider route:
+- Full streaming responses with thinking turns and token usage.
+- Native DSH tool cards (terminal, diff, view, search) mirrored via `agy_tool`.
+- Multi-turn continuity with session-conversation binding and continuation spans.
+- In-GUI Google OAuth login with QR code & auth helper.
+- Sliding activity watchdog supporting indefinite execution for active long tasks.
+- `/agy` command suite (`status`, `auth`, `doctor`, `ask`).
+
+### Pre-submission Checklist
+- [x] `dsh.bundle` manifest present in `package.json`
+- [x] >= 10 commits (currently 40+)
+- [x] Repository age >= 1 day
+- [x] `dsh-plugin` topic set on GitHub repository
+- [x] Published and verified on npm (`dsh-agy-link`)
 ```
+

package/docs/spec-account-pool.md

@@ -0,0 +1,229 @@
+# Comprehensive Specification: Multi-Account Pool, Quota Statistics & Sequential Drain
+
+> **Document Type**: Technical Specification & Architecture Design  
+> **Status**: Approved for Implementation  
+> **Scope**: Host Backend, Account Engine, Quota Statistics, Transparent Retry Pipeline, DSH Attached WebUI, CLI Family
+
+---
+
+## 1. Executive Summary & Core Tenets
+
+### 1.1 Background & Motivation
+In agentic coding workflows using Google Antigravity models (Gemini 3.7 Flash, Claude 4.6 Sonnet/Opus, GPT-OSS 120B), heavy usage can hit rate limits (`429 Too Many Requests`, `RESOURCE_EXHAUSTED`, or upstream capacity warnings).
+
+This specification details a **Multi-Account Pool (号池系统)** that enables pooling multiple Google accounts (e.g. Accounts A, B, C) with **Live Quota Statistics (实时配额进度条)**, **Sticky Sequential Drain (按模型家族顺次耗尽)**, **Zero-Interruption In-Flight Fallback (零感知自动重试)**, and full integration into the **DSH Built-in Settings WebUI**.
+
+### 1.2 Core Architectural Principles
+1. **Zero Ban Risk via Official CLI Execution**: Execution runs through the official Google `agy` binary (`agy -p ...`). No reverse-engineered chat streaming, no fragile Protobuf schema translation, no spoofed fingerprinting. Full access to agy's 50+ native Agent tools.
+2. **Multi-Profile Directory Isolation (Verified)**: Local process isolation via dedicated `HOME` directories (`~/.dsh/agy-accounts/<id>/`). Zero Docker containers or background daemons. Verified to boot isolated agy processes in ~50ms.
+3. **Live Quota Inspection (实时额度统计)**: Direct upstream query of `v1internal:fetchAvailableModels` to extract `remainingFraction` (0.0~1.0) and `resetTime` per model family (`google`, `anthropic`, `openai`), visually rendered as colorful progress bars in the DSH settings panel.
+4. **Zero-Config Proxy Inheritance (零配置开箱即用)**: All accounts default to inheriting the active system/terminal proxy (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) from DSH. Single-proxy-port users (e.g. Clash on 7890) can use 3+ accounts seamlessly without configuring proxy settings.
+5. **Family-Scoped Precise Cooldown (按模型家族精准冷却)**: Cooldowns are tracked per model family (`google`, `anthropic`, `openai`). A 429 on Claude only cools down Claude; Gemini requests remain active on that same account. Cooldown duration leverages the server's exact `resetTime`.
+6. **Sticky Sequential Drain**: Always prioritize Account A until a specific model family is exhausted, then fail over to Account B, then C. Minimizes context thrashing and maximizes session token cache hits.
+7. **Native DSH WebUI Attachment**: Fully integrated into the native DSH Web interface via `settings.section` slot — zero external ports or separate web servers needed.
+
+---
+
+## 2. Multi-Profile Isolation & OAuth Flow (Verified)
+
+### 2.1 Directory Structure
+```
+~/.dsh/agy-accounts/
+├── pool.json                         # Account registry, active mode, and cached quota metadata
+├── acc_1700000000_a1/                # Account A (e.g. work@gmail.com)
+│   └── .gemini/
+│       └── antigravity-cli/
+│           └── antigravity-oauth-token
+├── acc_1700000000_b2/                # Account B (e.g. personal@gmail.com)
+│   └── .gemini/
+│       └── antigravity-cli/
+│           └── antigravity-oauth-token
+└── acc_1700000000_c3/                # Account C (e.g. backup@gmail.com)
+    └── .gemini/
+        └── antigravity-cli/
+            └── antigravity-oauth-token
+```
+
+### 2.2 Verified Add-Account OAuth Workflow
+```
+[ User clicks: "➕ 添加新 Google 账号" ]
+                 │
+                 ▼
+1. Backend allocates directory: ~/.dsh/agy-accounts/acc_<id>/
+                 │
+                 ▼
+2. Generates Google OAuth PKCE authorization URL:
+   - Client ID: AGY_PUBLIC_CLIENT_ID (Antigravity Consumer Public OAuth Client)
+   - Scopes: cloud-platform, userinfo.email, userinfo.profile, cclog, experimentsandconfigs
+                 │
+                 ▼
+3. WebUI renders:
+   - 👉 Button: Open authorization page in browser (works through local proxy)
+   - 📱 Inline Base64 QR code
+   - 📋 Authorization code input field
+                 │
+                 ▼
+[ User authorizes & pastes code back ]
+                 │
+                 ▼
+4. Backend exchanges code at https://oauth2.googleapis.com/token:
+   - Receives: { access_token, refresh_token, expires_in }
+   - Resolves email via https://www.googleapis.com/oauth2/v1/userinfo
+   - Fetches live quota stats via v1internal:fetchAvailableModels
+                 │
+                 ▼
+5. Writes token into ~/.dsh/agy-accounts/acc_<id>/.gemini/antigravity-cli/antigravity-oauth-token
+   and registers account in pool.json.
+                 │
+                 ▼
+6. Account is live and immediately ready for use!
+```
+
+---
+
+## 3. Real-Time Quota Statistics (实时配额统计)
+
+### 3.1 Quota API Endpoint & Payload
+- **Endpoint**: `https://daily-cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` (Fallback: `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels`)
+- **Headers**: `Authorization: Bearer <access_token>`, `User-Agent: antigravity/1.1.15 darwin/arm64`
+- **Response Format**:
+  ```json
+  {
+    "models": {
+      "gemini-3.7-flash": {
+        "displayName": "Gemini 3.7 Flash",
+        "quotaInfo": {
+          "remainingFraction": 0.85,
+          "resetTime": "2026-08-20T16:00:00Z"
+        }
+      },
+      "claude-3-7-sonnet": {
+        "displayName": "Claude 3.7 Sonnet",
+        "quotaInfo": {
+          "remainingFraction": 0.40,
+          "resetTime": "2026-08-20T18:30:00Z"
+        }
+      },
+      "gpt-oss-120b-medium": {
+        "displayName": "GPT-OSS 120B",
+        "quotaInfo": {
+          "remainingFraction": 1.0,
+          "resetTime": "2026-08-21T00:00:00Z"
+        }
+      }
+    }
+  }
+  ```
+
+### 3.2 Family-Scoped Quota Aggregation
+Each model maps to a family:
+- **`google`**: `gemini-*`, `gemma-*`
+- **`anthropic`**: `claude-*`
+- **`openai`**: `gpt-*`, `openai/*`
+
+For each family $F$:
+$$\text{remainingFraction}(F) = \min_{m \in F} (\text{model.quotaInfo.remainingFraction})$$
+$$\text{resetTime}(F) = \min_{m \in F} (\text{model.quotaInfo.resetTime})$$
+
+---
+
+## 4. Scheduling & Transparent Fallback Engine
+
+### 4.1 Account Selection Algorithm (Sequential Drain)
+
+```
+[ Request: model = "claude-sonnet-4-6", family = "anthropic" ]
+                            │
+                            ▼
+              Get candidate accounts in priority order:
+              [ Account A, Account B, Account C ]
+                            │
+              Filter: enabled === true
+                            │
+              Filter: cooldowns['anthropic'].cooldownUntil <= Date.now()
+                      AND remainingFraction['anthropic'] > 0.05
+                            │
+              ┌─────────────┴─────────────┐
+              ▼                           ▼
+      Candidates Available?       All in Cooldown?
+              │                           │
+              ├── Yes: Pick first         └── No: Throw POOL_EXHAUSTED
+              │   (Account A)                 (with earliest reset countdown)
+              ▼
+    Spawn agy with Account A (HOME=~/.dsh/agy-accounts/acc_A)
+```
+
+### 4.2 In-Flight Transparent Fallback (429 Zero-Interruption Retry)
+- When Account A hits 429, `RESOURCE_EXHAUSTED`, or upstream capacity errors:
+  1. Record cooldown on Account A for `anthropic`:
+     $$\text{cooldownUntil} = \text{server.resetTime} \parallel (\text{Date.now()} + 600\,000)$$
+  2. Select next healthy account (Account B).
+  3. Re-spawn agy under Account B with the conversation digest prefix.
+  4. Stream chunks directly to the caller. The user experiences zero interruption or error modals.
+
+---
+
+## 5. DSH Attached WebUI Specification
+
+Attached via `settings.section` slot under DSH Settings $\rightarrow$ Antigravity.
+
+### 5.1 Visual Mockup with Quota Bars
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│ 👥 Antigravity Account Pool (Google 多账号池)                           │
+│ 调度模式: [ 顺次耗尽 (Sequential Drain) ▾ ]  |  [ 🔄 刷新全部额度 ]       │
+│ 提示: 默认共用本地系统/代理环境，账号 A 额度耗尽自动无缝切换到账号 B    │
+├──────────────────────────────────────────────────────────────────────────┤
+│ 1. 🟢 Account A (work@gmail.com) [当前主用]                             │
+│    📊 额度余量:                                                          │
+│    • Gemini:  [████████████████████░░] 85%  (重置时间: 16:00)            │
+│    • Claude:  [████████░░░░░░░░░░░░░░] 40%  (重置时间: 18:30)            │
+│    • GPT-OSS: [██████████████████████] 100%                             │
+│    [ 🔍 刷新额度 ] [ ⚙️ 代理设置 ] [ 🔄 重新认证 ]                      │
+├──────────────────────────────────────────────────────────────────────────┤
+│ 2. 🟡 Account B (personal@gmail.com)                                     │
+│    📊 额度余量:                                                          │
+│    • Gemini:  [██████████████████████] 100%                             │
+│    • Claude:  [░░░░░░░░░░░░░░░░░░░░░░] 0% (已耗尽 · 7分12秒后重置)      │
+│    • GPT-OSS: [██████████████████████] 100%                             │
+│    [ 🔍 刷新额度 ] [ ⚙️ 代理设置 ] [ ⬆️ 设为主用 ] [ 🗑️ 移除 ]           │
+├──────────────────────────────────────────────────────────────────────────┤
+│ 3. ⚪ Account C (backup@gmail.com)                                       │
+│    📊 额度余量:                                                          │
+│    • Gemini:  [██████████████████████] 100%                             │
+│    • Claude:  [██████████████████████] 100%                             │
+│    • GPT-OSS: [██████████████████████] 100%                             │
+│    [ 🔍 刷新额度 ] [ ⚙️ 代理设置 ] [ ⬆️ 设为主用 ] [ 🗑️ 移除 ]           │
+├──────────────────────────────────────────────────────────────────────────┤
+│  [ ➕ 添加新 Google 账号 (Add Account) ]                                │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Host Web Server Routes
+
+All host routes are namespaced under `/plugins/agy-link/`:
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `GET` | `/plugins/agy-link/pool` | Get all accounts, live quota bars, cooldown timers, mode |
+| `POST` | `/plugins/agy-link/pool/add` | Allocate a new account slot and generate OAuth URL & QR |
+| `POST` | `/plugins/agy-link/pool/auth-code` | Submit OAuth code, exchange tokens, fetch initial quota |
+| `POST` | `/plugins/agy-link/pool/auth-cancel` | Cancel in-progress OAuth for a slot |
+| `POST` | `/plugins/agy-link/pool/refresh-quota`| Refresh real-time quota for one or all accounts |
+| `POST` | `/plugins/agy-link/pool/remove` | Delete an account directory and its records |
+| `POST` | `/plugins/agy-link/pool/reorder` | Update account priority order |
+| `POST` | `/plugins/agy-link/pool/proxy` | Update optional proxy override for an account |
+| `POST` | `/plugins/agy-link/pool/test` | Test connectivity & quota health of an account slot |
+
+---
+
+## 7. CLI Family Commands
+
+- `/agy pool` / `/agy accounts`: Print summary table of pooled accounts, live quota %, and family cooldowns.
+- `/agy add-account [alias]`: Start terminal-guided OAuth login for a new account slot.
+- `/agy refresh-quota [id]`: Fetch fresh quota percentages from Google backend.
+- `/agy remove-account <id>`: Delete an account slot.
+- `/agy clear-cooldown [id]`: Manually reset cooldown timers for accounts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agy-link",
-  "version": "0.3.5",
+  "version": "0.4.9",
   "description": "Google Antigravity (agy CLI) models for DeepSeek Harness — stream Gemini/Claude/GPT-OSS subscriptions into DSH with thinking, tool activity, token usage and in-GUI Google OAuth login.",
   "type": "module",
   "license": "MIT",
@@ -58,7 +58,8 @@
     "@types/node": "^24.3.0",
     "@types/qrcode": "^1.5.5",
     "tsdown": "^0.22.14",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "undici": "^8.10.0"
   },
   "dsh": {
     "bundle": {