Introduction¶

DeepSeek Harness (DSH) is built on the idea of “everything is a plugin”. When using DSH for agent development or runtime, tracking the actual cost of API calls is a common requirement. Conventional logging is often insufficiently precise or relies on estimates, which can easily lead to billing discrepancies.

To solve this problem, a mechanism is needed that can convert usage reports into citable, append-only JSONL spend receipts. The dsh-spend-receipt plugin is designed for this purpose, addressing the lack of transparency and floating-point precision issues in traditional billing methods.

Plugin Overview¶

This is a DeepSeek Harness function plugin maintained by user jwilson411. Its core purpose is to convert Harness usage reports into a citable, append-only JSONL spend receipt, and to provide a spend_receipt tool to read back this data (including the last N lines, totals, and cache hit rates).

Core Features¶

The plugin mainly addresses the following issues:

1. Verifiable Billing Records
   Every record includes the actually reported token counts, pricing information, time window, and source. Readers can independently recalculate costs without having to trust this package. It performs no text tokenization or estimation; missing pricing is not filled with zero, but recorded as usd: null.

2. Append-Only JSONL Format
   The receipt file uses JSONL format and only appends without modification. Even crashes will not cause data corruption.

3. Precise Pricing and Calculation
   Totals are calculated using nano_usd integers to avoid floating-point drift. Pricing is based on the public DeepSeek price table from 2026-08-29 and distinguishes between Peak and Off-peak windows.

4. Session Log Synchronization
   Supports syncing usage from session logs by reading JSONL logs and extracting usage events from them.

Installation and Configuration¶

Before installation, ensure your environment meets the dependency requirements: Node.js >= 22.14.0.

1. Install the Plugin

Run the following command to add the plugin to the web profile configuration file:

dsh plugin --profile web add github:jwilson411/dsh-spend-receipt

The dsh plugin command appends the dsh.bundle.patch from the plugin package manifest to the configuration and applies the cordis.patch.yml layer.

2. Configure the Plugin

The plugin must be configured in cordis.patch.yml. Note that the target configuration entry (id: spend-receipt) replaces the entire configuration entry, so all fields that need to be retained must be re-declared.

- id: spend-receipt
  config:
    receiptPath: ~/.dsh/spend-receipt.jsonl
    sessionLog: ~/.dsh/sessions/current.jsonl

Usage¶

After installation and configuration, the spend receipt can be viewed using the spend_receipt tool.

1. Basic Usage

The tool supports two parameters:
* limit: Return the most recent N records; the default is the configured limit.
* sync: Whether to scan the session log first to sync new data; the default is true. Setting it to false reports only data that has already been recorded.

2. Example Output

The tool returns the receipt path, the rate table used, the specific row data, totals, and cache hit rates. An example JSONL record is as follows:

{
  "ts": "2026-08-29T09:00:12.000Z",
  "session_id": "sess-7c2",
  "model": "deepseek-v4-pro",
  "input_tokens": 12000,
  "cache_hit_tokens": 9000,
  "output_tokens": 800,
  "usd": 0.007524,
  "currency": "USD",
  "nano_usd": 7524000,
  "rate_table": "deepseek-v4@2026-08-29",
  "rate_tier": "peak",
  "ts_source": "event",
  "source": { "kind": "session-log", "path": "…/session.jsonl", "line": 3 }
}

Use Cases and Notes¶

Use Cases:
* Developers and teams that need accurate cost accounting.
* Scenarios that require auditing API call details and cache hit rates.
* Financial statistics where floating-point calculation errors should be avoided.

Notes:
* Dependency Versions: The plugin depends on @deepseek-ai/cordis (^4.0.1) and @deepseek-ai/dsh-tools (^0.1.1-rc.2).
* Pricing Logic: Pricing is based on the price table from 2026-08-29. Peak windows are UTC 01:00-04:00 and 06:00-10:00 (Monday through Friday); all other times are off-peak. Pricing depends on the model name, cache split, or timestamp; if any of these is missing, pricing cannot be performed.
* Permissions and Security: The plugin runs with the permissions of the DSH process. Before installation, it is recommended to review the source code and license (MIT).

Conclusion¶

The dsh-spend-receipt plugin provides DeepSeek Harness with a transparent, verifiable spend-tracking solution. By recording usage as an append-only JSONL file and using integer arithmetic to ensure precision, it effectively addresses the pain point of inaccurate cost estimation.

For plugin details and source code, refer to: GitHub