dsh-cost

Evidence-first token cost ledger and budget checks for DeepSeek Harness.

dsh-cost folds the durable DSH session log. It attributes each committed assistant/message.usage record to the active request/header provider/model route, then applies a user-owned price book. Missing usage and missing prices remain explicit: partial evidence never becomes a reassuring fake total.

Install

dsh plugin --profile <name> add github:dongsheng123132/dsh-cost

The bundle mounts two tools:

• dsh_cost_report — durable session cost, route breakdown, evidence completeness, optional budget status, and the current ctx.tokenMeter pressure snapshot.
• dsh_cost_check — explicit fail-open/fail-closed budget decision. It does not claim to intercept future calls automatically.

The same evidence core is available through the bundled stdio MCP server as cost_report and cost_check. MCP accepts only bounded, sanitized usage rows (provider, model, disjoint token buckets, or an explicit missingUsage marker); it rejects prompts, message bodies, credentials and other extra fields. The formal Codex plugin manifest lives at .codex-plugin/plugin.json.

The DSH entry is a namespace plugin (name / inject / apply) with no default export. This preserves both tools and tokenMeter injection through the real Cordis Loader. Structural and plugin smokes fail if a default export is reintroduced.

Price book

Copy prices.example.json, replace the zero placeholders with prices from your own current provider contract, and pass its path as plugin config:

- id: dsh-cost
  name: dsh-cost
  config:
    priceBookFile: C:/absolute/path/prices.json
    defaultBudget: 5

Prices are per million tokens. Input, output, cache-read and cache-write buckets are disjoint. reasoningTokens is informational inside output usage and is not added again.

No vendor prices are baked in: prices change, account discounts differ, and a stale number is worse than an explicit unpriced route.

Offline ledger

dsh-cost --events session-events.json --prices prices.json --budget 5 --fail-closed

Exit code 2 means over budget, or unknown when --fail-closed is active. The events file may be a raw array or an object with an events array.

Evidence boundary

• Cost is computed only from durable assistant/message.usage records.
• Calls without provider usage stay missingUsageCalls.
• Routes absent from the price book stay unpricedCalls.
• A below-budget answer is unknown, not within, while either count is non-zero.
• Current context pressure comes from DSH's own ctx.tokenMeter; it is not confused with lifetime spend.

Verify

npm test
npm run check
npm run smoke:plugin
npm run smoke:mcp

For a built DSH checkout and an isolated Web profile containing this bundle, run DSH_CHECKOUT=/path/to/dsh DSH_HOME=/path/to/isolated-home npm run smoke:web-loader. The smoke starts the real stock Web profile with a bounded, credential-free environment and requires an actual readiness URL. npm run smoke:dsh additionally enumerates and calls both tools through the real DSH ToolRuntime when DSH_CHECKOUT is set.

MIT