@chenmiao8563/dsh-token-ledger 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-10
+
+### Added
+
+- Host plugin `token-ledger` that folds the durable session event stream into
+  per-session, per-day and per-model token totals.
+- Four disjoint buckets (uncached input, output, cache read, cache write) with
+  `totalTokens` derived from them, plus reasoning tokens reported separately as
+  a subset of output.
+- Fork-aware folding: an inherited prefix is cut only when the session has a
+  parent, so a fork is not double counted and a resume is not under counted.
+- Backfill of every stored session on startup, so a fresh install shows real
+  history rather than starting from zero.
+- Restart-safe cursors: the ledger is written atomically to
+  `<DSH_HOME>/token-ledger/ledger.json` and resumes instead of recounting.
+- `/tokens [summary|export|json|path]` conversation command.
+- `dsh-token-ledger` CLI with `summary`, `audit`, `rebuild` and `export`
+  commands, `--json` output, and an audit that distinguishes a ledger merely
+  behind a live session from a genuinely wrong ledger.
+- CSV export for the daily, session and model tables.
+- Zero runtime dependencies, zero peer dependencies and no install scripts, so
+  the package installs without a build step.
+
+[Unreleased]: https://github.com/chenmiao8563/dsh-token-ledger/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/chenmiao8563/dsh-token-ledger/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chenmiao8563
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# dsh-token-ledger
+
+Transparent, auditable token accounting for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+
+[![CI](https://github.com/chenmiao8563/dsh-token-ledger/actions/workflows/ci.yml/badge.svg)](https://github.com/chenmiao8563/dsh-token-ledger/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@chenmiao8563/dsh-token-ledger.svg)](https://www.npmjs.com/package/@chenmiao8563/dsh-token-ledger)
+[![license](https://img.shields.io/npm/l/dsh-token-ledger.svg)](./LICENSE)
+
+[English](README.md) | [中文](README.zh.md)
+
+---
+
+## What this is
+
+A ledger, not a dashboard. It folds the durable DSH session log into token
+totals, keeps them restart-safe, and — the part that matters — lets you
+**recompute the exact same numbers from the raw logs and diff them** against
+what the running host recorded.
+
+```
+$ dsh-token-ledger audit
+scanned 139 session log(s), 344203 events, 29 fork(s), 0 unreadable
+
+  stored      6901 calls  1205685663 tokens
+  recomputed  6901 calls  1205685663 tokens
+
+  audit: match — the stored ledger equals a fresh fold of the raw logs
+```
+
+If you only want a pretty chart, there are a dozen plugins for that. This one is
+for when you need to *defend* the number.
+
+## Why it installs where others do not
+
+| Property | Why it matters |
+| --- | --- |
+| **Zero dependencies, zero peer dependencies** | Nothing to resolve, so a version drift in a DSH package cannot break the install. |
+| **Zero install scripts** | `dsh plugin add` from a git URL works immediately — pnpm has no build to block and no `allowBuilds` entry to add. |
+| **Only `node:` imports** | The host half loads from any profile (web, desktop, headless, TUI) without resolving a single package. |
+| **No model-facing surface** | It registers no prompt section, no message and no tool, so it cannot change a request prefix or hurt KV-cache reuse. |
+| **Fails soft** | Every hook is guarded. A ledger fault logs a warning; it never fails a session. |
+
+## Install
+
+```bash
+# from npm
+dsh plugin --profile web add @chenmiao8563/dsh-token-ledger
+
+# from a git URL (no build step is involved)
+dsh plugin --profile web add github:chenmiao8563/dsh-token-ledger
+
+# from a local checkout
+dsh plugin --profile web add /absolute/path/to/dsh-token-ledger
+```
+
+The npm package is scoped because npm rejects the unscoped name
+`dsh-token-ledger` as too similar to an existing package once separators are
+normalized away. The CLI command is still `dsh-token-ledger`.
+
+Restart DSH, then check the row landed:
+
+```bash
+dsh --profile web --dump-config | grep token-ledger
+```
+
+In the conversation, `/tokens` prints the ledger:
+
+```
+/tokens
+/tokens export     # write CSV + JSON under <DSH_HOME>/token-ledger/exports/
+/tokens json       # the raw snapshot
+/tokens path       # where the ledger file is
+```
+
+The ledger is written to `<DSH_HOME>/token-ledger/ledger.json`.
+
+## Counting rules
+
+The numbers are only useful if you know exactly what they count.
+
+| Rule | Behaviour |
+| --- | --- |
+| **Successful anchors only** | Usage is taken from `assistant/message` (a completed step) and `compaction/summary` (one compaction call). A failed or cancelled attempt never appends either, so it is never counted. |
+| **Streaming samples are replaced, not added** | When a step emits a `usage` chunk and then its final message, the final value replaces the earlier sample — one call either way. |
+| **`totalTokens` is derived** | It is the sum of the four buckets, never the provider's own total field. Across 15,778 real usage reports the two agreed every single time, and deriving it keeps the buckets and the total consistent by construction. |
+| **Reasoning tokens are a subset** | Reported separately, never added into the total, because they are already inside `outputTokens`. |
+| **Local calendar days** | Days are your days, not UTC days. |
+| **Forks are cut, resumes are not** | See below. |
+
+### Forks versus resumes
+
+A stored log can begin with a prefix of history that was already recorded. Two
+different situations produce one, and getting them confused is the most common
+way a usage plugin silently gets the wrong answer:
+
+- **Fork** (`parentSession` set): the prefix is the *parent's* history, counted
+  in the parent's own log. Counting it again here would double count. It is cut.
+- **Resume** (no parent): the prefix is *this session's own* earlier history,
+  stored once. Cutting it would lose tokens. Nothing is cut.
+
+This is not a guess. Against real logs, every forked session whose parent log was
+still present had its pre-marker usage fingerprints contained in the parent's,
+while the non-forked logs carrying the same marker never repeated their prefix
+later in the file. On one real 139-session home the distinction was worth
+79.9 million tokens of double counting that a naive "count every log" pass
+reports.
+
+## CLI
+
+Works without DSH running — it reads the raw logs directly.
+
+```
+dsh-token-ledger [summary] [options]     print the stored ledger (default)
+dsh-token-ledger audit   [options]       recompute from raw logs and diff
+dsh-token-ledger rebuild [options]       recompute from raw logs
+dsh-token-ledger export  [options]       write CSV and JSON exports
+
+--home <path>    DSH home to read (default: $DSH_HOME, else ~/.dsh)
+--ledger <path>  ledger file to read or write
+--out <path>     export destination directory
+--days <n>       days in the summary (default 7)
+--models <n>     models in the summary (default 5)
+--write          with rebuild: replace the stored ledger
+--json           machine-readable output
+--quiet          suppress the human summary, keep the exit code
+```
+
+Exit codes: `0` success or audit match, `1` audit found a real difference,
+`2` bad usage or an unreadable input. That makes it usable as a scheduled check.
+
+### The audit distinguishes two kinds of difference
+
+A running host writes its ledger on a debounce, so a live session is routinely a
+little ahead of the stored file. Reporting that as corruption would make the
+audit useless. The ledger's own `updatedAt` settles it:
+
+- a differing session whose newest event is **newer than the ledger** has simply
+  kept running → *match*, with the unflushed amount reported;
+- a differing session whose newest event **predates the ledger**, or a day/model
+  row that contradicts the fold it should sum to → *mismatch*, exit 1.
+
+```
+  audit: match — 1 session(s) advanced after the ledger was written
+         (1 calls, 5100 tokens not yet flushed)
+```
+
+## Configuration
+
+Override the composition entry by its `id`:
+
+```yaml
+- id: token-ledger
+  config:
+    ledgerPath: 'D:/dsh/ledger.json'   # default: <DSH_HOME>/token-ledger/ledger.json
+    backfill: false                     # default: true — fold stored history on startup
+```
+
+## What it deliberately does not do
+
+- **No pricing.** It counts tokens; turning them into money needs a price
+  catalogue that goes stale. Pair it with a billing plugin if you want money.
+- **No model-facing tool.** A tool schema costs prompt tokens on every request
+  and shifts the cache prefix — a strange thing for a token-accounting plugin to
+  do. `/tokens` and the CLI cover the human cases.
+- **No UI in 0.1.0.** The host half and the CLI are the contract; a browser half
+  is planned for 0.2 as a pure addition.
+
+## Compatibility
+
+- **Node:** ≥ 22.15.0 (the CLI decodes Zstandard frames). The host half itself
+  needs nothing version-specific.
+- **DSH:** verified on `0.1.2-rc.1`. The surface used — `ctx.on`, `ctx.inject`,
+  `ctx.get`, `ctx.effect`, `commands.register`, and
+  `sessionPersistence.list()/inspect()` — is the same across the `0.1.2` line.
+- **Profiles:** any. There is no profile-specific code.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove @chenmiao8563/dsh-token-ledger
+```
+
+The ledger file is left alone on purpose — delete
+`<DSH_HOME>/token-ledger/` yourself to reset the history.
+
+## Development
+
+```bash
+npm test            # 49 tests, no dependencies to install
+npm run verify      # packaging invariants (dependency-free, no install scripts, no bare imports)
+```
+
+`npm test` uses Node's built-in test runner. In a restricted environment where
+spawning a child process per test file is blocked, use
+`npm run test:single-process`.
+
+See [docs/VERIFICATION.md](docs/VERIFICATION.md) for what was actually verified
+and how, including the evidence behind the fork rule.
+
+## Releasing
+
+npm requires two-factor authentication for every publish, so a version's first
+release is interactive:
+
+```bash
+npm login
+npm publish --access public --otp=<six digits from your authenticator>
+```
+
+After that first publish, configure a **Trusted Publisher** for the package on
+npmjs.com (package → Settings → Trusted Publisher → GitHub Actions, repository
+`chenmiao8563/dsh-token-ledger`, workflow `release.yml`). OIDC cannot be set up
+before the package exists, which is why the first release is manual. From then
+on, a tag push publishes with no stored token at all:
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+`release.yml` skips the publish step when the version is already on the
+registry and creates the GitHub release regardless, so re-running it is safe.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,208 @@
+# dsh-token-ledger
+
+为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 提供透明、可审计的 token 记账。
+
+[![CI](https://github.com/chenmiao8563/dsh-token-ledger/actions/workflows/ci.yml/badge.svg)](https://github.com/chenmiao8563/dsh-token-ledger/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@chenmiao8563/dsh-token-ledger.svg)](https://www.npmjs.com/package/@chenmiao8563/dsh-token-ledger)
+[![license](https://img.shields.io/npm/l/dsh-token-ledger.svg)](./LICENSE)
+
+[English](README.md) | 中文
+
+---
+
+## 这是什么
+
+这是一本**账本**，不是一块仪表盘。它把 DSH 的持久会话日志折叠成 token 用量，保证重启不丢，
+而且——这是关键——允许你**从原始日志重算同一批数字并与之对账**。
+
+```
+$ dsh-token-ledger audit
+scanned 139 session log(s), 344203 events, 29 fork(s), 0 unreadable
+
+  stored      6901 calls  1205685663 tokens
+  recomputed  6901 calls  1205685663 tokens
+
+  audit: match — the stored ledger equals a fresh fold of the raw logs
+```
+
+只想看漂亮的图表，市面上有十几个同类插件。这个插件是给你**需要为这个数字辩护**的时候用的。
+
+## 为什么别的插件装不上时它能装上
+
+| 特性 | 为什么重要 |
+| --- | --- |
+| **零依赖、零 peer 依赖** | 没有东西需要解析，DSH 内部包的版本漂移搞不坏安装。 |
+| **零安装脚本** | 直接用 git URL `dsh plugin add` 即可——pnpm 没有构建要拦，你也不必去 `allowBuilds` 里加白名单。 |
+| **只 import `node:`** | 宿主端可以从任意 profile（web / desktop / headless / TUI）加载，不需要解析任何包。 |
+| **不碰模型可见面** | 它不注册任何提示词段、消息或工具，因此不会改变请求前缀，也不会损害 KV cache 复用。 |
+| **故障降级** | 每个钩子都有保护。账本出问题只记一条警告，绝不让会话失败。 |
+
+## 安装
+
+```bash
+# 从 npm
+dsh plugin --profile web add @chenmiao8563/dsh-token-ledger
+
+# 从 git URL（不涉及任何构建步骤）
+dsh plugin --profile web add github:chenmiao8563/dsh-token-ledger
+
+# 从本地仓库
+dsh plugin --profile web add /absolute/path/to/dsh-token-ledger
+```
+
+npm 包名带 scope，是因为 npm 会把分隔符归一化后比较，无 scope 的
+`dsh-token-ledger` 被判为与已有包过于相似而拒绝发布。CLI 命令名仍然是
+`dsh-token-ledger`。
+
+重启 DSH，然后确认那一行进去了：
+
+```bash
+dsh --profile web --dump-config | grep token-ledger
+```
+
+在对话里用 `/tokens`：
+
+```
+/tokens
+/tokens export     # 把 CSV 与 JSON 写到 <DSH_HOME>/token-ledger/exports/
+/tokens json       # 原始快照
+/tokens path       # 账本文件位置
+```
+
+账本写在 `<DSH_HOME>/token-ledger/ledger.json`。
+
+## 计数规则
+
+只有知道它到底在数什么，这些数字才有用。
+
+| 规则 | 行为 |
+| --- | --- |
+| **只认成功锚点** | 用量取自 `assistant/message`（已完成的步）与 `compaction/summary`（一次压缩调用）。失败或被取消的尝试不会追加这两种事件，因此永远不计入。 |
+| **流式样本是替换，不是相加** | 同一步先出 `usage` chunk、后出最终消息时，最终值**替换**早期样本——无论哪种情况都算一次调用。 |
+| **`totalTokens` 是推导出来的** | 它是四个桶之和，绝不采信提供方自己的总量字段。在 15,778 份真实用量报告上两者完全一致，而推导能让桶与总量在构造上永远自洽。 |
+| **推理 token 是子集** | 单独报告，绝不相加进总量，因为它本来就在 `outputTokens` 里面。 |
+| **按本地日历日** | 是你所在时区的日，不是 UTC 日。 |
+| **fork 切、resume 不切** | 见下。 |
+
+### fork 与 resume 的区别
+
+存储的日志可能以一段"已经记录过的历史"开头。有两种完全不同的情况会产生这种前缀，
+把它们搞混是用量插件静默算错的最常见原因：
+
+- **fork**（有 `parentSession`）：前缀是**父会话**的历史，已经在父会话自己的日志里计过。
+  在这里再计一次就是重复计入——必须切掉。
+- **resume**（没有父会话）：前缀是**这个会话自己**更早的历史，只存了一次。
+  切掉就是漏计——不能切。
+
+这不是猜的。对照真实日志：所有父日志仍在磁盘上的 fork 会话，其边界标记之前的用量指纹
+都包含在父会话里；而带同样标记但没有父会话的日志，其前缀在文件后半段从未重复出现。
+在一个真实的 139 会话 home 上，这个区别意味着 **7,992 万 token** 的重复计入——那是
+"把每个日志都完整计一遍"的天真做法会报出来的数字。
+
+## 命令行
+
+不需要 DSH 在运行——它直接读原始日志。
+
+```
+dsh-token-ledger [summary] [选项]     打印已存账本（默认）
+dsh-token-ledger audit   [选项]       从原始日志重算并对比
+dsh-token-ledger rebuild [选项]       从原始日志重算
+dsh-token-ledger export  [选项]       导出 CSV 与 JSON
+
+--home <path>    DSH home（默认 $DSH_HOME，其次 ~/.dsh）
+--ledger <path>  要读写的账本文件
+--out <path>     导出目录
+--days <n>       摘要显示天数（默认 7）
+--models <n>     摘要显示模型数（默认 5）
+--write          配合 rebuild：覆盖已存账本
+--json           机器可读输出
+--quiet          抑制人类可读摘要，只保留退出码
+```
+
+退出码：`0` 成功或审计通过，`1` 审计发现真实差异，`2` 用法错误或输入不可读。
+因此它可以挂进定时任务。
+
+### 审计能区分两类差异
+
+运行中的宿主是按防抖写入账本的，所以活跃会话比文件"新一点"是常态。
+把这种情况报成数据损坏，审计就废了。账本自己的 `updatedAt` 可以裁决：
+
+- 有差异的会话，其最新事件**比账本更新** → 只是还在跑 → **通过**，并报出尚未落盘的量；
+- 有差异的会话，其最新事件**早于账本**，或者某条日/模型行与它本该汇总的折叠结果矛盾
+  → **不通过**，退出码 1。
+
+```
+  audit: match — 1 session(s) advanced after the ledger was written
+         (1 calls, 5100 tokens not yet flushed)
+```
+
+## 配置
+
+按 `id` 覆盖组合条目：
+
+```yaml
+- id: token-ledger
+  config:
+    ledgerPath: 'D:/dsh/ledger.json'   # 默认 <DSH_HOME>/token-ledger/ledger.json
+    backfill: false                     # 默认 true——启动时折叠已存历史
+```
+
+## 它刻意不做的事
+
+- **不做定价。** 它只数 token；折算成钱需要一份会过期的价目表。要钱就配一个计费插件。
+- **不注册面向模型的工具。** 工具 schema 会在每次请求上花提示词 token 并改变缓存前缀——
+  对一个 token 记账插件来说这很荒唐。人类场景由 `/tokens` 与 CLI 覆盖。
+- **0.1.0 不带 UI。** 宿主端与 CLI 就是契约；浏览器端计划在 0.2 作为纯增量加入。
+
+## 兼容性
+
+- **Node：** ≥ 22.15.0（CLI 需要解码 Zstandard 帧）。宿主端本身没有版本相关要求。
+- **DSH：** 在 `0.1.2-rc.1` 上验证。所用到的接口面——`ctx.on`、`ctx.inject`、`ctx.get`、
+  `ctx.effect`、`commands.register`、`sessionPersistence.list()/inspect()`——在 `0.1.2` 线上一致。
+- **Profile：** 任意。没有 profile 相关代码。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove @chenmiao8563/dsh-token-ledger
+```
+
+账本文件是**故意**不删的——要清空历史请自行删除 `<DSH_HOME>/token-ledger/`。
+
+## 开发
+
+```bash
+npm test            # 49 个测试，无需安装任何依赖
+npm run verify      # 打包不变式（零依赖、无安装脚本、无裸模块说明符）
+```
+
+`npm test` 使用 Node 内置测试运行器。在禁止逐文件 spawn 子进程的受限环境里，
+改用 `npm run test:single-process`。
+
+实际验证了什么、怎么验证的（包括 fork 规则背后的证据）见
+[docs/VERIFICATION.md](docs/VERIFICATION.md)。
+
+## 发布
+
+npm 现在强制每次发布都要 2FA，所以一个版本的首发必须交互式完成：
+
+```bash
+npm login
+npm publish --access public --otp=<认证器里的 6 位数字>
+```
+
+首发之后，在 npmjs.com 上给这个包配 **Trusted Publisher**（包 → Settings →
+Trusted Publisher → GitHub Actions，仓库填 `chenmiao8563/dsh-token-ledger`，
+workflow 填 `release.yml`）。OIDC 没法在包存在之前配置，这就是首发必须手动的
+原因。配好之后，打 tag 即可发布，**不需要存放任何 token**：
+
+```bash
+git tag v0.1.1 && git push origin v0.1.1
+```
+
+`release.yml` 会在版本已存在于 registry 时跳过发布步骤、但仍创建 GitHub
+Release，所以重复运行是安全的。
+
+## 许可证
+
+MIT

package/bin/dsh-token-ledger.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Executable entry point for `dsh-token-ledger`.
+ *
+ * Kept as a thin wrapper so the CLI logic stays importable and testable.
+ *
+ * @module dsh-token-ledger/bin
+ */
+
+import { run } from '../lib/cli.js'
+
+process.exitCode = run(process.argv.slice(2))

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# Bundle patch for `dsh plugin add @chenmiao8563/dsh-token-ledger`.
+#
+# The package is scoped because npm rejects the unscoped name as too similar to
+# an existing package once separators are normalized away. The plugin's Cordis
+# entry id stays `token-ledger`, and the CLI command stays `dsh-token-ledger`.
+#
+# This adds exactly one entry and touches nothing else: no stock component is
+# disabled or replaced, so the ledger can coexist with any other usage,
+# billing or statistics plugin already in the profile.
+#
+# The row's `id` is what a profile-level override would target, e.g.
+#
+#   - id: token-ledger
+#     config:
+#       ledgerPath: /custom/path/ledger.json
+#       backfill: false
+#
+- insert:
+    - id: token-ledger
+      name: '@chenmiao8563/dsh-token-ledger'