Mu-scorpio/token-usage-counter

Token Usage Counter for DeepSeek Harness

Persistent provider-reported token usage statistics for DeepSeek Harness. The plugin keeps uncached input, cache read, cache write, and output usage in separate buckets, and exposes cumulative, daily, per-session, and per-model views.

Features

Install

To install this 0.5.0 source before an npm release, replace COMMIT with the full 40-character commit of the reviewed revision:

dsh plugin --profile web add -w github:Mu-scorpio/token-usage-counter#COMMIT

The npm command installs the latest independently published version, which may differ from this checkout:

dsh plugin --profile web add -w dsh-token-usage-counter
dsh web

The Bundle is additive: it mounts only the plugin-owned token-usage-counter entry and leaves the built-in usage accumulator and page enabled.

Version 0.4.0 moves persistence from the shared usage-stats namespace to the plugin-owned dsh-token-usage-counter namespace. Existing 0.3.x totals are not silently migrated because the shared namespace belongs to the built-in plugin; the new counter starts with an independent snapshot after the upgrade.

Version 0.5.0 uses DSH's public storage-domain service for persistent data in dsh_token_usage_counter, and serves a read-only aggregate snapshot to its settings page through the existing DSH browser authentication. It does not write statistics into Profile configuration forms. Legacy plugin-owned settings data is not copied automatically; persisted session history can rebuild the counter where the DSH session store still retains that history. See SECURITY.md for permissions and evidence limits.

Local development

From this checkout:

dsh web --patch ./cordis.yml

The local overlay mounts src/index.ts without replacing built-in components. For a manual composition, add only the plugin-owned entry:

- insert:
    - id: token-usage-counter
      name: './src/index.ts'

Compatibility

• Node.js: 22.13.0 or newer.
• Plugin 0.5.0: 0.2.0-rc.2, 0.2.1-alpha.1 and 0.2.1-alpha.2 passed isolated install, startup, persistence, authentication and uninstall checks. Older releases are unknown for this source.
• Profile: web.
• Exact per-release results and disposable-profile evidence are recorded in docs/VERIFICATION.md.

Store listing migration details: docs/STORE-REMEDIATION.md.

Build

npm install --ignore-scripts --legacy-peer-deps --no-package-lock
npm run build
npm run verify

Run a packed Bundle against an independently installed official DSH CLI:

npm run test:disposable -- /path/to/dsh/lib/bin.js /path/to/plugin.tgz

The generated host and client bundles are committed under lib.

Counting rules

The plugin listens to the durable session event stream:

• assistant/message.usage is counted once.
• compaction/summary.usage is counted as one provider call.
• A usage-only assistant/chunk is held until its matching assistant/message.
• When a chunk and final message describe the same turn and step, the final value replaces the early sample.
• Failed requests, retries, and fork seed history are not counted twice.

API

The plugin provides ctx.tokenUsageCounter:

ctx.tokenUsageCounter.getSummary()
ctx.tokenUsageCounter.getSession(sessionId)
ctx.tokenUsageCounter.getModel(provider, model)
ctx.tokenUsageCounter.formatSummary()

Links

• npm: https://www.npmjs.com/package/dsh-token-usage-counter
• GitHub: https://github.com/Mu-scorpio/token-usage-counter
• DSH Bundle documentation: https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md

License

MIT