dsh-usage-plugin

A DeepSeek Harness plugin that reports the current session's token usage and estimated cost. One host-plane plugin row registers:

• the usageReport session-projection unit — folds the provider-reported usage of every model request (uncached input, cache-read, cache-write, output) attributed to the model named by the nearest request/header, and prices each sample with the configured price table;
• the /usage human command — prints the report as a table;
• the usage_report model tool — returns the same report as canonical JSON, so the agent itself can check budget mid-task.

Costs are estimates, not billing records: they multiply the provider's reported token buckets by the price table below. The token buckets are exact provider numbers; the prices are configuration.

Install

Requirements: a DSH profile with the tools, commands, and sessionProjections services (the web and headless profiles provide all three via dsh-base).

#        - id: usage-report

#          name: 'dsh-usage-plugin'

## Usage

### `/usage` (human)

Type `/usage` in a chat. Example output:

```text
Session usage report
model                 uncached-input  cache-read  cache-write  output  requests  est. cost
deepseek-v4-flash              1,234        5,678           12   8,901        14  $0.012345
Total                          1,234        5,678           12   8,901        14  $0.012345

usage_report (model tool)

The model can call it mid-task ("how much have we spent?") and receives the same numbers as canonical JSON:

{
  "totals": { "uncachedInputTokens": 1234, "cacheReadTokens": 5678, "cacheWriteTokens": 12, "outputTokens": 8901, "requests": 14, "cost": 0.012345 },
  "models": [{ "model": "deepseek-v4-flash", "usage": { "...": "..." } }]
}

/usage (human)

Type /usage in a chat. Example output:

Session usage report
model                 uncached-input  cache-read  cache-write  output  requests  est. cost
deepseek-v4-flash              1,234        5,678           12   8,901        14  $0.012345
Total                          1,234        5,678           12   8,901        14  $0.012345

usage_report (model tool)

The model can call it mid-task ("how much have we spent?") and receives the same numbers as canonical JSON:

{
  "totals": { "uncachedInputTokens": 1234, "cacheReadTokens": 5678, "cacheWriteTokens": 12, "outputTokens": 8901, "requests": 14, "cost": 0.012345 },
  "models": [{ "model": "deepseek-v4-flash", "usage": { "...": "..." } }]
}

Configuration

Set from the plugin row's config: block in cordis.patch.yml:

- id: usage-report
  name: 'dsh-usage-plugin'
  config:
    pricing: flat            # 'flat' | 'peak-offpeak'
    prices: {}               # per-model overrides, merged over the DeepSeek table
    defaultModel: unknown    # model attributed to usage with no request/header yet
    costDecimals: 6          # decimal places for USD in text output

Key	Default	Meaning
pricing	'flat'	'flat' uses one rate per model; 'peak-offpeak' varies the rate by UTC hour (DeepSeek's regime effective 2026-08-16).
prices	{}	Per-model overrides merged over the shipped DeepSeek table. A model with no entry counts its tokens but prices at $0 ("unpriced" in the report).
defaultModel	'unknown'	Model bucket for a usage sample that arrives before any request/header.
costDecimals	6	Decimal places for USD cost in text output.

Price entry shape (per model):

prices:
  deepseek-v4-flash:
    flat: { inputPerMillion: 0.14, cacheReadPerMillion: 0.0028, outputPerMillion: 0.28 }
    peakOffpeak:
      peak: { inputPerMillion: 0.44, cacheReadPerMillion: 0.014, outputPerMillion: 1.32 }
      offPeak: { inputPerMillion: 0.22, cacheReadPerMillion: 0.007, outputPerMillion: 0.66 }
      peakWindowsUtc: [[60, 240], [360, 600]]   # [start, end) minutes of day, UTC

Shipped DeepSeek prices (USD per 1M tokens)

Flat rates in effect since before 2026-08-16 (source: DeepSeek pricing):

Model	Input (cache miss)	Input (cache hit)	Output
deepseek-v4-flash	$0.14	$0.0028	$0.28
deepseek-v4-pro	$0.435	$0.003625	$0.87

Peak/off-peak regime effective 16:00 UTC 2026-08-16 (peak hours 01:00–04:00 and 06:00–10:00 UTC, off-peak otherwise):

Model	Cache hit off-peak / peak	Cache miss off-peak / peak	Output off-peak / peak
deepseek-v4-flash	$0.007 / $0.014	$0.22 / $0.44	$0.66 / $1.32
deepseek-v4-pro	$0.022 / $0.044	$0.66 / $1.32	$1.98 / $3.96

DeepSeek may change prices; restate prices from the pricing page when they do (bump the plugin's stateVersion after changing the fold, or the persisted projection cache may serve stale rows).