deepseek-peak

A drop-in dsh-plugin for the deepseek-ai/deepseek-harness web UI that shows the DeepSeek V4 API's current peak / off-peak pricing state, lets you pause the LLM during peak hours with a queue that drains on its own, watches your account balance, and warns you when the balance drops below a threshold you set.

The PEAK pill in the session header, the BALANCE row with the REFRESH and TOP UP actions, and the per-model 30-day peak/off-peak bar charts (v4-pro and v4-flash). The pill is amber when the balance drops below the configured lowBalanceWarningUsd threshold.

What it does

• Pill (always visible, in the session header next to the Session log button). Reads the current phase from the browser clock against a baked-in UTC schedule:

  • Green during off-peak windows
  • Red during peak windows (2× the off-peak rate)
  • A PRE-CUTOVER badge while the new schedule is being previewed
  • A live countdown to the next phase boundary
  • A → live target arrow while pre-cutover, or a → next phase HH:MM arrow after the cutover
  • A pause toggle at the right edge of the pill: when on AND the phase is peak, the LLM stream is gated and user messages queue instead of running
  • Amber border + dot + label when the account balance drops below the configured lowBalanceWarningUsd threshold (default $1.00). Overrides the phase color so a low balance is visible at a glance.

• Tooltip (on hover, while the pill is open). Expands under the pill:

  • A BALANCE row showing the current DeepSeek account balance (host-routed through /api/peak-hours/balance so the API key never leaves the harness process). Two action pills on the right:
    • REFRESH — bypasses the 5-min host cache AND the browser cache so a user who just topped up sees the new number without waiting for the natural refresh tick.
    • TOP UP — opens https://platform.deepseek.com/top_up in a new tab.
  • A per-model chart card for each model the user has run in the trailing 30 days (v4-pro, v4-flash). Each card has a tiny inline SVG daily bar chart, 30 days wide, with peak (red) on top of off-peak (green). The split is computed from each event's UTC timestamp against the schedule.
  • A small legend so the peak/off-peak split is legible without a tooltip.
  • When the LLM is gated and the queue has items, a queue card appears under the chart with one row per queued message and a per-row send arrow that dispatches that single message immediately (bypasses the global pause).

• Settings (registered on the existing peak-hours namespace in the host's settings plane, exposed through Settings → Plugins → Plugin configuration → Peak hours):

  • paused — boolean, the same value the pill toggle writes. Two write paths into the same field; last write wins.
  • lowBalanceWarningUsd — number, the threshold below which the pill switches to amber. Default $1.00. Zero is allowed (always warn); negatives are rejected by the schema.

• Background refresh:

  • The state poll runs every 2 s on the browser (Pill's usePeakHoursState hook), so toggle / threshold / queue / balance changes propagate in under two ticks.
  • The balance is fetched server-side and cached for 5 min, with a 30-s fast retry on transient errors so a brief blip doesn't poison the cache.
  • The chart's per-day buckets come from the host's /api/peak-hours/usage route, which walks the session persistence log. The in-browser trajectory walk is a fallback for the harness-not-running case.

Source of truth: api-docs.deepseek.com/quick_start/pricing/. The schedule windows and the cutover date are baked in as constants in src/client/domain.ts. The PRE-CUTOVER window is the period between "the new schedule is announced" and "the new schedule is enforced"; the pill shows it for the duration and the gate is engaged whenever paused && peak regardless of cutover state.

This repo ships two things:

1. harness-plugin/ — a dsh-plugin Cordis client package for the harness web UI. This is the real integration.

2. widget.html + serve.js — a self-contained browser widget you can pin as a tab in any browser, no harness required. Useful as a fallback for users who don't run the harness. It does NOT include the pause / queue / balance features; it's a phase + countdown display only.

The harness plugin is the rich one. The standalone widget is a "schedule on a second monitor" display.

Install (harness plugin)

Requires:

• A checked-out deepseek-harness working tree (any recent commit)
• node ≥ 22.19
• pnpm ≥ 11 (install once with npm i -g pnpm)

# Clone this repo
git clone https://github.com/YMRYMR/deepseek-peak.git
cd deepseek-peak

# One-liner installer: takes your harness clone as the argument
./install.sh /path/to/deepseek-harness

What the installer does (each step is idempotent and skipped if already done):

1. Copies harness-plugin/ → <harness>/packages/client/ui-peak-hours/
2. Adds the ui-peak-hours row to packages/bundle/web-app/cordis.patch.yml
3. Adds the workspace dep to packages/bundle/web-app/package.json
4. Adds the project reference to tsconfig.client.json
5. Adds the path mapping to tsconfig.base.json
6. Runs pnpm install in the harness
7. Runs pnpm run build:lib:host (required for the generated Typert contracts)
8. Runs pnpm --filter @deepseek-ai/dsh-client-ui-peak-hours run bundle
9. Runs the harness verification gates (warnings only)

Then start the harness:

cd /path/to/deepseek-harness
pnpm dsh web

Open http://127.0.0.1:3080/. The pill appears in the top-right of the session header, left of the Session log button.

Hard-refresh the browser (Ctrl+Shift+R) the first time so the new __DSH_BOOT__ roster loads.

What you should see

A compact pill, ~180 px wide, with this shape (left to right):

[●] PEAK PRE-CUTOVER  08h 11m  →  live   [pause-switch]

• [●] is the colored dot — green for off-peak, red for peak, amber when the balance is below the configured threshold (overrides the phase color)
• The phase label and the PRE-CUTOVER badge (only during the pre-cutover window)
• The countdown to the next phase boundary (1 Hz tick)
• The target arrow: → live while pre-cutover, → next phase HH:MM after the cutover
• The pause switch at the right edge (red when on, gray when off)

Hover the pill

The card expands under the pill:

• BALANCE row — your DeepSeek account balance, with the REFRESH and TOP UP actions on the right
• Per-model chart card for each model you've used in the trailing 30 days (typically v4-pro and v4-flash). Tiny inline-SVG daily bar chart, 30 days wide, peak (red) on top of off-peak (green). Day totals shown in the top-right of each card.
• A small legend under the chart: red = peak, green = off-peak
• If the queue has items, a queue card with one row per queued message and a per-row send arrow for manual dispatch

Pause-during-peak workflow

1. Click the pill's pause switch to the right of the countdown.
2. While the switch is on AND the phase is peak, the next LLM stream (user message or subagent tool call) is gated. The harness shows the request as queued, and the tooltip expands to show the queue card.
3. The queue is FIFO. Each item is dispatched the moment the switch flips off or the phase leaves peak.
4. To dispatch a single item without flipping the global pause, click the row's per-row send arrow in the queue card.

Low-balance warning

Open Settings → Plugins → Plugin configuration → Peak hours and set lowBalanceWarningUsd to your preferred floor (default 1.00). The pill switches to amber the moment the live account balance drops below the value. Override the same field directly in ~/.dsh/settings.yaml:

peak-hours:
  paused: false
  lowBalanceWarningUsd: 1.5

The next 2 s state poll picks up the new value automatically.

Uninstall

./uninstall.sh /path/to/deepseek-harness

The script removes the plugin directory and prints the four small wire-up entries you need to delete by hand (one line each in cordis.patch.yml, package.json, and the two tsconfig files).

Install (standalone widget)

No harness needed. Just a Node server that serves a static HTML page.

cd deepseek-peak
node serve.js

Opens http://127.0.0.1:3737/ in your default browser. Pin the tab. Press Ctrl+C in the terminal to stop.

The standalone widget includes a 24-hour timeline of peak windows, a V4-Flash / V4-Pro model selector, and the actual $/1M-token rate for each tier. Useful on a screen that doesn't have the harness open. Pause / queue / balance features are NOT in the standalone widget — they live in the harness plugin only.

Why a plugin AND a standalone

The harness pill is the right answer inside the harness. The standalone is the right answer everywhere else (a second monitor, a tablet, a phone browser). Both compute the same numbers from the same authoritative schedule, so they never disagree.

Host routes exposed by the plugin

Route	Method	Purpose
/api/peak-hours/state	GET	Current pause / phase / queue / balance / threshold (2 s polled by the browser)
/api/peak-hours/state	POST	Toggle the global pause (writes through the host's settings service)
/api/peak-hours/balance	GET	Live DeepSeek account balance (5 min host cache)
/api/peak-hours/balance?fresh=1	GET	Force a fresh upstream fetch (bypasses both the host and the browser cache; the in-tooltip REFRESH button calls this)
/api/peak-hours/usage?rangeDays=N	GET	Per-day, per-model token / cost buckets for the trailing N days (default 30, max 365; 5 min host cache)
/api/peak-hours/usage?fresh=1&rangeDays=N	GET	Force a fresh host walk of the session persistence log
/api/peak-hours/queue/dispatch	POST	Manually dispatch the front queued item (the per-row send arrow in the queue card calls this)

The API key is held by the host's credentials seam and never reaches the browser — the host routes read the key, fetch from api.deepseek.com, and return the parsed JSON envelope.

Verified

The plugin passes every harness gate I could run on a Windows dev tree:

Check	Result
pnpm run constraints	220/220 packages conform
pnpm run verify-cordis-config	120/120 config files passed
pnpm run verify-package-invariants	220/220 hand-owned companions conform
tsc -b tsconfig.client.json	clean
pnpm --filter ... run bundle	~78 kB client.js
pnpm run build (host + client + web)	clean
Live runtime smoke (curl /plugins/.../client.js)	200, ~78 kB, slot registered

What the source layout looks like

deepseek-peak/
├── README.md               # this file
├── LICENSE                 # MIT
├── .gitignore
├── install.sh              # one-line installer for the harness plugin
├── uninstall.sh            # rollback helper
├── package.json            # standalone-widget package
├── serve.js                # standalone-widget Node server
├── smoke.js                # standalone-widget self-test (5/5 passes)
├── widget.html             # the standalone widget
├── docs/
│   └── pill-preview.png    # the screenshot at the top of this README
└── harness-plugin/         # the in-harness plugin (copied to a harness
                            #   clone by install.sh)
    ├── package.json
    ├── tsconfig.json
    ├── tsdown.config.ts
    ├── README.md
    └── src/
        ├── index.ts                        # host face — routes, settings,
        │                                   #   LLM gate, 1 Hz phase ticker
        ├── invariant.ts
        ├── css-modules.d.ts
        └── client/
            ├── index.ts                    # browser apply() — registers the pill
            ├── domain.ts                   # pure peak/off-peak math, schedule,
            │                               #   pre-cutover computation
            ├── phase.ts                   # phase types, currentPhase(), labels
            ├── peakHoursState.ts          # state hook — 2 s poll, paused toggle
            ├── balance.ts                 # balance fetch + 5 min cache, REFRESH support
            ├── usage.ts                   # host usage fetch with host-side fallback
            ├── pricing.ts                  # model display names
            ├── PeakHoursPill.tsx           # the always-visible React component
            ├── PeakHoursPill.module.css
            ├── PeakHoursHost.tsx           # hover-state host; renders the tooltip + queue
            ├── PeakHoursHost.module.css
            ├── UsageTooltip.tsx            # the tooltip card (balance + chart + queue)
            ├── UsageTooltip.module.css
            ├── QueueCard.tsx               # per-row dispatch card
            ├── QueueCard.module.css
            ├── PauseSwitch.tsx             # the pill's right-edge toggle
            ├── PauseSwitch.module.css
            ├── PeakHoursDock.tsx           # legacy input.dock variant, kept for
            │                                #   reference; the current pill lives
            │                                #   in the session header instead
            └── PeakHoursDock.module.css

Notes

• The schedule and the pre-cutover date are baked in as constants in src/client/domain.ts. If DeepSeek changes the windows or the cutover date, edit the constants there and re-bundle.
• All times are computed in UTC; only the display is localized to the browser's IANA zone.
• The pill trusts the browser clock against the baked-in UTC schedule. A user with a mis-set system clock will see a misleading status. A future iteration can sanity-check via worldtimeapi.org.
• The pause toggle on the pill and the paused field in the Plugin configuration page are two write paths into the same persisted setting. The 2 s state poll reconciles whichever wrote last.
• The pill's REFRESH button invalidates the browser cache (so a rapid second click still reaches the host) and calls the host with ?fresh=1 (so the host bypasses its own 5 min cache and re-fetches from api.deepseek.com). Both must be running the latest code for REFRESH to work end-to-end; the host change requires a dsh web restart.

License

MIT. See LICENSE.