dsh-agent-pricing

Readme

# dsh-agent-pricing

> Real-time **session cost preview** for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a live cost readout under the composer, a today-usage overlay chart, and `price_estimate` / `session_cost` agent tools — with **prices kept in sync with the DeepSeek official pricing page** (peak / off-peak aware).

[English](README.md) | [中文](README.zh.md)

[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-%E2%9C%93-5B4CF0?style=flat-square)](https://github.com/topics/dsh-plugin)
[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-ecosystem-4D6BFE?logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
[![GitHub stars](https://img.shields.io/github/stars/Way2LOose4/dsh-agent-pricing?logo=github)](https://github.com/Way2LOose4/dsh-agent-pricing/stargazers)
[![License](https://img.shields.io/github/license/Way2LOose4/dsh-agent-pricing)](LICENSE)
[![Last commit](https://img.shields.io/github/last-commit/Way2LOose4/dsh-agent-pricing)](https://github.com/Way2LOose4/dsh-agent-pricing/commits/main)

---

## Features

- **Live cost readout under the composer** — the current session's accumulated cost, refreshed every 5 seconds, CNY ⇄ USD toggle. This is your approximate balance-consumption preview while you work.
- **Today overlay** — today's input/output/cache tokens, an hourly usage bar chart, and a per-model breakdown. The overlay also shows **which price source produced the numbers**, when the table was last verified, and — after peak/off-peak billing takes effect — whether the **peak or off-peak** tier applies right now.
- **Agent tools** — `price_estimate` (per-call estimate) and `session_cost` (full-session usage read from the same source as the Web stats strip), so your agent can quote its own burn rate mid-task.
- **Prices always aligned with the official site** — on activation and every 30 minutes, the plugin scrapes [the official DeepSeek pricing page](https://api-docs.deepseek.com/quick_start/pricing): current rates **plus announced peak/off-peak tiers with their effective date**. Any failure degrades gracefully through the fallback chain; a network outage never breaks estimation.

```
workspace agent-pricing.json   (1) your override — wins over everything
        ↓ absent
official pricing page scrape   (2) DeepSeek rows, incl. announced peak/off-peak tiers
        ↓ down / HTML changed
this repo's prices.json        (3) edit it on GitHub → every install re-aligns,
        ↓ down                     no reinstall needed
built-in table                 (4) offline fallback — ships with announced tiers
```

DeepSeek peak/off-peak billing (announced effective **16:00 UTC 2026-08-16**, peak hours 01:00–04:00 & 06:00–10:00 UTC) is computed **per usage event at its own timestamp**: calls made before the switch stay at flat rates, peak-hour calls bill at peak rates automatically.

---

## Installation

Requirements: DeepSeek Harness (Web profile), `0.1.0-rc.6` verified.

### A. DSH plugin marketplace (recommended)

1. Install **dsh-plugin-marketplace** if you don't have it yet ([repo & one-line installer](https://github.com/bradeGithub/DSH-Plugins-Marketplace)).
2. Open **Settings → DSH插件市场**, search `dsh-agent-pricing`, click **安装 / Install**.
3. **Restart DSH** (relaunch `dsh web`) and refresh the page.

### B. dsh CLI (pnpm handles the GitHub URL)

```sh
dsh plugin --profile web add github:Way2LOose4/dsh-agent-pricing
# then restart the Web profile.
```

### C. Manual

Clone into `%DSH_HOME%/profiles/web/node_modules/dsh-agent-pricing` and append to `%DSH_HOME%/profiles/web/cordis.patch.yml`:

```yaml
- insert:
    - id: agent-pricing
      name: dsh-agent-pricing
```

Restart DSH. The Web profile's HMR is disabled — code changes only take effect on restart.

---

## Usage

1. Open any conversation — a compact cost line appears under the composer.
2. Click **CNY/USD** to switch currency, click **▸ 图表** to open the today overlay.
3. Ask your agent "how much have we spent?" — it can answer itself with `session_cost`, and quote before-the-fact numbers with `price_estimate`.

## Configuration (optional)

Drop an `agent-pricing.json` into your workspace root to fully override the price table — same shape as [`prices.json`](prices.json) in this repo:

```json
{ "models": [{ "keys": ["my-model"], "label": "My Model", "input": 1.0, "output": 2.0 }] }
```

Optional per-row fields: `cacheRead`, `cacheWrite`, and `tiers` (`{ "effectiveAt", "peakHoursUtc", "peak": {...}, "offPeak": {...} }`). The file is re-read on activation and on every periodic refresh. Models that match no row cost 0 and are listed in the result's `note`.

## HTTP endpoints & tools

| Endpoint | Method | Description |
|---|---|---|
| `/api/pricing/session-cost?sessionId=…&currency=CNY` | GET | Full-session usage + cost |
| `/api/pricing/today?currency=CNY` | GET | Today's tokens/cost + hourly series + price source |
| `/api/pricing/estimate?model=…&input_tokens=…&output_tokens=…` | GET | Single-call estimate |
| `/api/pricing/debug` | GET | Price-source layers, sync state, tier rows |
| `/api/pricing/reload` | ANY | Force a price-table refresh |

Model tools registered: `price_estimate`, `session_cost`.

## Keeping prices current

DeepSeek rows re-align automatically from the official page. For other vendors, update [`prices.json`](prices.json): every installation refetches it every 30 minutes. A workspace-level `agent-pricing.json` still wins when present.

## Repo layout

```
├─ package.json        bundle manifest (dsh.client + dsh.bundle.patch)
├─ cordis.patch.yml    profile mount row
├─ prices.json         repo-hosted price table (auto-fetched by installs)
├─ lib/
│  ├─ index.js         host: routes, tools, price layers, official-page parser
│  └─ client.js        browser: cost readout + today overlay
├─ test.mjs            official-page parser + pricing math (peak/off-peak, CNY/USD)
└─ test-refresh.mjs    price-layer precedence: file > official > repo > builtin
```

Run the tests against a saved copy of the official pricing page:

```sh
node test.mjs official-pricing.html
node test-refresh.mjs official-pricing.html
```

## Limitations & security notes

- All figures are **estimates**: they mirror the official public price table, not your account's negotiated rates or remaining balance. DeepSeek exposes a real `/user/balance` endpoint; this plugin deliberately stays read-only on public data and needs no API key.
- Cost history is computed from your local session logs; nothing leaves your machine except the price-table requests to the official docs page and this repo's raw `prices.json`.
- Only install plugins you trust — a plugin package is registered into the Web profile and loads with every DSH start.

## Compatibility

| DSH version | Status |
|---|---|
| 0.1.0-rc.6 | ✅ verified |

## License

MIT — see [LICENSE](LICENSE).