dsh-tokeneconomizer
DiscoveredCache-weighted cost accounting, repository facts and evidence-driven tool pruning for DeepSeek Harness (native TypeScript port of TokenEconomizer)
dsh-tokeneconomizer
Three small DeepSeek Harness components that make an agent spend fewer tokens on
the same work. They are native Cordis plugins, not a port of a script: each one
plugs into the harness's own typed events, so there is no shell wrapper, no
subprocess, no fail-open JSON dance, and no editing of another tool's settings
files.
The ideas come from microsoft/TokenEconomizer
(arXiv:2610.22732, Apache-2.0), which built the same three mechanisms
out-of-process for Claude Code, Codex and Copilot CLI. See NOTICE for the
attribution. This repository is an independent TypeScript implementation of
three of its mechanisms against a plugin API TokenEconomizer did not have.
Install
From the npm registry (0.1.0 and later):
dsh plugin --profile <profile> add @sonettogu14/dsh-te # all three
dsh plugin --profile <profile> add @sonettogu14/dsh-te-cost # or one at a time
From a checkout, build once first: a link: install links sources and keeps
their node_modules, but it does not run the build for you, and the packages
resolve their entry points from lib/.
pnpm install
pnpm build # tsc -b -> packages/*/lib
Then install the component, or components, into a profile. One component, on its own — that is a supported way to use this:
dsh plugin --profile <profile> add link:<repo>/packages/cost
All three at once, through the bundle:
dsh plugin --profile <profile> add link:<repo>/packages/bundle
dsh plugin add appends the package to dsh.profile.bundles in that profile's
package.json because every package declares dsh.bundle.patch. Confirm with:
dsh --profile <profile> --dump-config | grep -A2 "== @sonettogu14"
Set enabled: false in the row's config to keep a component installed but
dormant.
Maintainer release, once the version is bumped in packages/*/package.json:
pnpm release:dry # build + `pnpm -r publish --dry-run`, packs all five
pnpm release # build + `pnpm -r publish --access public --no-git-checks`
prepublishOnly builds each package, files ships lib/, and pnpm rewrites
the intra-workspace workspace:* dependencies to the published versions. The components have no dependency on each other: cost, facts and
prune depend only on @sonettogu14/dsh-te-core, and the one cross-component
interaction (facts reporting its own injected tokens to cost) is a soft,
optional lookup — lose the ledger and facts still work.
The components
@sonettogu14/dsh-te-cost — cache-weighted accounting
Raw token totals mislead, because most input tokens are cache reads billed at a
fraction of a fresh input token. This component folds the harness's own four
disjoint provider buckets (uncachedInput, cacheRead, cacheWrite, output)
into a single number that is unit-free: equivalent fresh-input tokens, using
the provider's real price ratios.
- Watches
session/event(request/header,assistant/message), never touches the prompt or the tool surface. - Keeps a per-session view and a per-repository ledger in
$DSH_HOME/dsh-tokeneconomizer/repos/<key>/cost.json. - Counts the components' own spending:
recordOverhead(session, label, tokens)puts injected text on the same books, so a saving cannot be manufactured by moving cost into the plugin. /te-cost [session|repo]prints the breakdown.
Unknown models fall back to a default weight table, recorded as
weightsSource: 'default' rather than failing: a plugin must never be able to
break a session over a price table.
@sonettogu14/dsh-te-facts — repository facts, learned and retired
Watches shell calls; when a session ends, a form that failed here plus a
different form of the same intent that then worked is one fact (an
env_value repair is the second family). Facts are scoped to one repository
(git origin remote, else the working directory).
A fact is not shown because it was observed. It is promoted only after three separate sessions confirm it, and injected only while the waste it prevents is still happening in at least 40% of the sessions that exercised it, measured over at least four such sessions. When the model stops repeating the mistake, the fact stops being injected — and a later session that contradicts it retires it.
- Injects through the logged pre-step channel: one extra user-role message at the first step of a session, nothing at all when no fact qualifies, capped at 4 facts / 600 characters.
- Stores the repair itself — the failing and working command forms of one intent, plus environment variable names. Never file contents, never output text.
/te-factslists what it knows, with state, score and firing rate.
Ported constants: K_PROMOTE=3, GAMMA=0.8, LAMBDA=5.0, FIRE_GATE=0.40,
FIRE_MIN_N=4.
@sonettogu14/dsh-te-prune — stop sending tools nobody calls
Every tool definition rides along on every request. This component counts, per
repository, how many sessions a tool has gone unused; after idleSessions
(default 5) it hides the tool with the registry's own scoped restriction, which
is lifted when the session ends.
- Off by default, and deliberately so: the tool set is part of the cached request prefix, so hiding tools changes what the provider can reuse. The decision is made once at session start and held for the whole session, which keeps the prefix stable inside a session.
- Never hides the harness basics (shell, edit, read, subagents, jobs, …), and
maxHiddenbounds the damage to 8 tools per session. /te-pruneshows idle counters;/te-prune restoregives tools back and records them as permanently kept.
Configuration
Each component takes a small Config; the profile's patch row is the place to
set it:
- id: te-facts
name: '@sonettogu14/dsh-te-facts'
config:
enabled: true
maxFacts: 4
maxChars: 600
| Component | Setting | Default | Meaning |
|---|---|---|---|
| cost | enabled, persist | true, true | fold usage, write the repo ledger |
| facts | enabled | true | watch, learn, inject |
| facts | maxFacts, maxChars | 4, 600 | injection budget |
| prune | enabled | false | hiding is opt-in |
| prune | idleSessions, maxHidden | 5, 8 | when to hide, how many |
| prune | protected | [] | extra names never to hide |
State lives in $DSH_HOME/dsh-tokeneconomizer/ (default ~/.dsh/), partitioned
by repository key. Writes are atomic (tmp + rename), reads never throw.
Verification
pnpm build # tsc -b over the four source packages
pnpm typecheck # tsc -p tsconfig.test.json, includes all tests
pnpm test # vitest: 113 unit tests
pnpm test:integration # vitest: 8 integration tests against real DSH packages
pnpm verify # all four, in that order
Three levels, from cheapest to most convincing:
Unit tests mount the components in a bare Cordis Context with stubbed
services: cost is fed synthetic session events, facts and prune are driven
through four to six simulated sessions to prove promotion, the firing gate,
two-strike contradiction, idle counting, and that restrictions are lifted again.
Integration tests (test/integration/) are the interesting ones: they load
the real @deepseek-ai/dsh-agent-loop, dsh-llm, dsh-tools,
dsh-session and dsh-tool-executor-native packages, register a scripted
LlmAdapter in place of a provider, and run a genuine agent turn — no network,
no credentials, no model. What they assert is exactly what the components claim:
- cost — the four buckets the fake adapter reports (
100uncached,50cache-read,5cache-write,20output) land incost.jsonunchanged and fold toequivalent: 211.25; two sessions in one repository accumulate. - facts — a qualified fact is present as a
dsh-te-factsmessage in the first model request (not merely in state), and disappears when the fire gate is not met; a real failingpython -m pytestfollowed by a workingpytestin the same session teaches the fact end to end. - prune — an idle tool is absent from the request's
toolNameswhile the registry still knows it (hidden, not unregistered); a tool below the threshold survives;writeis never hidden.
These tests caught a real composition requirement: DSH 0.2.2 refuses to run an agent unless a tool executor is mounted, which a bare event-level test never notices.
Manual, real model — a throwaway profile built from the shipped headless
template with the bundle installed answered a one-word task and exited cleanly:
$ dsh --profile te-headless "Reply with exactly: ok"
ok
That run produced $DSH_HOME/dsh-tokeneconomizer/repos/<key>/cost.json with
equivalent: 9189 for a three-token reply — the fixed prompt and tool
definitions, not the answer, are what a session costs. The same repo after a
second session read:
{"equivalent": 9471.76, "buckets": {"uncachedInput": 9266, "cacheRead": 9088,
"cacheWrite": 0, "output": 6}, "sessions": 2}
18,360 raw tokens against 9,472 equivalent ones: that gap is the whole reason the
ledger folds buckets instead of summing totalTokens. A profile with only
@sonettogu14/dsh-te-cost installed boots the same way, so the components really are
independent.
What no test can prove is the harness-level effect on token spend over many sessions; that needs the plugins left on in real work.
What was deliberately not ported
- Loop guard / spiral intervention. TokenEconomizer's own docs say it was
only validated on seeded loops, never on a real spiral, and DSH already ships
dsh-repeat-tool-reminder. Porting an unvalidated heuristic that can spend model calls to interrupt a turn is not a good trade here. - Context compaction, ¥ spend panel. Already covered by
dsh-compaction*and@linxin666/dsh-usage; duplicating them would only add overhead. - The LLM proposer and the other four fact families (
boundary,arg_repair,absent_tool,empty_probe). They are where TokenEconomizer's extra model calls live; the mechanical two-family core is the cheap 80%. - A Python sidecar. The target harness is TypeScript and in-process; a second runtime would add a process boundary for nothing.
Evidence status
TokenEconomizer's headline numbers (18–31% cheaper on SWE-Bench, 16–21% on
Web-Bench) exist in that repository only as constants in
docs/assets/results_overview.py, covering the paper's Table 1; the repository
ships no run results and says so in that file. They are a reason to try these
mechanisms, not evidence that this port inherits them. What is verifiable here is
narrow and stated above: the arithmetic is exact, the lifecycle gates behave as
specified, and nothing the components do can alter the agent's transcript except
one bounded fact block at session start.
Layout
packages/core/ pure logic: pricing weights, bucket folding, fact lifecycle,
shell-transcript extraction, repo identity, atomic storage.
No Cordis dependency; unit-tested in isolation.
packages/cost/ ledger service + /te-cost
packages/facts/ fact watcher + pre-step injection + /te-facts
packages/prune/ idle counters + scoped tool restrictions + /te-prune
packages/bundle/ the install-all patch
Citation and license
The mechanisms implemented here come from this paper; cite it if you use them:
@misc{li2026tokeneconomizer,
title = {{TokenEconomizer}: Experience-Driven Black-Box Cost Control for Coding Agents},
author = {Li, Aaron J. and Xu, Weijia and Singh, Chandan and Chen, Zixiao and
Inala, Jeevana Priya and Siska, Charlotte and Tamersoy, Acar and Yu, Bin and
Stoica, Ion and Galley, Michel and Gao, Jianfeng},
year = {2026},
eprint = {2610.22732},
archivePrefix = {arXiv},
primaryClass = {cs.CL},
url = {https://arxiv.org/abs/2610.22732}
}
This project is licensed under the Apache License, Version 2.0; see
LICENSE. It is an independent implementation of mechanisms from
microsoft/TokenEconomizer
(Apache-2.0, Copyright (c) Microsoft Corporation and contributors); no source
file was copied verbatim. NOTICE records the attribution and which
parts are derived.
Comments
Loading…
Similar plugins
by kam74515-boop
DeepSeek Harness token usage and estimated cost dashboard
★ 0
MIT
TypeScript
Aug 15, 2026
dsh plugin --profile web add dsh-show-me-how-muchby zhirai-tech
Token cost monitoring, call-efficiency analysis and reversible tool-output caching for DeepSeek Harness.
★ 0
JavaScript
Nov 7, 2026
dsh plugin --profile web add dsh-token-managerby kpl0111
Token-efficient tool-result pruning for DeepSeek Harness: compact previews, targeted recall, and long-session context control.
★ 0
↓ 24/wk
MIT
JavaScript
Aug 16, 2026
dsh plugin --profile web add dsh-context-guardby Snow-ea
Deterministic, recoverable tool-result compression and cache-aware compaction for DeepSeek Harness.
★ 4
↓ 631/wk
MIT
TypeScript
Nov 14, 2026
dsh plugin --profile web add dsh-token-optimizerby dongsheng123132
Evidence-first token cost ledger and budget checks for DeepSeek Harness
★ 2
↓ 64/wk
MIT
JavaScript
Nov 6, 2026
dsh plugin --profile web add dsh-costby shi-YangYang
一款 DeepSeek Harness Token 用量统计与可视化插件,支持跨会话用量汇总、实时统计、历史趋势分析及模型级 Token 消耗追踪。
★ 0
MIT
TypeScript
Nov 10, 2026
dsh plugin --profile web add @shi-yangyang/dsh-token-dashboard