@hystudio/dsh-quota-pill 0.0.0-stage → 0.1.1

package/AGENTS.md

@@ -0,0 +1,217 @@
+# Agent setup guide — dsh-quota-pill
+
+This file is for **AI agents** helping a human install and configure the plugin.
+Follow it top to bottom. It is written so that you can run the whole flow, asking
+the human only for things only they can supply (an API key, an OAuth login).
+
+> **Rule for the whole flow: never invent a quota number.** If a provider cannot
+> be read, say so and explain what is missing. A wrong number is worse than "—".
+
+---
+
+## 0. What this plugin does
+
+It shows how much quota is **left** for the LLM subscriptions the user has, in a
+small pill in the DeepSeek Harness web GUI.
+
+Architecture — two pieces, both required:
+
+```
+DSH web GUI  ──►  client.js   (the pill; renders JSON)
+                      │
+                      ▼
+                  sidecar      (Node process; reads credentials + upstream APIs)
+```
+
+The pill shows nothing until the sidecar runs. That is by design: credentials
+must never reach the browser.
+
+There are **two credential families**, and this matters for every step:
+
+| Family | Providers | What the user needs |
+|---|---|---|
+| API key | `kimi`, `opencode`, `commandcode` | a key pasted into `~/.dsh/.credentials.yaml` |
+| OAuth via CLIProxyAPI | `xai`, `codex`, `agy` | **CLIProxyAPI installed and logged in once** |
+
+---
+
+## 1. Verify the sidecar runs
+
+```bash
+npx @hystudio/dsh-quota-pill
+```
+
+Expected first lines:
+
+```
+[quota-pill] listening on http://127.0.0.1:8319
+[quota-pill] credentials: /Users/<user>/.dsh/.credentials.yaml
+[quota-pill] CLIProxyAPI: /Users/<user>/.cli-proxy-api        ← or "not set up"
+```
+
+Then, in another shell:
+
+```bash
+curl -s http://127.0.0.1:8319/health
+# {"ok":true,"port":8319,"providers":["kimi","opencode","commandcode","xai","codex","agy"]}
+```
+
+If `CLIProxyAPI: not set up`, the three OAuth providers will report "needs
+CLIProxyAPI". That is expected on a fresh machine — tell the human that
+`kimi` / `opencode` / `commandcode` work without it, and ask whether they want
+the OAuth three as well.
+
+**Keep it running.** Do not leave it in the foreground of a terminal the human
+will close. Offer a background service (launchd on macOS, systemd on Linux):
+
+```bash
+# macOS: ~/Library/LaunchAgents/dev.quota-pill.plist
+#   ProgramArguments: ["/usr/bin/env","node","<abs path>/bin/quota-pill-server.js"]
+#   RunAtLoad: true
+#   KeepAlive: true
+```
+
+Ask before installing a service — that is a persistent change to their machine.
+
+---
+
+## 2. Ask which providers the user actually has
+
+Do **not** guess. Ask, in one message, listing the options with what each needs:
+
+> I can read quota for six providers. Which do you have?
+>
+> - **Kimi Coding** — needs a `KIMI_CODING_API_KEY`
+> - **OpenCode Go** — needs an `OPENCODE_GO_API_KEY`
+> - **Command Code** — needs a `COMMANDCODE_API_KEY`
+> - **xAI / Grok**, **Codex / ChatGPT Plus**, **Antigravity** — need CLIProxyAPI installed and logged in
+>
+> Tell me which ones, and paste the key for any of the first three.
+
+If they have none of them: stop and say the plugin has nothing to show yet.
+Do not install a fake provider to "make it look working".
+
+---
+
+## 3. Write the API keys
+
+Keys live in `~/.dsh/.credentials.yaml` under `refs`. **Read the file first** —
+it usually already exists and contains other credentials that must not be lost.
+
+```yaml
+refs:
+  KIMI_CODING_API_KEY: sk-...
+  OPENCODE_GO_API_KEY: sk-...
+  COMMANDCODE_API_KEY: sk-...
+```
+
+Rules:
+
+- **Append or edit one line at a time.** Never rewrite the whole file from a
+  template — that would delete the user's other credentials.
+- **Never echo a key back** into the chat, a log, or a commit. After writing,
+  verify only that the key is *present*, not what it is.
+- If the file does not exist, create it with `chmod 600`.
+
+Verify each one without printing it:
+
+```bash
+python3 - <<'PY'
+import yaml, os
+d = yaml.safe_load(open(os.path.expanduser('~/.dsh/.credentials.yaml')))
+refs = d.get('refs') or {}
+for k in ('KIMI_CODING_API_KEY','OPENCODE_GO_API_KEY','COMMANDCODE_API_KEY'):
+    print(f'{k}: ' + ('present' if refs.get(k) else 'MISSING'))
+PY
+```
+
+---
+
+## 4. Configure the OAuth three (only if asked for)
+
+These read token files that **CLIProxyAPI** writes. This plugin never performs
+the OAuth flow itself.
+
+1. Check whether CLIProxyAPI is already there:
+
+   ```bash
+   ls ~/.cli-proxy-api/ 2>/dev/null
+   ```
+
+2. If the directory is missing, tell the human:
+
+   > xAI / Codex / Antigravity need CLIProxyAPI installed and logged in once.
+   > It writes tokens to `~/.cli-proxy-api/`, which is what I read.
+   > Install it, log into those services, then tell me — or skip them for now.
+
+3. Once logged in, confirm the files appeared:
+
+   ```bash
+   ls ~/.cli-proxy-api/ | grep -E '^(xai|codex|antigravity)-'
+   ```
+
+4. **Codex needs CLIProxyAPI to be *running***, not just installed. Codex quota
+   is read from CLIProxyAPI's management API (`/v0/management/auth-files`), which
+   reports the `X-Codex-*` headers CLIProxyAPI observed. Without it running, the
+   fallback hits `chatgpt.com`, which blocks non-browser TLS and returns 403.
+
+---
+
+## 5. Verify end to end
+
+```bash
+curl -s 'http://127.0.0.1:8319/quota/all?fresh=1' | python3 -m json.tool | head -40
+```
+
+For each provider look at `kind`:
+
+| `kind` | Meaning |
+|---|---|
+| `subscription-quota` | working — `remainingPct` and `windows` are populated |
+| `none` | not configured — the `error` field says exactly what to add |
+| `probe-failed` | configured but the upstream call failed — see `error` |
+| `payg` | metered billing with no ceiling; no percentage exists |
+
+Cross-check one provider against its official dashboard if the human is unsure.
+**The plugin reports remaining quota, not used.**
+
+If a provider came back `none` with `no <REF>`, the key did not get written —
+go back to step 3. Do not report success while any asked-for provider is `none`.
+
+---
+
+## 6. Report back
+
+Tell the human, per provider: how much is left and when it resets. Then state
+plainly:
+
+- which providers are working
+- which are skipped, and the single action that would enable each
+
+Do not paste raw JSON. Do not claim a provider works if it returned `none` or
+`probe-failed`.
+
+---
+
+## Troubleshooting
+
+**Pill shows "quota service is not running"**
+The sidecar is not up, or is on another port. Start it; if it must live on a
+different port, set `window.__QUOTA_PILL_PORT__` or run with `QUOTA_PILL_PORT=…`
+and set the same on the client side.
+
+**`probe-failed` with http 403 / ECONNRESET**
+Some upstreams (`chatgpt.com`, `googleapis`, `grok.com`) need either CLIProxyAPI
+or a local proxy. Codex additionally needs CLIProxyAPI *running* for its
+observed-headers route.
+
+**`none` with "no … in ~/.dsh/.credentials.yaml"**
+The key is missing. Steps above show the exact `refs.` name to add.
+
+**Everything is `none` even though keys exist**
+Check the sidecar's printed `credentials:` path — it may be reading a different
+`DSH_HOME` than the one the user edited.
+
+**Numbers look stale**
+The sidecar caches for 60s. `?fresh=1` forces an upstream read. The pill does
+this automatically when the session context changes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 598934321
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,208 @@
-# Temporary Holding Version
+# dsh-quota-pill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A quota pill for the [DeepSeek Harness](https://github.com/deepseek-ai) web GUI:
+**how much is left** on every LLM subscription you have, in one collapsible pill
+next to the composer.
+
+![quota pill](docs/screenshot.png)
+
+It sits in the composer toolbar, shows the tightest window at a glance, and opens
+into a per-provider breakdown with reset times. Switch sessions and it follows
+the model — showing that provider's last reading while it refreshes, then easing
+into the live number.
+
+## What it reads
+
+| Provider | Credential |
+|---|---|
+| **Kimi Coding** | `refs.KIMI_CODING_API_KEY` in `~/.dsh/.credentials.yaml` |
+| **OpenCode Go** | `refs.OPENCODE_GO_API_KEY` |
+| **Command Code** | `refs.COMMANDCODE_API_KEY` |
+| **xAI (Grok)** | OAuth token from [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) |
+| **Codex (ChatGPT Plus)** | same — and CLIProxyAPI must be **running** |
+| **Antigravity** | same |
+
+The three API-key providers need nothing but the key. The three OAuth providers
+need CLIProxyAPI installed and logged in, because that is what holds the tokens;
+this plugin only reads them and never runs an OAuth flow itself.
+
+Every provider is optional. Unconfigured ones say exactly what is missing instead
+of showing a fake zero.
+
+## Install
+
+```bash
+# 1. the DSH plugin
+dsh plugin add @hystudio/dsh-quota-pill
+
+# 2. the sidecar (reads credentials, talks to upstream APIs)
+npx @hystudio/dsh-quota-pill
+```
+
+The pill shows **"quota service is not running"** with that exact command until
+the sidecar is up. Keep it running in the background — see
+[Running it as a service](#running-it-as-a-service).
+
+Then add whichever keys you have:
+
+```yaml
+# ~/.dsh/.credentials.yaml
+refs:
+  KIMI_CODING_API_KEY: sk-...
+  OPENCODE_GO_API_KEY: sk-...
+  COMMANDCODE_API_KEY: sk-...
+```
+
+Reload the DSH window. Done.
+
+### Let an agent do it
+
+The repo ships [`AGENTS.md`](AGENTS.md) — a step-by-step guide written for an AI
+agent. Ask your agent to set the plugin up and it will detect what you already
+have, ask only for what it cannot know (your keys), write them safely, and verify
+each provider end to end.
+
+```text
+Read AGENTS.md in this repo and set up dsh-quota-pill for me.
+```
+
+## Running it as a service
+
+`npx` in a terminal dies with the terminal. Pick one:
+
+**macOS (launchd)** — `~/Library/LaunchAgents/dev.quota-pill.plist`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.quota-pill</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string><string>node</string>
+    <string>/absolute/path/to/bin/quota-pill-server.js</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict></plist>
+```
+
+```bash
+launchctl load ~/Library/LaunchAgents/dev.quota-pill.plist
+```
+
+**Linux (systemd)** — `~/.config/systemd/user/quota-pill.service`
+
+```ini
+[Unit]
+Description=dsh-quota-pill sidecar
+
+[Service]
+ExecStart=/usr/bin/env node /absolute/path/to/bin/quota-pill-server.js
+Restart=always
+
+[Install]
+WantedBy=default.target
+```
+
+```bash
+systemctl --user enable --now quota-pill
+```
+
+## How it works
+
+```
+DSH web GUI
+   └─ client.js          renders the pill; never sees a credential
+        │  HTTP (localhost)
+        ▼
+      sidecar           reads ~/.dsh/.credentials.yaml and ~/.cli-proxy-api/*.json,
+                        calls each provider's quota endpoint, caches 60s
+```
+
+Two processes because credentials must never reach the browser, and because
+upstream calls need real timeouts and a TLS stack Node's `fetch` does not have
+for some hosts.
+
+### Endpoints
+
+| Path | Purpose |
+|---|---|
+| `GET /health` | liveness + provider list |
+| `GET /quota?model=<id>` | one provider's reading, selected by model prefix |
+| `GET /quota/all` | every provider, concurrently |
+| `GET /setup` | what each provider still needs |
+
+`?fresh=1` bypasses the 60-second cache.
+
+### Response
+
+```jsonc
+{
+  "kind": "subscription-quota",   // subscription-quota | payg | none | probe-failed
+  "provider": "opencode",
+  "displayName": "OpenCode Go",
+  "remainingPct": 17,             // remaining, never used
+  "window": "monthly",            // the binding window
+  "resetAt": "2026-11-12T00:00:00.000Z",
+  "products": { "rolling": 9, "weekly": 67, "monthly": 83 },  // per-window used%
+  "windows": [                    // one row each in the UI
+    { "key": "monthly", "remainPct": 17, "resetAt": "..." }
+  ],
+  "cached": false,
+  "at": 1792500000000
+}
+```
+
+`kind` is meant to be exhaustive so the UI never has to guess:
+
+- `subscription-quota` — a real percentage exists
+- `payg` — metered billing, no ceiling (shows spend, not a percentage)
+- `none` — not configured; `error` names the missing credential
+- `probe-failed` — configured but the upstream call failed
+
+## Notes on specific providers
+
+**Codex** is read through CLIProxyAPI's management API, which reports the
+`X-Codex-*` headers CLIProxyAPI observed while proxying real traffic. The direct
+`chatgpt.com/backend-api/codex/usage` endpoint sits behind Cloudflare and rejects
+non-browser TLS fingerprints, so it only works as a fallback. CLIProxyAPI must be
+*running*, not merely installed.
+
+**xAI** has three account generations: grandfathered plans report a percentage
+directly, current plans only reveal allowance in `x-ratelimit-*` response headers
+of a one-token completion, and unified-billing accounts have no ceiling at all
+(reported as `payg`).
+
+**Antigravity** shares one quota pool across all Gemini models, so it reports a
+single aggregate row — per-model rows would all be the same number and the label
+would flicker between models you do not even have configured.
+
+**Command Code** does not expose a monthly ceiling. The adapter derives it from
+`monthlyCap = weekly.cap × 2`, an identity verified against two different plans
+(31.6 + 38.4 = 70 with `weekly.cap` 35; 0.225 + 9.775 = 10 with `weekly.cap` 6).
+
+## Privacy
+
+- Credentials are read from disk, used for the upstream call, and never logged.
+- The sidecar binds `127.0.0.1` only.
+- Nothing is sent anywhere except the provider's own quota endpoint.
+- The client shows no credential, and the sidecar's JSON carries no token.
+
+## Development
+
+```bash
+git clone https://github.com/598934321/dsh-quota-pill
+cd dsh-quota-pill
+npm test              # 26 tests, offline
+npm start             # sidecar on :8319
+```
+
+Tests are offline by design: they point the credential layer at a nonexistent
+directory so they never touch a live account. Fixtures in `test/fixtures.js` are
+synthetic — no real emails, account ids, or balances.
+
+## License
+
+MIT

package/bin/quota-pill-server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Entry point: `npx @hystudio/dsh-quota-pill` or the `dsh-quota-pill` bin. */
+import '../src/server.js';