dsh-coding-subscription-oauth 0.5.0

package/README.ko.md

@@ -0,0 +1,254 @@
+
+<!-- banner -->
+<div align="center">
+
+# 🔐 dsh-coding-subscription-oauth
+
+**v0.5.0** · 이전 이름 `dsh-grok-build`
+
+**[DeepSeek Harness](https://github.com/deepseek-ai/dsh)용 코딩 구독 OAuth 플러그인.** 이미 결제한 구독으로 한 번에 로그인하고, dsh 설정 페이지나 CLI에서 그 모델을 사용하세요. **채팅에 토큰을 붙여넣을 필요가 없습니다.**
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+*[English](README.md) · [中文版](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Русский](README.ru.md)*
+
+</div>
+
+---
+
+## 이름 변경
+
+처음에는 Grok Build 전용 **`dsh-grok-build`** 였습니다. 지금은 SuperGrok / Codex / Kimi / Claude / Antigravity 코딩 구독 OAuth입니다.
+
+| | 이것을 쓰세요 | 계속 동작 |
+|---|---|---|
+| GitHub / `dsh plugin add` | [`dsh-coding-subscription-oauth`](https://github.com/lninghaha/dsh-coding-subscription-oauth) | `github:lninghaha/dsh-grok-build`（같은 `main`） |
+| npm | 아직 게시되지 않음. GitHub에서 설치 | 레거시 npm 패키지는 게시된 적 없음 |
+| CLI | `dsh-coding-oauth` | `dsh-grok-build` |
+| Cordis 플러그인 id | `llm-grok-build-oauth` | 그대로 |
+| 설정 페이지 HTTP API | `/plugins/dsh-grok-build/*` | 그대로 |
+| 자격 증명 파일 | `$DSH_HOME/.grok-build-auth.json` 및 기타 `*-oauth-auth.json` | 그대로 |
+
+## ✨ 기능
+
+- 🧾 **내 구독 그대로 사용** — 별도 API key 없이 이미 결제한 코딩 플랜을 사용합니다.
+- 🔑 **로컬 OAuth, 키 붙여넣기 불필요** — 설정 페이지나 CLI에서 인증하며, 토큰이 채팅에 들어가지 않습니다.
+- 🧩 **하나의 플러그인, 다섯 프로바이더** — Grok Build, Codex, Kimi, Claude, Google Antigravity.
+- 🛡️ **안전한 설계** — 인증 파일은 소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금.
+- ⚙️ **동적 카탈로그** — 모델 선택기에 인증을 완료한 프로바이더만 표시됩니다.
+- 🌐 **프록시 인지형** — 검증된 신뢰 가능한 구독 도메인만 프록시합니다.
+
+## 이 플러그인이 푸는 연동 문제
+
+코딩 구독을 DSH에 붙일 때 아래 검색어·오류로 이 저장소에 오는 경우가 많습니다.
+
+| 검색 / 화면 | 실제 원인 | 이 플러그인 |
+|---|---|---|
+| SuperGrok / X Premium를 DSH에, Grok Build vs `api.x.ai` | 내장 `xai`는 종량 API. 구독 추론은 `cli-chat-proxy.grok.com` | `grok-build` + CLI 지문 헤더(`X-XAI-Token-Auth` 등), 조용한 403 방지 |
+| `API key is invalid` / `AUTH` | GUI는 모든 AUTH를 그 문구로 표시. 흔히 짧은 OAuth access token 만료 | 만료 **5분 전** refresh. 401이면 저장 토큰을 무효화하고 step 재시도 |
+| Codex/Kimi 두 번째 턴 `INVALID_REPLAY_STATE` | replay가 pi-ai 네이티브 provider id를 유지 | Harness route id를 유지하고 오염된 replay를 복구 |
+| grok-4.6에 **xhigh**가 없음 | `/v1/models-v2`의 `reasoning_efforts`를 버리고 4.5 템플릿을 복제 | live efforts를 `thinkingLevelMap`에 반영. 4.6은 xhigh, 4.5는 low/medium/high |
+| Kimi Code가 Anthropic `x-api-key`로 나감 | OAuth token을 Anthropic 키로 전송 | `Authorization: Bearer`만 사용 |
+| 로그인하지 않은 모델이 선택기에 남음 | 등록된 모든 라우트를 나열 | 미인증은 빈 목록. 인증됨은 `(OAuth)` |
+| 원격/헤드리스에서 PKCE 불가 | localhost로 돌아올 수 없음 | Grok/Codex/Kimi는 디바이스 코드. Claude는 redirect URL 붙여넣기 |
+| 프록시로 Grok은 되고 중국 Kimi는 죽음 | 전역 `HTTPS_PROXY` | 허용 도메인만. Kimi는 기본 직결(`proxyKimi: true`일 때만 프록시) |
+
+## 지원 프로바이더
+
+| 프로바이더 | 라우트 | 인증 | 기존 API-key 라우트와 공존 |
+|---|---|---|---|
+| **xAI Grok Build** | `grok-build` | SuperGrok / X Premium OAuth | `xai` |
+| **OpenAI Codex** | `codex-oauth` | ChatGPT Plus/Pro OAuth | `openai` |
+| **Kimi Code** | `kimi-code-oauth` | Kimi Code OAuth | `kimi-coding` |
+| **Claude Code** | `claude-code-oauth` | Claude Pro/Max OAuth | — |
+| **Google Antigravity** | `agy` | `dsh-agy` Google OAuth | — |
+
+> Grok Build의 디바이스 로그인, 동적 `/v1/models-v2` 카탈로그, Responses 스트리밍 추론은 실제 배포에서 검증되었습니다. Codex/Kimi/Claude는 `@earendil-works/pi-ai`의 네이티브 OAuth/리프레시를 재사용하며 벤더 플로우를 재구현하지 않습니다.
+
+## 🚀 빠른 시작
+
+```bash
+# 1. web 프로필에 플러그인 설치
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# 2. 선택 사항 — Google Antigravity (검증된 고정 버전)
+dsh plugin --profile web add dsh-agy@0.1.2
+
+# 3. 상주하는 dsh web 서비스 재시작
+systemctl --user restart dsh-web.service
+```
+
+그런 다음 **Settings → Coding OAuth**를 열고 원하는 프로바이더에 로그인하세요. 완료입니다 — 선택기에서 인증된 모델을 선택하면 됩니다.
+
+## 📚 목차
+
+- [이름 변경](#이름-변경)
+- [이 플러그인이 푸는 연동 문제](#이-플러그인이-푸는-연동-문제)
+- [설치](#설치)
+- [설정 페이지](#설정-페이지)
+- [CLI](#cli)
+- [중국에서의 Kimi](#중국에서의-kimi)
+- [네트워크 프록시](#네트워크-프록시)
+- [복원력](#복원력)
+- [자격 증명](#자격-증명)
+- [아키텍처](#아키텍처)
+- [기술 메모](#기술-메모)
+- [준수](#준수)
+- [문서](#문서)
+- [기여](#기여)
+- [라이선스](#라이선스)
+
+## 설치
+
+DeepSeek Harness `0.1.0-rc.6+` 및 Node.js 22.19+가 필요합니다. 자세한 내용은 [설치 노트](INSTALL.md)를 참조하세요.
+
+```bash
+# GitHub에서
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# 또는 로컬 개발 디렉터리에서
+dsh plugin --profile web add ./dsh-coding-subscription-oauth
+```
+
+설치 후 `dsh web`을 재시작합니다. 실제 배포 검증:
+
+```bash
+pnpm run verify:deployed            # 실제 /api/llm.models + OAuth 상태 확인
+DSH_EXPECT_AGY_AUTH=signed-in pnpm run verify:deployed   # Google에 로그인된 경우
+
+DSH_RESTORE_PROVIDER=openai \
+DSH_RESTORE_MODEL=gpt-5.6-sol \
+DSH_RESTORE_REASONING=max \
+pnpm run smoke:deployed             # 실제 Codex/Kimi 도구 호출 + 두 번째 사용자 turn 재생
+```
+
+> `smoke:deployed`는 임시 세션을 만들고 Codex와 Kimi 도구 호출 및 두 번째 사용자 turn(`INVALID_REPLAY_STATE` 회귀)을 검증한 뒤 선언된 기본 모델을 복원하고 세션을 아카이브합니다.
+
+## 설정 페이지
+
+**Settings → Coding OAuth**를 열어 주세요:
+
+| 프로바이더 | 방식 |
+|---|---|
+| Grok | 인증 코드 · 디바이스 코드 · Grok CLI import · 모델 선택 |
+| Codex | 디바이스 코드(원격 DSH 권장) · 브라우저 PKCE |
+| Kimi | 디바이스 코드 |
+| Claude | 브라우저 PKCE(원격 브라우저는 전체 localhost redirect URL을 붙여넣기 가능) |
+| Antigravity | `dsh-agy` 설치 상태 + profile-local CLI 명령 |
+
+선택기는 인증을 완료한 라우트만 나열하며, 인증되지 않은 프로바이더는 빈 목록을 반환합니다. 프로바이더 이름에는 `(OAuth)`가 붙고, 로그인/아웃 후 `llm/adapters-updated`를 통해 카탈로그가 갱신됩니다.
+
+## 선택적 기능
+
+7개 스위치 `codexSearch`, `codexImages`, `codexImageEdits`, `codexUsage`, `codexFast`, `grokImagineImage`, `grokImagineVideo`는 모두 기본적으로 꺼져 있으며 재시작 없이 즉시 적용됩니다. 숫자 설정은 `searchResults`(1–20, 기본 5), `imageCount`(1–4, 기본 1), `videoArtifactTtlMs`(1시간–7일, 기본 7일, UI에서는 1–168시간)입니다. 보존 시간을 낮추면 기존 아티팩트도 즉시 단축·정리되며, 높인 값은 이후 생성된 아티팩트에만 적용됩니다.
+
+## CLI
+
+```bash
+# `dsh-grok-build` 는 같은 CLI 별칭
+dsh-coding-oauth login [--pkce] | import | status | logout
+
+# 최신 프로바이더
+dsh-coding-oauth login codex --device-auth | codex --browser | kimi | claude
+dsh-coding-oauth status all
+dsh-coding-oauth logout codex
+
+# Antigravity (먼저 web 프로필에 설치)
+dsh plugin --profile web exec dsh-agy login --headless
+```
+
+> `dsh-agy` CLI는 DSH 프로세스 밖에서 계정 풀을 수정하므로 프로세스 내 카탈로그 이벤트를 내보낼 수 없습니다 — 로그인/아웃 후 모델 선택기를 닫았다 다시 여세요.
+
+## 중국에서의 Kimi
+
+Kimi Code 구독 OAuth는 `https://auth.kimi.com`, 추론은 `https://api.kimi.com/coding`을 사용합니다. `https://api.moonshot.cn/v1`은 종량제 **Moonshot Open Platform** API-key 채널이며, 전환 가능한 "중국 OAuth 엔드포인트"는 없습니다. 이 플러그인은 별도 `kimi-code-oauth` 라우트를 사용하며 기존 `kimi-coding` API-key 설정에 영향을 주지 않습니다.
+
+## 네트워크 프록시
+
+우선순위: `config.proxy` → `CODING_OAUTH_PROXY` → `GROK_BUILD_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`.
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    proxy: http://127.0.0.1:7890
+    proxyKimi: false
+```
+
+검증된 구독 도메인만 프록시됩니다(xAI/Grok, OpenAI Codex, Claude/Anthropic, Google Antigravity). 나머지 DSH 트래픽은 원래 디스패처를 유지합니다. Kimi는 기본적으로 직결이며 `proxyKimi: true`일 때만 프록시를 사용합니다.
+
+## 복원력
+
+OAuth 액세스 토큰은 저장된 만료 시각 **5분 전**에 선제적으로 갱신됩니다(pi-ai 0.84+). 업스트림이 로컬에서는 아직 유효한 토큰을 401/403으로 거절하면, 플러그인이 저장된 `expires`를 과거로 되돌리고 재시도 단계에서 먼저 갱신한 뒤 다시 요청합니다.
+
+요청 재시도는 harness retry 정책을 따릅니다. 일시 오류(`RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/`EMPTY_RESPONSE`)와 **`AUTH`**는 지수 백오프로 재시도합니다(기본 2회, 500 ms → 10 s, 10% jitter). 쿼터 소진과 죽은 refresh token은 재시도하지 않습니다. 배포별 재정의:
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    retryPolicy:
+      mode: normal
+      maxRetries: 2
+      retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, AUTH]
+      backoff: { initialDelayMs: 500, maxDelayMs: 10000, jitterRatio: 0.1 }
+```
+
+## 자격 증명
+
+소유자 전용 `0600`, 원자적 쓰기, 크로스 프로세스 파일 잠금:
+
+- `$DSH_HOME/.grok-build-auth.json`
+- `$DSH_HOME/.codex-oauth-auth.json`
+- `$DSH_HOME/.kimi-code-oauth-auth.json`
+- `$DSH_HOME/.claude-code-oauth-auth.json`
+
+선택 캐시는 해당 `*-models.json` 파일에 저장됩니다. **HTTP 상태, 로그, UI가 토큰을 반환해서는 안 됩니다.**
+
+## 아키텍처
+
+```mermaid
+flowchart LR
+    subgraph DSH["DSH Harness"]
+        UI[설정 / Web · Coding OAuth] --> LLM[llm route]
+        LLM --> ALIA[라우트 별칭 어댑터]
+    end
+    ALIA --> PI[pi-ai 네이티브 프로바이더<br/>OAuth · 리프레시 · 스트림]
+    PI --> GROK[Grok Build]
+    PI --> COD[Codex]
+    PI --> KIMI[Kimi]
+    PI --> CLAU[Claude]
+    AGY[dsh-agy 플러그인] --> GAL[Google Antigravity]
+```
+
+## 기술 메모
+
+- **Grok Build**: `cli-chat-proxy.grok.com/v1`의 커스텀 Responses 프로바이더, CLI 핑거프린트 헤더, 동적 모델 카탈로그.
+- **Codex/Kimi/Claude**: pi-ai 네이티브 프로바이더가 OAuth와 리프레시를 처리합니다. 라우트 별칭 어댑터가 이를 네이티브 id에 매핑하되 모델 내부 아이덴티티는 변하지 않습니다.
+- Kimi access token은 명시적으로 `Authorization: Bearer`로 변환됩니다 — Anthropic `x-api-key`로 잘못 보내지는 일이 없습니다.
+- Google Antigravity는 여기서 리버스 엔지니어링**하지 않습니다**. 버전 고정형 전용 DSH 플러그인을 사용합니다.
+
+## 준수
+
+제3자 harness를 통한 코딩 구독 사용은 각 벤더 이용약관의 회색 지대에 놓일 수 있으며 할당량, 지역 또는 계정 리스크 관리가 트리거될 수 있습니다. **본인 계정만 사용하세요.** 이 프로젝트는 대량 계정, 할당량 재판매, 원격 릴레이, 페이월 우회, 클라이언트 사칭을 지원하지 않습니다. 상업용으로는 벤더 공식 API-key 채널을 권장합니다.
+
+## 문서
+
+| 문서 | 용도 |
+|---|---|
+| [`INSTALL.md`](INSTALL.md) | 설치·사용 상세 |
+| [`CHANGELOG.md`](CHANGELOG.md) | 릴리스 이력 |
+| [`docs/00-project-rules.md`](docs/00-project-rules.md) | 버전 관리, 릴리스 루프, 공개/로컬 분리 |
+| [`docs/02-architecture.md`](docs/02-architecture.md) | 내부 아키텍처 (라우트 · 데이터 흐름 · 모듈 · API) · [中文](docs/02-architecture.zh-CN.md) |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 기여 가이드 |
+
+## 관련 프로젝트
+
+- [`dsh-agy`](https://www.npmjs.com/package/dsh-agy) — Google Antigravity용 독립 고정 버전 플러그인.
+
+## 기여
+
+기능, 문서, 번역, 버그 보고 등 모든 기여를 환영합니다. 프로세스, 커밋 규칙 및 릴리스 루프는 **[CONTRIBUTING](CONTRIBUTING.md)**을 참조하세요. 목록에 없는 언어라면 README 번역을 PR로 보내 주세요. 위 언어 테이블에 추가하겠습니다.
+
+## 라이선스
+
+[Apache-2.0](LICENSE) · [NOTICE](NOTICE) 참조. 일부는 [dsh-xai](https://github.com/MirDie/dsh-xai) 프로젝트(Apache-2.0)에서 파생되었습니다.

package/README.md

@@ -0,0 +1,286 @@
+
+<!-- banner -->
+<div align="center">
+
+# 🔐 dsh-coding-subscription-oauth
+
+**v0.5.0** · formerly `dsh-grok-build`
+
+**Coding-subscription OAuth for [DeepSeek Harness](https://github.com/deepseek-ai/dsh).** Use SuperGrok / X Premium (Grok Build), ChatGPT Plus/Pro (Codex), Kimi Code, Claude Pro/Max and Google Antigravity inside DSH — without a second API-key bill and **without pasting any token into chat.**
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+*[English](README.md) · [中文版](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Português (BR)](README.pt-BR.md) · [Español](README.es.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Русский](README.ru.md)*
+
+</div>
+
+---
+
+## Name change
+
+Published first as **`dsh-grok-build`** when it only covered Grok Build. The current name matches the full coding-subscription OAuth surface.
+
+| | Use this | Still works |
+|---|---|---|
+| GitHub / `dsh plugin add` | [`dsh-coding-subscription-oauth`](https://github.com/lninghaha/dsh-coding-subscription-oauth) | `github:lninghaha/dsh-grok-build` (same `main`) |
+| npm | Current release is `0.5.0`: `dsh plugin --profile web add dsh-coding-subscription-oauth@0.5.0` then `dsh plugin --profile web update dsh-coding-subscription-oauth`. GitHub install still works. | No legacy npm package was published |
+| CLI | `dsh-coding-oauth` | `dsh-grok-build` |
+| Cordis plugin id | `llm-grok-build-oauth` | unchanged |
+| Settings HTTP API | `/plugins/dsh-grok-build/*` | unchanged |
+| Credential files | `$DSH_HOME/.grok-build-auth.json` and the other `*-oauth-auth.json` files | unchanged |
+
+## ✨ Features
+
+- 🧾 **Bring your own subscription** — SuperGrok, ChatGPT Plus/Pro, Kimi Code, Claude Pro/Max; no extra pay-as-you-go key.
+- 🔑 **Local OAuth, no key-pasting** — authorize in Settings or CLI; access/refresh tokens never enter chat, logs or HTTP status.
+- 🧩 **One plugin, five providers** — Grok Build (`cli-chat-proxy.grok.com`), Codex, Kimi Code, Claude Code and Google Antigravity.
+- 🛡️ **Secure by design** — credential files are owner-only `0600`, atomically written, cross-process locked.
+- ⚙️ **Dynamic catalog** — the selector lists only signed-in routes, labelled `(OAuth)`, including grok-4.6 `xhigh`.
+- 🌐 **Proxy-aware** — proxies only reviewed subscription domains; Kimi China stays direct by default.
+- 📥 **Manual CLI Pull** — Settings discovers allowlisted official Grok/Codex/Kimi/Claude CLI OAuth files read-only; you pull a one-way copy after preview and overwrite confirmation.
+- 🎛️ **Optional capabilities, default off** — Codex search, usage/quota, image generate/edit, Fast, and Grok Imagine apply live when you turn them on.
+- 🔌 **Opt-in local API gateway** — default-off loopback OpenAI/Anthropic-compatible server for your own tools; never a public relay.
+
+## Problems this plugin solves
+
+These are the searches and DSH errors that usually lead here. If one of them is your tab title, you are in the right repo.
+
+| You searched / saw | What was actually broken | What this plugin does |
+|---|---|---|
+| SuperGrok / X Premium in DSH, “Grok Build vs `api.x.ai`” | The built-in `xai` route is the **pay-as-you-go API**. Coding-plan inference is `cli-chat-proxy.grok.com` | Dedicated `grok-build` route + official CLI fingerprint headers (`X-XAI-Token-Auth`, `x-grok-client-identifier`, `x-grok-client-version`) so you do not get a silent 403 |
+| `本轮运行失败` **API key is invalid** / `AUTH` mid-turn | The GUI maps **every** `AUTH` code to that banner. Often the OAuth access token just expired (Kimi ~15 min) | Refresh **5 minutes** before expiry; on a 401, invalidate the stored token and **retry the step** after refresh |
+| `INVALID_REPLAY_STATE` on the second Codex / Kimi turn | Replay state still carried the native pi-ai provider id after the Harness route alias | Keep the Harness route id in replay state and heal older poisoned messages |
+| grok-4.6 **xhigh** / Extra High Effort missing | Live `GET /v1/models-v2` already returns `reasoning_efforts` including `xhigh`; cloning the grok-4.5 template hides it (pi-ai treats absent `xhigh` as unsupported) | Parse live `reasoning_efforts` into `thinkingLevelMap`. grok-4.6 gets `xhigh`; grok-4.5 stays low/medium/high |
+| Kimi Code 401, or requests going out as Anthropic `x-api-key` | The OAuth token was attached as an Anthropic key | Wire **only** `Authorization: Bearer` on `api.kimi.com/coding` |
+| Unsigned-in Grok / Codex / Claude still in the model picker | Every registered route was listed | Unauthenticated routes expose **no models**; signed-in names show `(OAuth)` |
+| Device login on a **remote / headless** DSH | Browser PKCE cannot reach `localhost` | Device-code for Grok, Codex and Kimi; Claude accepts a pasted localhost redirect URL |
+| Proxy works for Grok/Codex but breaks Kimi in China | One global `HTTPS_PROXY` | Allowlisted proxy; Kimi stays **direct** unless `proxyKimi: true`. `auth.kimi.com` ≠ `api.moonshot.cn` |
+| ChatGPT Plus / Claude Pro in DSH without another API bill | Separate OpenAI / Anthropic API keys | Local OAuth on `codex-oauth` / `claude-code-oauth`, coexist with existing `openai` / `kimi-coding` API-key routes |
+
+Grok Build device login, live `/v1/models-v2` and Responses streaming are verified on real deployments. Codex / Kimi / Claude reuse `@earendil-works/pi-ai` native OAuth instead of re-implementing vendor flows.
+
+## Supported providers
+
+| Provider | Route | Auth | Coexists with |
+|---|---|---|---|
+| **xAI Grok Build** | `grok-build` | SuperGrok / X Premium OAuth | `xai` |
+| **OpenAI Codex** | `codex-oauth` · optional `codex-oauth-fast` | ChatGPT Plus/Pro OAuth | `openai` |
+| **Kimi Code** | `kimi-code-oauth` | Kimi Code OAuth | `kimi-coding` |
+| **Claude Code** | `claude-code-oauth` | Claude Pro/Max OAuth | — |
+| **Google Antigravity** | `agy` | `dsh-agy` Google OAuth | — |
+
+> Grok Build's device login, dynamic `/v1/models-v2` catalog and Responses streaming are verified on real deployments. Codex/Kimi/Claude reuse the provider-native OAuth/refresh from `@earendil-works/pi-ai` instead of re-implementing vendor flows.
+
+## 🚀 Quick start
+
+```bash
+# 1. install the plugin into the web profile
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# 2. optional — Google Antigravity (pinned, reviewed version)
+dsh plugin --profile web add dsh-agy@0.1.2
+
+# 3. restart the resident dsh web service
+systemctl --user restart dsh-web.service
+```
+
+Then open **Settings → Coding OAuth** and sign in to any provider. Done — pick your authenticated model from the selector.
+
+## 📚 Table of contents
+
+- [Name change](#name-change)
+- [Problems this plugin solves](#problems-this-plugin-solves)
+- [Install](#install)
+- [Settings page](#settings-page)
+- [Optional capabilities](#optional-capabilities)
+- [CLI](#cli)
+- [Kimi in China](#kimi-in-china)
+- [Network proxy](#network-proxy)
+- [Resilience](#resilience)
+- [Credentials](#credentials)
+- [Architecture](#architecture)
+- [Technical notes](#technical-notes)
+- [Compliance](#compliance)
+- [Documentation](#documentation)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Install
+
+Requires DeepSeek Harness `0.1.0-rc.6+` and Node.js 22.19+. Full details in the [installation notes](INSTALL.md).
+
+```bash
+# from GitHub
+dsh plugin --profile web add github:lninghaha/dsh-coding-subscription-oauth
+
+# or a local dev checkout
+dsh plugin --profile web add ./dsh-coding-subscription-oauth
+```
+
+Restart `dsh web` after installing. Verification against a live deployment:
+
+```bash
+pnpm run verify:deployed            # checks real /api/llm.models + OAuth state
+DSH_EXPECT_AGY_AUTH=signed-in pnpm run verify:deployed   # if Google is signed in
+
+DSH_RESTORE_PROVIDER=openai \
+DSH_RESTORE_MODEL=gpt-5.6-sol \
+DSH_RESTORE_REASONING=max \
+pnpm run smoke:deployed             # real Codex/Kimi tool-calls + second-turn replay
+```
+
+> `smoke:deployed` creates temporary sessions, exercises Codex and Kimi tool-calls plus a second user turn (regression coverage for `INVALID_REPLAY_STATE`), restores the declared default model, then archives the sessions.
+
+## Settings page
+
+Open **Settings → Coding OAuth**:
+
+| Provider | Methods |
+|---|---|
+| Grok | auth code · device code · model selection |
+| Codex | device code (recommended on remote DSH) · browser PKCE |
+| Kimi | device code |
+| Claude | browser PKCE (remote browser can paste the full localhost redirect URL) |
+| Antigravity | `dsh-agy` install status + profile-local CLI commands |
+
+Use device code when the DSH host is remote. Browser/PKCE sign-in opens the provider URL; if the localhost callback cannot reach this DSH host, paste either the returned authorization code or the complete redirect URL into the waiting Settings card.
+
+Settings also **discovers** allowlisted official Grok / Codex / Kimi / Claude CLI OAuth files (read-only). Synchronization is an explicit one-way **Pull** — not auto-import: discover → preview → conflict/fingerprint check → confirm overwrite. Official CLI files are never written. Reads refuse symlinks, non-regular files, non-owner files, group/other access, and oversized documents (`O_NOFOLLOW`). Preview tickets are one-use, expire in five minutes, and are capped at 32.
+
+The selector only lists routes that completed authentication; unauthenticated providers return an empty list. Provider names carry `(OAuth)`, and the catalog refreshes via `llm/adapters-updated` after sign-in/out.
+
+## Optional capabilities
+
+All seven switches start **off** and apply **live** (no restart): `codexSearch`, `codexImages`, `codexImageEdits`, `codexUsage`, `codexFast`, `grokImagineImage`, and `grokImagineVideo`. Numeric controls are `searchResults` (1–20, default 5), `imageCount` (1–4, default 1), and `videoArtifactTtlMs` (1 hour–7 days, default 7 days; the UI shows 1–168 hours). Lowering video retention shortens and cleans existing artifacts immediately; raising it affects only artifacts created afterward. Administrators may provide secret-free composition defaults under plugin config `capabilities`; live user settings in the `coding-subscription-oauth` settings section override that base, and omitting it keeps every switch off.
+
+`codex-oauth-fast` is advertised only after a **fresh live catalog** lists at least one `priority`-eligible model. Those requests send `service_tier: priority` plus a routing hint. The UI says **Fast requested** and never guarantees latency or that upstream will honor the request.
+
+Codex search, usage, and images are **opt-in** private `chatgpt.com/backend-api` endpoints. Image generation uses the fixed model `gpt-image-2`. Image edit accepts only current-session top-level attachment ids that this session already owns.
+
+Grok Imagine calls official `https://api.x.ai` with `grok-imagine-image-2.0` and `grok-imagine-video-1.5`. It uses a **separate** DSH credential reference `XAI_API_KEY` — never Grok OAuth and never a process-env fallback. Generated outputs are fetched under MIME / size / time / redirect / DNS controls from frozen hosts `imgen.x.ai`, `videogen.x.ai`, and `vidgen.x.ai`, stored privately (256 MiB hard caps for one object and aggregate unique bytes, seven days), and served only on same-origin loopback routes.
+
+## Local API gateway
+
+Default **off**. When enabled it starts an isolated `node:http` server (not the DSH web port) on `127.0.0.1:18080` and reuses the same signed-in OAuth sessions:
+
+```yaml
+gateway:
+  enabled: false
+  bind: 127.0.0.1
+  port: 18080
+```
+
+Endpoints: `GET /healthz`, `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/responses`, `POST /v1/messages`. A Bearer key is stored at `$DSH_HOME/.coding-oauth-gateway.json` (`0600`). Settings can toggle and rotate the key; bind/port stay YAML-only. Non-loopback bind requires a key. This is not a remote relay.
+
+## CLI
+
+```bash
+# `dsh-grok-build` remains a command alias
+dsh-coding-oauth login [--pkce] | import | status | logout
+
+# newer providers
+dsh-coding-oauth login codex --device-auth | codex --browser | kimi | claude
+dsh-coding-oauth status all
+dsh-coding-oauth logout codex
+
+# Antigravity (install into web profile first)
+dsh plugin --profile web exec dsh-agy login --headless
+```
+
+> `dsh-agy` CLI edits the account pool outside the DSH process, so it can't emit an in-process catalog event — close and reopen the model selector after signing in/out.
+
+## Kimi in China
+
+Kimi Code subscription OAuth uses `https://auth.kimi.com`; inference uses `https://api.kimi.com/coding`. `https://api.moonshot.cn/v1` is the pay-as-you-go **Moonshot Open Platform** API-key channel — there is no switchable "China OAuth endpoint". This plugin uses a separate `kimi-code-oauth` route and doesn't affect an existing `kimi-coding` API-key config.
+
+## Network proxy
+
+Priority: `config.proxy` → `CODING_OAUTH_PROXY` → `GROK_BUILD_PROXY` → `HTTPS_PROXY`/`HTTP_PROXY`.
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    proxy: http://127.0.0.1:7890
+    proxyKimi: false
+```
+
+Only reviewed subscription domains are proxied (xAI/Grok, OpenAI Codex, Claude/Anthropic, Google Antigravity); all other DSH traffic keeps its original dispatcher. Kimi stays direct by default and only uses the proxy when `proxyKimi: true`.
+
+## Resilience
+
+OAuth access tokens refresh proactively **five minutes** before their stored expiry (pi-ai 0.84+), so a request never rides a token into its final seconds. If an upstream still rejects a locally-valid token with 401/403 — server-side revocation or clock skew — the plugin backdates the stored credential and the retried step refreshes before reuse, recovering transparently instead of failing the turn.
+
+Request retries use the harness retry policy: transient failures (`RATE_LIMIT`/`SERVER`/`TIMEOUT`/`TRANSPORT`/`EMPTY_RESPONSE`) **and `AUTH`** retry with exponential backoff (default 2 retries, 500 ms → 10 s, 10% jitter). Quota exhaustion and a dead refresh token are **not** retried — they fail fast with the real message and a sign-in prompt. Override per deployment:
+
+```yaml
+- id: llm-grok-build-oauth
+  config:
+    retryPolicy:
+      mode: normal
+      maxRetries: 2
+      retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT, AUTH]
+      backoff: { initialDelayMs: 500, maxDelayMs: 10000, jitterRatio: 0.1 }
+```
+
+## Credentials
+
+Owner-only `0600`, atomically written, cross-process file lock:
+
+- `$DSH_HOME/.grok-build-auth.json`
+- `$DSH_HOME/.codex-oauth-auth.json`
+- `$DSH_HOME/.kimi-code-oauth-auth.json`
+- `$DSH_HOME/.claude-code-oauth-auth.json`
+
+Selection caches live in the matching `*-models.json` files. Grok Imagine uses a separate DSH credential named `XAI_API_KEY` (not the Grok OAuth file). **No HTTP status, log or UI may ever return a token.**
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph DSH["DSH Harness"]
+        UI[Settings / Web · Coding OAuth] --> LLM[llm route]
+        LLM --> ALIA[Route-alias adapter]
+    end
+    ALIA --> PI[pi-ai native provider<br/>OAuth · refresh · stream]
+    PI --> GROK[Grok Build]
+    PI --> COD[Codex]
+    PI --> KIMI[Kimi]
+    PI --> CLAU[Claude]
+    AGY[dsh-agy plugin] --> GAL[Google Antigravity]
+```
+
+## Technical notes
+
+- **Grok Build**: Responses API on `cli-chat-proxy.grok.com/v1` (not `api.x.ai`), CLI fingerprint headers, live `/v1/models-v2` including grok-4.6 `reasoning.effort: xhigh`.
+- **Codex/Kimi/Claude**: pi-ai native providers handle OAuth and refresh; the route-alias adapter maps them to native ids so multi-turn replay does not throw `INVALID_REPLAY_STATE`.
+- The Kimi access token is explicitly converted to `Authorization: Bearer` — never mistakenly an Anthropic `x-api-key`.
+- **Codex Fast / private endpoints**: `codex-oauth-fast` is opt-in and fail-closed on a stale catalog; search, usage and `gpt-image-2` images stay off until enabled.
+- **Grok Imagine**: official `api.x.ai` only, `XAI_API_KEY` through DSH credentials, same-origin download routes under `/plugins/dsh-grok-build/imagine/*`.
+- Google Antigravity is **not** reverse-engineered here; it uses a version-pinned dedicated DSH plugin.
+
+## Compliance
+
+Using coding subscriptions through a third-party harness may sit in a gray area of each vendor's terms and can trigger quota, regional or account-risk controls. **Use only your own accounts**; this project does not support bulk accounts, quota resale, remote relay, paywall bypass or client impersonation. For commercial use, prefer the vendors' official API-key channels.
+
+## Documentation
+
+| Doc | Purpose |
+|---|---|
+| [`INSTALL.md`](INSTALL.md) | Installation & usage details |
+| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
+| [`docs/00-project-rules.md`](docs/00-project-rules.md) | Versioning, release loop, publish vs local-only split |
+| [`docs/02-architecture.md`](docs/02-architecture.md) | Internal architecture (routes, data flow, modules, API) · [中文](docs/02-architecture.zh-CN.md) |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guide |
+
+## Related
+
+- [`dsh-agy`](https://www.npmjs.com/package/dsh-agy) — separate pinned plugin for Google Antigravity.
+
+## Contributing
+
+Contributions of all kinds are welcome — features, docs, translations, bug reports. See **[CONTRIBUTING](CONTRIBUTING.md)** for the flow, commit conventions and the release loop. If your language isn't listed, PR a README translation and we'll add it to the table above.
+
+## License
+
+[Apache-2.0](LICENSE) · see [NOTICE](NOTICE). Portions derived from the [dsh-xai](https://github.com/MirDie/dsh-xai) project (Apache-2.0).