@goodandready/dsh-subscriptions 0.4.15 → 0.4.17

package/README.md

@@ -1,233 +1,199 @@
-# dsh-subscriptions
-
-Use **ChatGPT Codex**, **Claude**, **Grok**, and **Antigravity**
-subscriptions as DeepSeek Harness LLM providers. Log in from
-**Settings → Plugins → Plugin settings → Subscriptions**.
-Several accounts per provider rotate on quota inside this plugin.
-
-This package is original software. It speaks vendor-public OAuth and LLM HTTP
-contracts. It does not ship tools (`x_search`, image, or video).
-
-## Install
-
-```bash
-dsh plugin --profile web add @goodandready/dsh-subscriptions
+# 📦 @goodandready/dsh-subscriptions
+
+<div align="center">
+
+<h3>Personal AI Subscription Bridge, Multi-Account Pool Rotation & Zero-Leak OAuth for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-subscriptions"><img src="https://img.shields.io/npm/v/@goodandready/dsh-subscriptions.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Overview
+
+**`dsh-subscriptions`** bridges your paid personal AI subscriptions directly into **DeepSeek Harness** as first-class LLM providers.
+
+Instead of burning expensive pay-as-you-go API credits for everyday agent tasks, `dsh-subscriptions` allows you to authenticate your existing web subscriptions via standard OAuth PKCE. It features **multi-account rotation pools** (automatically switching accounts when a rate limit or cooldown is reached), **preemptive quota switching**, and an **in-process Cordis service (`ctx.subscriptions`)** that safely powers sibling plugins like [`dsh-image-gen`](https://github.com/GooDAnDReaDY/dsh-image-gen) and [`dsh-grok-xsearch`](https://github.com/GooDAnDReaDY/dsh-grok-xsearch) with zero token leakage.
+
+```mermaid
+graph LR
+    subgraph DSHCore [DeepSeek Harness Session]
+        Agent[🤖 DSH Agent Execution] --> Router{Provider Router}
+    end
+
+    subgraph SubscriptionsCore [dsh-subscriptions Engine]
+        Router --> Pool{Multi-Account Vendor Pool}
+        Pool -->|Account #1| Acc1[👤 Primary Account: Active]
+        Pool -->|Account #2| Acc2[👤 Secondary Account: Standby]
+        Pool -->|Account #3| Acc3[👤 Fallback Account: Cooldown]
+        Acc1 -->|HTTP 429 / Quota Limit| Rotate[Smart Quota & Cooldown Rotator]
+        Rotate -->|Switches Traffic| Acc2
+    end
+
+    subgraph VendorBridges [4 Upstream Vendor Bridges]
+        Acc1 --> B1[ChatGPT / Codex Backend]
+        Acc1 --> B2[Claude Pro / Max Protocol]
+        Acc1 --> B3[xAI / Grok Subscriptions]
+        Acc1 --> B4[Google Cloud Code Assist / Antigravity]
+    end
+
+    subgraph EcosystemBridge [In-Process Cordis Service: ctx.subscriptions]
+        Pool --> ImgGen[dsh-image-gen: Zero-Cost Image Drawing]
+        Pool --> XSearch[dsh-grok-xsearch: Live Twitter Search]
+    end
+
+    style DSHCore fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style SubscriptionsCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style VendorBridges fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style EcosystemBridge fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
 ```
 
-Local checkout (development):
-
-```bash
-dsh plugin --profile web add file:/path/to/dsh-subscriptions
-```
-
-After a `file:` install, remove then add again if you added new files under
-`lib/` — pnpm reuses the previous copy otherwise.
-
-## Settings
-
-Settings live on a collapsible card in **Settings → Plugins → Plugin settings**
-(not a sidebar entry). Click **Show** to expand it.
-
-1. Pick a provider block and click **Connect**. Complete sign-in in the browser.
-2. **+ Add account** adds another account slot for the same provider; every
-   account participates in rotation.
-3. **Disconnect** removes that account's token; **Reconnect** repeats OAuth on
-   the same slot. The × button disconnects and drops the slot.
-4. If the provider redirects to a localhost or vendor URL that this host cannot
-   receive, paste the full redirected URL (or the `code` value) into the
-   account row and click **Submit code**.
-5. Logged-in providers appear in the session model picker.
-
-Leave **Use this Web UI origin as OAuth redirect_uri** off unless you registered
-your own OAuth client for this origin. Vendor CLI clients typically require
-their published redirect URI plus the paste step.
-
-## Accounts and rotation
-
-Each provider holds any number of account slots (`CODEX_OAUTH_1`,
-`CODEX_OAUTH_2`, …). On `RATE_LIMIT`, `QUOTA`, or HTTP 429 the plugin cools the
-account down (`cooldownMs`, default 30 minutes) and retries the same request on
-the next account of the same provider — never a different provider.
-
-Beyond error-driven rotation, accounts are proactively skipped when:
-
-- usage is at 100% for the current window (vendor-reported), or
-- remaining quota fraction is at or below `switchAtRemaining`
-  (default `0.01` = 1%), or
-- the window resets within one minute (no point spending the tail).
-
-When every account is below threshold, the request still goes out on the first
-exhausted account — a refusal beats silence.
-
-## Quota visibility
-
-Vendors that report usage expose named windows (Claude `5h`/`7d apps`,
-Codex primary/secondary, Grok credits). Each window renders as a progress bar
-with percent; colors follow theme variables (normal / warning ≥70% / exhausted
-100%). The last known snapshot persists across harness restarts and refreshes
-on the next successful request.
-
-The plugin also estimates remaining requests for the primary window
-(`≈ N (5h)`) once enough request history exists — hidden when data is thin.
-
-### Limit notifications
-
-When a window crosses 70%, 90%, or 100%, the plugin logs a warning and emits a
-`subscriptions.limit-notice` event (provider, ref, window id, usedPercent,
-threshold). Each threshold fires once per window until it resets. Toggle with
-`notifyLimits` in Config.
-
-## Background maintenance
-
-Two timers run while the plugin is loaded:
-
-- **Token refresh ahead**: expiring tokens are refreshed before they are needed
-  (`refreshAheadMs`, default 5 min). Failures back off via `refreshRetryMs`
-  (default 10 min) and mark the card as *reconnect required*.
-- **Health probe loop**: every `probeIntervalMin` minutes (default 15, 0
-  disables) each connected account gets a cheap vendor check. Dead accounts
-  surface in the card; probes never set cooldown.
-
-Both timers clean up on plugin dispose.
-
-## HTTP proxy
+---
 
-`POST|GET /dsh-subscriptions/proxy/{provider}/{path…}` forwards to the vendor
-API on behalf of a logged-in account — through the same allowlist, rotation,
-and quota accounting as model traffic. Same-origin only; no token ever appears
-in a response or log. Paths outside the per-provider allowlist get 403.
+## ✨ Key Features & Capabilities
 
-Example:
+### 1. 🌐 4 Supported Built-in Subscription Vendors
 
-```bash
-curl -X POST https://<host>:3080/dsh-subscriptions/proxy/codex/models \
-  -H 'Content-Type: application/json' -d '{}'
+| Vendor Key | Subscription Tier | Protocol & Features |
+|---|---|---|
+| `codex` | ChatGPT Plus / Pro | Codex streaming responses, tool calling & image drawing (`/backend-api/codex/...`) |
+| `claude` | Claude Pro / Max | Native Claude Messages protocol, usage tracking (`/v1/messages`, `/api/oauth/...`) |
+| `grok` | xAI / X Premium | Real-time reasoning responses, billing checks & social search |
+| `antigravity` | Google Cloud Code Assist | Antigravity engine (`/v1/loadCodeAssist`, `/v1/streamGenerateContent`) |
+
+*Custom vendors can also be dynamically registered via the `createVendorFromProfile` factory.*
+
+---
+
+### 2. 🔄 Multi-Account Rotation & Rate-Limit Mitigation (`rotate.js`, `ratelimit.js`)
+* **Multi-Account Pooling**: Attach multiple accounts per vendor (e.g. `CODEX_OAUTH_1`, `CODEX_OAUTH_2`, `CODEX_OAUTH_3`).
+* **Automatic 429 Failover**: When an account encounters a rate limit (`HTTP 429`, `RATE_LIMIT`, `QUOTA_EXCEEDED`), traffic instantly fails over to the next healthy account in the pool.
+* **Preemptive Quota Switching (`switchAtRemaining`)**: Automatically rotates to the next account before hitting zero if the rate-limit window reset is imminent.
+* **Dynamic Cooldown Calculation**: Parses upstream headers (`Retry-After`, `x-ratelimit-reset`, ISO dates, epoch timestamps) and auto-restores cooled-down accounts when their window resets.
+
+---
+
+### 3. 🔒 Zero-Leak Credential Security & Headless OAuth
+* **Zero Token Leakage**: OAuth tokens are **never** returned over HTTP API endpoints or rendered in the Web UI. The UI only receives masked account labels, connection health, and quota bars.
+* **Secure Host Storage**: Tokens reside in encrypted `$DSH_HOME/.credentials.yaml` managed by the host credentials service.
+* **Headless / Remote Login Fallback**: If running DSH on a headless server over SSH where browser popups cannot redirect to `localhost`, simply paste the redirected callback URL or authorization code directly into the account card.
+* **Proactive Background Token Refresh**: Access tokens are refreshed automatically before expiration.
+
+---
+
+### 4. 🧩 In-Process Cordis Service (`ctx.subscriptions`)
+Sibling plugins can tap into subscription capabilities directly in memory via Cordis:
+```javascript
+// Example in dsh-image-gen or custom plugins:
+const res = await ctx.subscriptions.request('codex', '/backend-api/codex/images/generations', {
+  method: 'POST',
+  body: JSON.stringify({ prompt: 'Cyberpunk landscape', size: '1024x1024' }),
+})
 ```
+* **Zero Overhead**: Eliminates intermediate HTTP loops and keeps auth tokens strictly in-memory.
+* **Strict Path Allowlist (`ALLOWLIST`)**: Restricts calls to verified vendor endpoints, preventing SSRF vulnerabilities.
 
-## Export / import
+---
 
-Tokens live in the host credentials store and normally tie the installation to
-one machine. To move them:
-
-```bash
-# export (returns an encrypted DSHE1 payload)
-curl -X POST https://<host>:3080/dsh-subscriptions/export \
-  -H 'Content-Type: application/json' -d '{"passphrase":"strong-passphrase"}'
-
-# import
-curl -X POST https://<host>:3080/dsh-subscriptions/import \
-  -H 'Content-Type: application/json' \
-  -d '{"passphrase":"strong-passphrase","payload":"DSHE1:…"}'
-```
+### 5. 🔐 Login Without a Browser: Loopback & Device Code (`v0.4.9`)
+* **Automatic Loopback Callback (`autoLoopback`, on by default)**: For vendors whose OAuth redirect URI is a loopback address (Codex `:1455`, Grok `:56121`), the plugin spins up a temporary local HTTP server and catches the callback by itself — no URL pasting needed. The paste fallback always stays available.
+* **Device Code Login (Codex)**: On fully headless machines (no browser on any reachable host), use the **Device login** button in the Codex account card. The plugin requests a short user code from `auth.openai.com`, you open `https://auth.openai.com/codex/device` on any device, enter the code, and the plugin completes the standard PKCE exchange automatically.
+* **Classic Fallbacks Intact**: Web-origin redirect (`useWebCallback`) and manual paste of the redirected URL / authorization code remain available for custom OAuth clients.
 
-Bundles are AES-256-GCM encrypted with a key derived from your passphrase
-(scrypt). Without the passphrase nothing decrypts; wrong passphrase fails with
-a clear error. Tokens are never logged.
+### 6. 🌍 Per-Account HTTP/SOCKS Proxy (`v0.4.9`)
+* **Individual Proxy per Account (`proxyUrl`)**: Every account slot accepts its own proxy URL (`http://`, `https://`, `socks5://[user:pass@]host:port`). All requests for that account — OAuth token refresh, vendor checks, model requests — are routed through it. Empty = direct connection.
+* **One-Click Proxy Check**: The account card has a **Check proxy** button: it performs a real request to the vendor base URL through the configured proxy and shows the round-trip latency or the failure reason.
+* **Request History Timings**: Every recorded request now carries its duration (`ms`) in the history store, so you can compare direct vs proxied latency over time.
 
-## Composer provider switcher
+### 7. 🕶️ Privacy Masking & Diagnostics Report (`v0.4.9`)
+* **Privacy Masking (`privacyMask`)**: One toggle in the settings card masks personal data across the whole UI: emails render as `j***n@example.com` everywhere (account lists, status labels, check results). Designed for screen sharing and streaming. Server-side masking means labels never leak through API responses either; the underlying account data is never overwritten.
+* **Anonymized Diagnostics Report**: The settings card has a **Generate diagnostics report** block: one click fetches an anonymized report (plugin/runtime versions, OS, per-vendor health counters, aggregate HTTP status counts, last ≥400 errors with timings, non-secret settings) and copies it to the clipboard. Tokens, emails, credential refs and proxy URLs are strictly excluded (verified by tests).
+* **Issue-Ready**: The same block links to the project issue tracker, so a bug report is: generate → paste → submit.
 
-A small widget in the composer bar shows the active subscription provider;
-clicking cycles among logged-in providers without opening Settings. It does not
-change the session model picker state.
+### 8. 🔌 HTTP API (added in `v0.4.9`)
+| Route | Method | Purpose |
+|---|---|---|
+| `/dsh-subscriptions/diagnostics` | GET | Anonymized diagnostics report (no secrets, no tokens, no proxy URLs) |
+| `/dsh-subscriptions/proxy-check` | POST | Latency check of a slot's proxy against its vendor base URL |
+| `/dsh-subscriptions/oauth/device/start` | POST | Begin Codex device-code login (returns user code + verification URL) |
+| `/dsh-subscriptions/oauth/device/poll` | POST | Poll device-code authorization status |
 
-## Session header chip
+---
 
-A compact chip in the conversation header shows how many subscriptions are
-connected. It polls `/dsh-subscriptions/status` every minute and turns green
-when at least one account is active.
+### 9. 🦛 Local Ollama Gateway & Seamless Fallback (`v0.4.17`)
+* **Native Provider (`ollama`)**: When a local Ollama is reachable at `ollamaBaseUrl` (default `http://127.0.0.1:11434`), it appears in the native DSH model picker with the models discovered from `/api/tags`. No API key needed.
+* **Seamless Quota Fallback (`ollamaFallback`, on by default)**: When every account of a provider is exhausted (or unreachable) and nothing has been streamed yet, the chat continues on a local model (`ollamaFallbackModel`, or the first model from `/api/tags`). The fallback is logged and recorded in request history as `kind: fallback`.
+* **Free ($0) Emergency Path**: Works with no internet and no quota — ideal for offline demos.
 
-## Quota reset countdown
+### 10. ⚡ Reasoning Effort, Verbosity & Fast Mode (`v0.4.17`)
+* **Reasoning Effort**: Codex models advertise their supported effort levels from the live catalog; the native picker validates and the chosen effort is transmitted as `reasoning.effort` in the Codex `/responses` protocol. Grok forwards effort with its own catalog-aware filtering.
+* **Verbosity (`codexVerbosity`)**: `low` / `medium` / `high` is sent as `text.verbosity` for Codex reasoning models. Empty = protocol default.
+* **Fast Mode (`codexFastMode`)**: Sends `service_tier: priority` (1.5x speed billing tier) with every Codex request. The active-subscription chip shows a `⚡` prefix while enabled.
 
-When a vendor reports a quota window reset timestamp, the account card shows a
-live `reset HH:MM:SS` countdown next to the quota bar, updating every second.
+### 11. 🚦 Family-Scoped Cooldowns & Model Filtering (`v0.4.17`)
+* **Reasoning vs Standard**: A 429 on a reasoning model (claude `*thinking*`, grok `*reasoning*`, all codex models) cools down only the reasoning family of that account — standard models on the same account keep working immediately. Legacy cooldowns (from older versions) still block the whole account until expiry.
+* **Hide Deprecated Models (`hideDeprecatedModels`)**: Filters `test`/`preview`/`dev`/`alpha`/`beta`/`legacy` model ids out of the native picker (applies to live catalogs and the static fallback).
 
-## Slash commands
+---
 
-From the chat, without opening Settings:
+## 📦 Quick Installation
 
+```bash
+dsh plugin --profile web add @goodandready/dsh-subscriptions
 ```
-/login <provider>     # start OAuth for codex|claude|grok|antigravity (opens the vendor page)
-/login status         # insert the connected providers into the composer
-/logout <provider>    # disconnect that provider
-```
-
-## /subscriptions page
-
-A localhost-only summary page at `/dsh-subscriptions/subscriptions` lists every account slot,
-connection status, usage percent, remaining quota and reset time across all
-providers. Requests from non-loopback hosts get 403.
-
-## Import a token directly
-
-In any account card, paste an existing refresh token (or API key) and click
-**Import token** to sign in without the browser OAuth round trip. The token is
-written straight to the host credentials store via
-`POST /dsh-subscriptions/import-token { provider, index, refreshToken }`.
-
-
-## Credential names
 
-Tokens are JSON blobs in the DSH credentials store. Names look like:
-
-```text
-CODEX_OAUTH_1
-CLAUDE_OAUTH_2
+> [!IMPORTANT]
+> Restart DSH Web UI after installation (`systemctl --user restart dsh-web`) and navigate to **Settings → Subscriptions** to link your accounts.
+
+---
+
+## ⚙️ Configuration Reference (`settings.yaml`)
+
+```yaml
+dsh-subscriptions:
+  switchAtRemaining: 1
+  cooldownMs: 60000
+  autoLoopback: true        # v0.4.9: catch loopback OAuth callbacks automatically
+  privacyMask: false        # v0.4.9: mask emails and account identifiers in the UI
+  ollamaBaseUrl: http://127.0.0.1:11434  # v0.4.17: local Ollama gateway
+  ollamaFallback: true      # v0.4.17: seamless fallback when all accounts are exhausted
+  ollamaFallbackModel: ''   # v0.4.17: e.g. qwen2.5-coder; empty = first model from /api/tags
+  hideDeprecatedModels: false # v0.4.17: filter test/preview/beta/legacy model ids
+  codexVerbosity: ''        # v0.4.17: low | medium | high (text.verbosity)
+  codexFastMode: false      # v0.4.17: service_tier priority (1.5x speed tier)
+  # Per-slot fields (v0.4.9): expiresAt (ms epoch), proxyUrl (http/https/socks5://)
+  accounts:
+    codex:
+      - ref: CODEX_OAUTH_1
+        label: "Work Pro Account"
+      - ref: CODEX_OAUTH_2
+        label: "Personal Plus Account"
+    claude:
+      - ref: CLAUDE_OAUTH_1
+        label: "Claude Max"
+    grok:
+      - ref: GROK_OAUTH_1
+        label: "X Premium"
 ```
 
-`<PROVIDER>` is `CODEX`, `CLAUDE`, `GROK`, or `ANTIGRAVITY`.
-Settings GET never returns access or refresh tokens — only
-`{ configured, label, usagePercent, cooldownUntil, ref }`.
-
-## Providers
-
-| Key | Subscription | Default OAuth client |
-|---|---|---|
-| `codex` | ChatGPT / Codex | Vendor-public Codex CLI client id |
-| `claude` | Claude Pro/Max | Vendor-public Claude Code client id |
-| `grok` | xAI / SuperGrok | Vendor-public Grok CLI client id |
-| `antigravity` | Google Antigravity | Your OAuth client id + secret in Config |
-
-Override `codexClientId`, `claudeClientId`, and the other empty Config fields
-if you register your own OAuth app.
-
-Live requests use the vendor subscription surfaces, not API-key hosts:
-Codex `chatgpt.com/backend-api/codex/responses`, Claude Messages with the
-OAuth beta header, Grok `cli-chat-proxy.grok.com` with CLI identity headers,
-and Antigravity Cloud Code Assist (`loadCodeAssist` then
-`streamGenerateContent`). Usage endpoints, when they answer, feed the skip
-logic above. If a live model list fails, the built-in catalog is used.
-
-Antigravity uses a confidential Google OAuth client: set `antigravityClientId`
-and `antigravityClientSecret` in plugin Config (Settings) — nothing is baked
-into the repository.
-
-Default model catalogs are built-in lists you can replace with
-`codexModels`, `claudeModels`, `grokModels`, `antigravityModels`
-in the plugin Config.
-
-### Config reference
-
-| Key | Default | Meaning |
-|---|---|---|
-| `cooldownMs` | 1800000 | Cooldown after RATE_LIMIT/QUOTA/429 |
-| `switchAtRemaining` | 0.01 | Skip account when remaining ≤ this (fraction <1 or absolute ≥1); 0 disables |
-| `refreshAheadMs` | 300000 | Refresh tokens expiring within this window |
-| `refreshRetryMs` | 600000 | Backoff after a failed background refresh |
-| `probeIntervalMin` | 15 | Account health-check interval, minutes; 0 disables |
-| `notifyLimits` | true | Emit notices when usage crosses 70/90/100% |
-| `useWebCallback` | false | Use Web UI origin as OAuth redirect_uri |
-| `<vendor>Models` | built-in | Replace default model catalog per vendor |
-
-## Identity
-
-These three names must match:
-
-| Place | Value |
-|---|---|
-| `package.json` `name` | `@goodandready/dsh-subscriptions` |
-| `cordis.patch.yml` `name:` | `@goodandready/dsh-subscriptions` |
-| `lib/client.js` loader `id` | `@goodandready/dsh-subscriptions` |
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.ru.md

@@ -0,0 +1,196 @@
+# 📦 @goodandready/dsh-subscriptions
+
+<div align="center">
+
+<h3>Мост персональных подписок на ИИ, ротация пула аккаунтов и безопасный OAuth без утечки токенов для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-subscriptions"><img src="https://img.shields.io/npm/v/@goodandready/dsh-subscriptions.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор
+
+**`dsh-subscriptions`** подключает ваши платные персональные подписки на нейросети напрямую в **DeepSeek Harness** в качестве полноценных LLM-провайдеров.
+
+Вместо поминутной оплаты дорогих API-ключей для повседневных задач агента, плагин позволяет авторизовать ваши существующие веб-подписки через безопасный протокол OAuth PKCE. Поддерживаются **пулы из нескольких аккаунтов** с автоматической ротацией при исчерпании лимитов, **упреждающее переключение квот** и **внутрипроцессный сервис Cordis (`ctx.subscriptions`)**, который питает соседние плагины (например, [`dsh-image-gen`](https://github.com/GooDAnDReaDY/dsh-image-gen) и [`dsh-grok-xsearch`](https://github.com/GooDAnDReaDY/dsh-grok-xsearch)) без утечки токенов в сеть.
+
+```mermaid
+graph LR
+    subgraph DSHCore [Сессия диалога DeepSeek Harness]
+        Agent[🤖 Выполнение задач агентом] --> Router{Маршрутизатор провайдеров}
+    end
+
+    subgraph SubscriptionsCore [Ядро dsh-subscriptions]
+        Router --> Pool{Пул аккаунтов вендора}
+        Pool -->|Аккаунт 1| Acc1[👤 Основной аккаунт: Активен]
+        Pool -->|Аккаунт 2| Acc2[👤 Второй аккаунт: Ожидание]
+        Pool -->|Аккаунт 3| Acc3[👤 Запасной аккаунт: Cooldown]
+        Acc1 -->|HTTP 429 / Превышение квоты| Rotate[Умный ротатор квот и задержек]
+        Rotate -->|Перенаправление трафика| Acc2
+    end
+
+    subgraph VendorBridges [4 Адаптера вендоров]
+        Acc1 --> B1[Бэкенд ChatGPT / Codex]
+        Acc1 --> B2[Протокол Claude Pro / Max]
+        Acc1 --> B3[Подписки xAI / Grok]
+        Acc1 --> B4[Google Cloud Code Assist / Antigravity]
+    end
+
+    subgraph EcosystemBridge [Сервис Cordis: ctx.subscriptions]
+        Pool --> ImgGen[dsh-image-gen: Бесплатная генерация картинок]
+        Pool --> XSearch[dsh-grok-xsearch: Поиск в X Twitter]
+    end
+
+    style DSHCore fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
+    style SubscriptionsCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
+    style VendorBridges fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
+    style EcosystemBridge fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
+```
+
+---
+
+## ✨ Ключевые возможности
+
+### 1. 🌐 4 Поддерживаемых встроенных вендора подписок
+
+| Ключ вендора | Тариф подписки | Протокол и возможности |
+|---|---|---|
+| `codex` | ChatGPT Plus / Pro | Стриминг Codex, вызов инструментов и генерация картинок (`/backend-api/codex/...`) |
+| `claude` | Claude Pro / Max | Нативный протокол Claude Messages, трекинг расхода (`/v1/messages`, `/api/oauth/...`) |
+| `grok` | xAI / X Premium | Ответы с рассуждениями, проверка баланса и поиск в соцсети |
+| `antigravity` | Google Cloud Code Assist | Движок Antigravity (`/v1/loadCodeAssist`, `/v1/streamGenerateContent`) |
+
+*Также поддерживается регистрация кастомных вендоров через фабрику профилей `createVendorFromProfile`.*
+
+---
+
+### 2. 🔄 Ротация аккаунтов и защита от лимитов (`rotate.js`, `ratelimit.js`)
+* **Пулы из нескольких аккаунтов**: привязка нескольких аккаунтов на вендора (`CODEX_OAUTH_1`, `CODEX_OAUTH_2`...).
+* **Автоматическое переключение при 429**: при превышении лимита запросов трафик мгновенно переключается на следующий свободный аккаунт.
+* **Упреждающее переключение квот (`switchAtRemaining`)**: смена аккаунта до падения в ошибку, если окно сброса близко.
+* **Динамический расчёт Cooldown**: парсинг заголовков `Retry-After`, `x-ratelimit-reset`, дат ISO и миллисекундных меток с автоматическим возвратом остывших аккаунтов в строй.
+
+---
+
+### 3. 🔒 Безопасность и авторизация на headless-серверах
+* **Нулевая утечка токенов**: токен OAuth **никогда** не отдаётся в браузер или через публичный HTTP API. В интерфейсе видны только статус, имя и остаток квоты.
+* **Хранилище хоста**: токены шифруются в `$DSH_HOME/.credentials.yaml`.
+* **Вход без браузера (SSH / Remote)**: если сервер запущен удалённо, авторизацию можно завершить, просто вставив итоговый redirect URL или authorization code в карточку аккаунта.
+* **Фоновое продление токенов**: плагин автоматически обновляет токены до истечения их срока действия.
+
+---
+
+### 4. 🧩 Внутрипроцессный сервис Cordis (`ctx.subscriptions`)
+Другие плагины могут использовать подключенные подписки напрямую в памяти:
+```javascript
+// Пример вызова из dsh-image-gen:
+const res = await ctx.subscriptions.request('codex', '/backend-api/codex/images/generations', {
+  method: 'POST',
+  body: JSON.stringify({ prompt: 'Cyberpunk landscape', size: '1024x1024' }),
+})
+```
+* **Нулевой оверхед**: прямое общение без лишних HTTP-запросов.
+* **Белый список путей (`ALLOWLIST`)**: строгий контроль вызываемых эндпоинтов для защиты от SSRF.
+
+---
+
+### 5. 🔐 Вход без браузера: loopback и device-код (`v0.4.9`)
+* **Автоматический loopback-callback (`autoLoopback`, включён по умолчанию)**: если redirect_uri вендора — loopback-адрес (Codex `:1455`, Grok `:56121`), плагин сам поднимает временный локальный HTTP-сервер и ловит callback без ручной вставки ссылки. Ручная вставка остаётся как запасной путь.
+* **Вход по коду устройства (Codex)**: на полностью headless-машинах нажмите **Device login** в карточке аккаунта Codex: плагин запросит короткий код на `auth.openai.com`, вы открываете `https://auth.openai.com/codex/device` с любого устройства, вводите код — плагин сам завершает стандартный PKCE-обмен.
+* **Классические варианты на месте**: redirect на origin веб-интерфейса (`useWebCallback`) и ручная вставка адреса/кода доступны как раньше.
+
+### 6. 🌍 Индивидуальный HTTP/SOCKS-прокси на аккаунт (`v0.4.9`)
+* **Прокси на слот (`proxyUrl`)**: каждый аккаунт принимает свой адрес `http://`, `https://`, `socks5://[user:pass@]host:port`. Через него идут все запросы аккаунта — обновление токенов, проверки вендора, запросы моделей. Пусто = прямое соединение.
+* **Проверка в один клик**: кнопка **Check proxy** в карточке аккаунта делает реальный запрос к базовому URL вендора через прокси и показывает задержку или причину отказа.
+* **Тайминги в истории**: каждая запись истории запросов теперь содержит длительность (`ms`) — удобно сравнивать прямое соединение и прокси.
+
+### 7. 🕶️ Режим приватности и диагностический отчёт (`v0.4.9`)
+* **Маскирование (`privacyMask`)**: один тумблер в карточке настроек скрывает персональные данные во всём интерфейсе: email отображается как `j***n@example.com` (списки аккаунтов, статусы, результаты проверок). Маскирование выполняется на сервере — личные данные не утекут и через ответы API; сами данные аккаунтов при этом не перезаписываются. Задумано для демонстраций экрана и стримов.
+* **Анонимизированный диагностический отчёт**: блок **Generate diagnostics report**: один клик — отчёт (версии плагина/рантайма, ОС, счётчики здоровья по вендорам, агрегаты HTTP-статусов, последние ошибки ≥400 с таймингами, не-секретные настройки) скачан и скопирован в буфер. Токены, email, имена учётных записей и адреса прокси исключены (покрыто тестами).
+* **Готово для issue**: рядом ссылка на трекер задач — баг-репорт это «сгенерировать → вставить → отправить».
+
+### 8. 🔌 HTTP API (добавлено в `v0.4.9`)
+| Маршрут | Метод | Назначение |
+|---|---|---|
+| `/dsh-subscriptions/diagnostics` | GET | Анонимизированный диагностический отчёт (без секретов, токенов и адресов прокси) |
+| `/dsh-subscriptions/proxy-check` | POST | Проверка задержки прокси слота через базовый URL вендора |
+| `/dsh-subscriptions/oauth/device/start` | POST | Начать вход Codex по коду устройства (возвращает код и адрес подтверждения) |
+| `/dsh-subscriptions/oauth/device/poll` | POST | Опрос статуса авторизации по коду устройства |
+
+---
+
+### 9. 🦛 Локальный шлюз Ollama и бесшовный фолбэк (`v0.4.17`)
+* **Нативный провайдер (`ollama`)**: если локальный Ollama доступен по `ollamaBaseUrl` (по умолчанию `http://127.0.0.1:11434`), он появляется в нативном селекторе моделей DSH с моделями из `/api/tags`. Ключ не нужен.
+* **Бесшовный фолбэк (`ollamaFallback`, включён по умолчанию)**: когда все аккаунты провайдера исчерпаны (или недоступны) и ещё ничего не выведено, чат продолжается на локальной модели (`ollamaFallbackModel`, либо первая из `/api/tags`). Фолбэк пишется в журнал и в историю запросов как `kind: fallback`.
+* **Бесплатный ($0) аварийный путь**: работает без интернета и без квот — удобно для офлайн-демо.
+
+### 10. ⚡ Effort, Verbosity и Fast Mode (`v0.4.17`)
+* **Уровень рассуждений (Effort)**: модели Codex объявляют поддерживаемые уровни из живого каталога; нативный селектор валидирует выбор, и выбранный уровень передаётся как `reasoning.effort` в протокол `/responses`. Grok передаёт effort со своей каталог-осознанной фильтрацией.
+* **Детализация (`codexVerbosity`)**: `low` / `medium` / `high` передаётся как `text.verbosity` для reasoning-моделей Codex. Пусто = дефолт протокола.
+* **Fast Mode (`codexFastMode`)**: c каждым Codex-запросом передаётся `service_tier: priority` (платный скоростной тир 1.5x). В чипе активной подписки при включённом режиме отображается `⚡`.
+
+### 11. 🚦 Кулдауны по семействам и фильтрация моделей (`v0.4.17`)
+* **Reasoning vs Standard**: 429 на reasoning-модели (claude `*thinking*`, grok `*reasoning*`, все codex-модели) охлаждает только семейство reasoning этого аккаунта — standard-модели того же аккаунта продолжают работать. Legacy-кулдауны (от старых версий) по-прежнему блокируют весь аккаунт до истечения.
+* **Скрыть устаревшие модели (`hideDeprecatedModels`)**: убирает из нативного селектора id с `test`/`preview`/`dev`/`alpha`/`beta`/`legacy` (действует и на живые каталоги, и на статичный фолбэк).
+
+---
+
+## 📦 Быстрая установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-subscriptions
+```
+
+---
+
+## ⚙️ Пример конфигурации (`settings.yaml`)
+
+```yaml
+dsh-subscriptions:
+  switchAtRemaining: 1
+  cooldownMs: 60000
+  autoLoopback: true        # v0.4.9: автоматически ловить loopback-callback
+  privacyMask: false        # v0.4.9: маскировать email и учётные записи в UI
+  ollamaBaseUrl: http://127.0.0.1:11434  # v0.4.17: локальный шлюз Ollama
+  ollamaFallback: true      # v0.4.17: бесшовный фолбэк при исчерпании всех аккаунтов
+  ollamaFallbackModel: ''   # v0.4.17: например qwen2.5-coder; пусто = первая модель из /api/tags
+  hideDeprecatedModels: false # v0.4.17: фильтровать test/preview/beta/legacy id моделей
+  codexVerbosity: ''        # v0.4.17: low | medium | high (text.verbosity)
+  codexFastMode: false      # v0.4.17: service_tier priority (скоростной тир 1.5x)
+  # Поля слота (v0.4.9): expiresAt (ms), proxyUrl (http/https/socks5://)
+  accounts:
+    codex:
+      - ref: CODEX_OAUTH_1
+        label: "Рабочий Pro-аккаунт"
+      - ref: CODEX_OAUTH_2
+        label: "Личный Plus-аккаунт"
+    claude:
+      - ref: CLAUDE_OAUTH_1
+        label: "Claude Max"
+    grok:
+      - ref: GROK_OAUTH_1
+        label: "X Premium"
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)