dsh-super-subscriptions

Readme

# dsh-super-subscriptions

[![CI](https://github.com/JoeeLiu/dsh-super-subscriptions/actions/workflows/ci.yml/badge.svg)](https://github.com/JoeeLiu/dsh-super-subscriptions/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)
[![DSH Plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-6f42c1.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![Version](https://img.shields.io/badge/version-1.0.1-0ea5e9.svg)](./CHANGELOG.md)

> A unified subscription-provider bundle for DeepSeek Harness (DSH), combining account login, model routing, quota visibility, search, and media capabilities in one Cordis plugin.

[繁體中文](./README.zh-TW.md)

## What it does

`dsh-super-subscriptions` lets a DSH Web profile use subscription-backed accounts through one integration surface. It consolidates the provider and UI responsibilities that would otherwise be installed as separate, overlapping plugins.

The bundle provides:

- OAuth and local account management for ChatGPT/Codex, Grok, and Google AntiGravity.
- Optional Claude and GitHub Copilot integrations retained from the upstream subscription plugin.
- Provider-aware model discovery, default-account selection, account pools, token refresh, and failover.
- A full-width sidebar usage panel grouped by provider, with five-hour, weekly, and other reported windows.
- A Web Settings page for login, account status, quota refresh, routing, proxy, and diagnostics.
- Unified `image_generate`, `video_generate`, `x_search`, and `view_image` tools.
- Native Codex Connect image generation registration and durable local image previews.
- Legacy `openai-codex` route migration to the unified `codex` route.

This is an independent community project for DSH. It is not affiliated with or endorsed by DeepSeek AI, OpenAI, xAI, Google, Anthropic, or GitHub.

## Provider matrix

| Provider | Default | Route | Authentication | Included capabilities |
| --- | ---: | --- | --- | --- |
| ChatGPT / Codex | On | `codex` | OAuth PKCE | Responses streaming, account pool, quota refresh, GPT image generation |
| Grok | On | `grok` | OAuth PKCE | Responses streaming, account pool, X search, Grok image and video generation |
| Google AntiGravity | On | `antigravity` / `agy` | Google OAuth or existing `agy` credentials | Model discovery, thinking stream, account pool, quota and CLI bridge |
| Claude | Off | `claude` | Claude Code credentials or OAuth | Opt-in provider retained from the subscription integration |
| GitHub Copilot | Off | `copilot` | GitHub device flow | Opt-in provider retained from the subscription integration |

Provider availability, model names, quota windows, and media endpoints are controlled by the corresponding service. A successful login does not guarantee that every model or capability is available on every subscription tier.

## Requirements and compatibility

- DeepSeek Harness `0.1.1-rc.2` or a compatible current `0.1.x` Web profile.
- Node.js 20 or newer.
- pnpm 9 or newer for development and local installation.
- A supported subscription account for each provider you enable.
- For AntiGravity, either the `agy` executable or the built-in Google OAuth flow. The built-in flow requires your own `AGY_CLIENT_ID` and `AGY_CLIENT_SECRET` environment variables.

Version `1.0.1` was typechecked, tested, and built against DSH `0.1.1-rc.2`, Node.js 24, and pnpm 11 on Windows.

## Installation

### Install the public GitHub repository

The repository is currently distributed through GitHub rather than npm:

```bash
dsh plugin --profile web add github:JoeeLiu/dsh-super-subscriptions
```

Restart the Web profile after installation:

```bash
dsh web
```

When an npm release is published, the package form will be documented here as well. Until then, do not use `dsh plugin --profile web add dsh-super-subscriptions` as an npm install command.

For the fixed `v1.0.1` prebuilt package, use the GitHub Release tarball:

```bash
dsh plugin --profile web add https://github.com/JoeeLiu/dsh-super-subscriptions/releases/download/v1.0.1/dsh-super-subscriptions-1.0.1.tgz
```

### Local development installation

```bash
git clone https://github.com/JoeeLiu/dsh-super-subscriptions.git
cd dsh-super-subscriptions
pnpm install
pnpm run check
```

To mount a working tree into a local Web profile, use a `file:` dependency in that profile's `package.json`. Keep only this bundle enabled when it replaces the overlapping upstream provider bundles.

### Uninstall and rollback

Remove the package from the target profile and restart DSH:

```bash
dsh plugin --profile web remove dsh-super-subscriptions
dsh web
```

If you are replacing an older overlapping setup, restore the profile's package and Cordis patch backups before restarting. Do not delete local credential stores unless you explicitly want to remove the accounts as well.

## First-run setup

1. Start DSH Web and open `http://127.0.0.1:3080` in a normal browser tab.
2. Open **Settings → Plugins → Super Subscriptions**.
3. Enable the providers you want to use.
4. Select **Sign in** for ChatGPT/Codex, Grok, or AntiGravity and complete the provider's OAuth flow in the browser. For AntiGravity, configure the OAuth environment variables first, or use the existing `agy` CLI login.
5. Return to DSH and refresh the provider status and model list.

Use a normal browser profile for the launcher when the provider login depends on existing browser cookies. An isolated embedded browser or a temporary profile will not automatically share those cookies.

After logging in, select a model from the provider route. The route is selected by the model id; no API key is required for the subscription flows. API-key-based integrations are outside the scope of this plugin.

## Configuration

The bundled patch in [`cordis.patch.yml`](./cordis.patch.yml) enables the supported defaults:

```yaml
- insert:
    - id: llm-super-subscriptions
      name: dsh-super-subscriptions
      config:
        providers:
          chatgpt:
            enabled: true
          grok:
            enabled: true
          antigravity:
            enabled: true
            permissionMode: skip
          claude:
            enabled: false
          copilot:
            enabled: false
        codexRoute: codex
        migrateOpenAiCodex: true
        enableSearch: true
        enableImageTool: true
        enableImageGeneration: true
```

The configuration schema is:

```ts
interface SuperSubscriptionsConfig {
  providers?: {
    chatgpt?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    grok?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    antigravity?: {
      enabled?: boolean
      agyBin?: string
      permissionMode?: 'skip' | 'plan' | 'accept-edits'
      workspaceRoot?: string
      defaultModel?: string
      defaultEffort?: string
    }
    claude?: { enabled?: boolean; streamIdleTimeoutMs?: number }
    copilot?: { enabled?: boolean; streamIdleTimeoutMs?: number }
  }
  codexRoute?: string
  migrateOpenAiCodex?: boolean
  enableSearch?: boolean
  enableImageTool?: boolean
  enableImageGeneration?: boolean
}
```

AntiGravity's built-in Google OAuth flow reads `AGY_CLIENT_ID` and `AGY_CLIENT_SECRET` from the DSH process environment. These are intentionally not bundled in the public repository. If you do not want to register an OAuth client, sign in with `agy` and let the plugin use the local `agy` credentials instead.

Do not enable `dsh-plugin-subscriptions`, `dsh-agy-link`, or `dsh-codex-connect` alongside this bundle unless you deliberately configure non-overlapping routes. Those plugins register related providers, tools, or UI slots and can cause duplicate registration or conflicting account stores.

## Tools and media

| Tool | Provider | Purpose |
| --- | --- | --- |
| `image_generate` | ChatGPT/Codex or Grok | Unified image generation; pass `provider: "gpt"` or `provider: "grok"` when needed |
| `codex_connect_image_generate` | ChatGPT/Codex | Native Codex Connect GPT Image 2 route with DSH attachment preview |
| `view_image` | Local attachment store | Resolve and display generated or attached images |
| `video_generate` | Grok | Generate and save short Grok Imagine video output |
| `x_search` | Grok | Search X posts and related public content through the hosted xAI tool |

The subscription image paths use `gpt-image-2` and `grok-imagine-image-2.0` where the provider account and endpoint support them. Generated image bytes are stored in the local DSH attachment area; they are not committed to this repository.

## Account storage, permissions, and privacy

- Provider tokens are stored locally under the DSH home directory, normally `~/.dsh/plugins/super-subscriptions/`.
- Imported legacy subscription credentials are read non-destructively; the old store is not deleted.
- AntiGravity may also use its own local credential format under the user's home directory so the `agy` binary can access the account.
- The optional AntiGravity OAuth client credentials are supplied by environment variables and are never stored in this repository.
- The plugin makes outbound HTTPS requests to the provider OAuth, model, quota, search, and media endpoints required by enabled capabilities.
- The Web settings and loopback callback servers bind to local DSH endpoints. They are protected by callback state/PKCE checks and trusted-origin validation where applicable.
- Proxy settings are optional and stored in the local DSH profile.
- No token, API key, browser cookie, private account data, or generated media belongs in Git. The repository `.gitignore` excludes local credentials, environment files, build output, and the upstream reference tree.

Review the source and provider terms before installing. This plugin executes with the permissions of the DSH process and can access the enabled subscription accounts.

## Troubleshooting

### Login completes but DSH still shows logged out

Keep the DSH page open at the same loopback origin, complete the callback in a normal browser tab, and wait for the Settings page to poll the callback result. If the callback tab says login succeeded but the UI is stale, refresh the provider status rather than restarting the OAuth flow immediately.

### Grok or ChatGPT returns a streaming/parser error

Make sure only this unified provider bundle owns the `grok` and `codex` routes. Version `1.0.1` emits the DSH `text-delta`, `reasoning-delta`, `tool-call-delta`, `reasoning`, and `tool-call` chunk variants and refreshes expired access tokens before retrying.

### Grok returns a request validation error

The Grok adapter omits tool-only request fields when no tools are present. Update to `1.0.1` and verify that an older duplicate Grok adapter is not still active in the profile.

### AntiGravity says `payload.provider must be one of ...`

That message usually means an uncompiled or duplicate AntiGravity tool definition reached the host. Keep only this bundle active, restart DSH, and refresh the provider status and model list.

### Images are generated but the UI shows only an attachment id

The Web client must load the attachment through the DSH attachment RPC. Update both the host and client bundle to the same `1.0.1` build, then refresh the Web page.

### Quota is unavailable

Quota APIs are provider- and account-tier-dependent. Refresh the provider from Settings, check that the account token is current, and inspect the provider status before treating an empty window as zero usage.

## Development

```bash
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
```

`pnpm run check` runs typechecking, the complete Vitest suite, and the production bundle build. Provider changes should include focused tests for authentication, request shape, stream translation, quota behavior, and error recovery.

The `.upstream/` directory is a local reference cache used while developing the integration. It is intentionally ignored and is not part of the published repository or package.

## Architecture and project layout

```text
src/
├── index.ts                    Cordis host entry and registrations
├── config.ts                   Schemastery configuration and defaults
├── auth/                       OAuth, callbacks, device flow, and token stores
├── core/                       migration, RPC, token lifecycle, security helpers
├── providers/
│   ├── codex/                  ChatGPT/Codex adapter and auth
│   ├── grok/                   Grok adapter, auth, search, and media support
│   ├── antigravity/            Google AntiGravity and agy bridge
│   ├── claude/                 Optional Claude integration
│   └── copilot/                Optional GitHub Copilot integration
├── features/                   search, image transport, proxy, and diagnostics
├── tools/                      model-callable search, image, and video tools
└── client/                     Settings, sidebar usage, tool views, and locales
```

See [`docs/architecture-overview.md`](./docs/architecture-overview.md) and the ADRs under [`docs/architecture/`](./docs/architecture/) for design decisions.

## DSH Market metadata and submission

The package manifest includes the DSH market metadata under `dsh.market`, including bilingual display names, descriptions, category, icon, feature tags, and default provider behavior. The repository also declares the `dsh-plugin` keyword and ships a root `dsh.bundle.patch` entry, which are the signals used by community DSH catalogs.

The public listing copy and submission checklist are maintained in [`docs/DSH-MARKET.md`](./docs/DSH-MARKET.md). A public GitHub repository and the `dsh-plugin` topic are prerequisites; a catalog listing is only claimed after the market registry accepts or discovers the repository.

## Versioning and release

This project follows Semantic Versioning and Keep a Changelog. Release `1.0.1` is the first integrated release with the ChatGPT/Codex, Grok, AntiGravity, quota UI, and image capability repairs documented in [`CHANGELOG.md`](./CHANGELOG.md).

## License and attribution

Licensed under the [Apache License 2.0](./LICENSE). This project incorporates source code and architectural patterns from the upstream projects listed in [`NOTICE`](./NOTICE) and [`THIRD_PARTY_NOTICES`](./THIRD_PARTY_NOTICES). Each upstream license remains applicable to its original material.

Security reports should follow [`SECURITY.md`](./SECURITY.md), not a public issue.