[xCentral]

Plugin type

• UI Plugin (interactive MCP App pages via ui.surfaces or _meta.ui.resourceUri)
• Standard plugin (no interactive pages)
• Not applicable (repo-level docs/build/CI only)

Affected plugins: tokencare

Problem solved

Long ZCode sessions accumulate huge tool outputs, re-read unchanged files, and overflow context — inflating cost and degrading quality. TokenCare applies layered, reversible compression: nothing is lost, everything is recoverable from an on-disk vault.

It unifies the ideas of two prior projects with their overlapping parts merged (one ledger, one status surface, one compaction driver) instead of duplicated:

• billion-context — incremental model-driven compression, reversibility, search over compressed context, growth nudges
• dsh-token-optimizer — tool-output triage at birth, duplicate-read elimination, session savings monitoring

Behavior and components

Layer	Mechanism
L0 observe (automatic)	PostToolUse hook records size/hash/path per tool result to a per-session JSONL ledger; outputs >30k chars get a one-line /digest nudge; SessionStart(compact) hook points at the vault after built-in compaction
L1 lossless	/digest spills originals verbatim to <project>/.zcode/tokencare/vault/ and emits structure-aware digests (error → 300-char excerpt, JSON → shape summary, CSV → header+rows, text → head/tail); ledger detects unchanged duplicate reads
L2 lossy	/compress writes a structured summary into the vault and anchors ZCode's built-in /compact (cooperates with, not replaces, host compaction)
recovery / stats	/context-search greps the vault; /token-status reports per-tool token estimates, largest outputs, duplicate-read waste, vault totals, MCP-trim advice

GLM-aware token estimation (CJK ≈ 1 token/char, ASCII ≈ 4 chars/token) and tiered profiles (TOKENCARE_PROFILE=flash|balanced|max, auto-detected from TOKENCARE_MODEL/ZCODE_MODEL/ANTHROPIC_MODEL or the hook payload): flash nudges at 20k chars / ~35–40% pressure, balanced 30k / ~45%, max 40k / ~55%.

Testing

• 45 assertions across two suites executed with a real Node runtime: hook recording, nudge JSON shape, malformed-payload safety, spill digests (text/JSON/CSV/error), search/get/index, stats (human + JSON), duplicate-read detection, post-compact pointer, CJK estimation, profile thresholds, auto-detection, self-gitignore. All pass.
• python scripts/validate.py: OK: 52 plugin(s) validated (includes tokencare).
• Installed locally from a dev marketplace; installed, enabled, slash commands registered (zcode commands list), hooks registered (hookCount: 2 at startup), hook executed against the installed cache path with real Node and verified writing the ledger + nudge. No hook/plugin errors in logs.
• Not run: pnpm build/scripts/build_dist.py full pass on Windows — they fail pre-existing on excalidraw (its bundler emits a Windows-invalid path dist\ui\C:\...); verified identical failure on a pristine checkout. tokencare is not a compiled plugin (no package.json, skipped by build-plugins.mjs).

Version

New plugin, first publication: 0.2.1 (manifest and marketplace entry match).

Dependencies, permissions, side effects

• Runtime dependency: Node.js ≥ 16 on PATH (hooks and vault CLI; zero npm dependencies, stdlib only). Degrades gracefully without it — hooks fail silently, sessions are never blocked.
• Writes only to <project>/.zcode/tokencare/ (ledger + vault, self-gitignored). No network access, no secrets, no machine-specific paths, no prebuilt artifacts.

Licensing / provenance

MIT (LICENSE included). Original code, no third-party code copied. Design inspired by and credited to billion-context (MIT + attribution term — credited with link in README) and dsh-token-optimizer (MIT); both linked in README.md / README_CN.md. Bilingual READMEs included.

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.