npm - token-harness - Versions diffs - 0.1.2 → 0.1.5 - Mend

token-harness 0.1.2 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,51 +1,81 @@
 # Token Harness
-Token Harness has one objective: **reduce the tokens consumed by coding agents without hiding
-useful information or overstating the result**.
+Token Harness has one objective: **maximize the useful coding work you can get from Claude Code
+and Codex usage limits, without hiding quality regressions or pretending that opaque subscription
+quota is exactly equivalent to a token count**.
-Coding sessions repeatedly send test logs, command output, repository context, MCP schemas,
-tool results, and conversation history back to the model. Specialized tools can reduce each of
-those sources, but installing them independently creates a second problem: overlapping hooks,
-double reduction, incompatible configurations, and savings counted more than once.
+The scarce resource is no longer just model context. Subscription users are constrained by rolling
+usage windows, weekly limits, model-dependent burn, long-session context growth, MCP/tool schema
+overhead, noisy tool output, and repeated work after poor model or effort choices. Token Harness is
+evolving from a token-reduction control plane into a **quota-aware efficiency layer** for coding
+harnesses.
-Token Harness is the control plane for that optimization stack. It finds the coding agents and
-token-saving tools on the machine, selects a compatible owner for each interception point, shows
-every proposed change before applying it, verifies whether the integration is genuinely being
-used, and reports how many tokens or characters were saved.
+The product therefore optimizes two related budgets:
-The reduction still happens inside specialized providers such as RTK and HarnessTrim. Token
-Harness makes those providers safe to combine, observable, reversible, and comparable.
+1. **subscription headroom** — observe the usage windows the harness itself exposes, pace work
+   against reset time, and choose native model/effort settings that fit the task and remaining
+   budget;
+2. **context sent to the model** — keep instructions, MCP schemas, conversation history, repository
+   context, and tool output as small as possible without removing information needed to finish the
+   task correctly.
+RTK and HarnessTrim remain useful providers, but reducers are now one layer of the system rather
+than the product definition. Native harness controls come first because choosing the right model,
+effort, context shape, and enabled tools can avoid an expensive turn entirely.
+## What Token Harness should optimize
+| Layer | Target behavior |
+| --- | --- |
+| Usage-window observability | Read five-hour, weekly, model-specific, or credit-backed limits only from surfaces the harness can actually prove; show reset time, headroom, and burn rate |
+| Native model policy | Prefer economical models/effort for routine work, escalate only for tasks whose expected quality benefit justifies the extra quota |
+| Session hygiene | Detect task boundaries, oversized conversations, and stale context; recommend clear/compact/new-session actions before history dominates each turn |
+| Instruction budget | Keep `CLAUDE.md` / `AGENTS.md` concise and hierarchical instead of injecting one large global instruction file everywhere |
+| MCP/tool budget | Disable irrelevant MCP servers, defer schemas where the harness supports it, and expose only the tools required by the current task |
+| Tool-output budget | Reduce logs, diffs, test output, and repeated command results before they re-enter model context |
+| Cross-harness scheduling | When Claude Code and Codex have independent headroom, recommend the harness that can do the task with the best expected quality per remaining quota |
+| Measurement | Correlate quota delta, model/effort, context size, tool traffic, and task outcome; never convert local token savings into an unproven subscription-quota claim |
 ## Optimization ecosystem
-The long-term goal is to coordinate token savings across the whole coding-agent pipeline. Only
-tools marked **active** are integrated in this release; every other row is a candidate and is
-neither installed nor configured by Token Harness.
+The priority order below is deliberately different from the original Token Harness roadmap. A tool
+is high priority only when it helps **included Claude Code/Codex capacity**, not merely API cost,
+provider routing, or benchmark token counts.
-| Tool | Optimization layer | Token Harness status |
+| Tool or surface | Optimization layer | Token Harness direction |
 | --- | --- | --- |
-| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **Active — integrated** |
-| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **Active — integrated** |
-| [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | Not active — candidate |
-| [Lazy MCP](https://github.com/voicetreelab/lazy-mcp) | Load MCP tool schemas only when needed | Not active — candidate |
-| [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | Not active — candidate |
-| [LiteLLM](https://github.com/BerriAI/litellm) | Model routing, fallbacks, budgets, and usage telemetry | Not active — candidate |
-| [RouteLLM](https://github.com/lm-sys/RouteLLM) | Route simpler requests to less expensive models | Not active — candidate |
-| [vLLM Semantic Router](https://github.com/vllm-project/semantic-router) | Route by task, complexity, tools, and deployment locality | Not active — candidate |
-| [Claude Code Router](https://github.com/musistudio/claude-code-router) | Route coding-agent requests across models and providers with effort-based rules and fallback chains | Not active — candidate · high priority |
-| [LLMRouter](https://github.com/ulab-uiuc/LLMRouter) | Select the model by task complexity, cost, and quality across routing strategies | Not active — candidate · high priority |
-| [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | Not active — candidate |
-| [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool results outside model context | Not active — candidate |
-| [LLMLingua](https://github.com/microsoft/LLMLingua) | Compress long prompts and context | Not active — candidate |
-| [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | Not active — candidate |
-Candidate status means only that the project has identified a useful optimization layer. A tool
-becomes active only after its installation, conflicts, rollback behavior, verification, and
-metrics attribution have been implemented and tested. Token Harness never installs a candidate
-merely because it is present on the machine. Rows marked `high priority` are the next intended
-intake; the admission gates each one carries are recorded in
+| **Claude Code native controls** | Usage status, model/effort choice, context inspection, clear/compact lifecycle | **P0 — build into core**. Prefer native surfaces over third-party credential scraping; discover available models dynamically |
+| **Codex native app-server + profiles** | Structured rate-limit telemetry; model, reasoning effort, verbosity, tool-output and MCP/context controls | **P0 — build into core**. `account/rateLimits/read` is the preferred live quota source when available |
+| [cclimits](https://github.com/cruzanstx/cclimits) | Live/local quota companion across coding tools | **P0 — optional observational companion for Claude**. Token Harness uses only cacheless Claude JSON mode, never reads its credentials, and labels the result `reported` or `cached`. Codex keeps its native app-server reader |
+| [ccusage](https://github.com/ccusage/ccusage) | Local historical token/session/cost analytics for Claude Code and Codex | **P0 — high-priority read-only companion**. Useful for history and baselines; not a substitute for live subscription-limit telemetry |
+| [RTK](https://github.com/rtk-ai/rtk) | Shell-command rewriting and command-output reduction | **P1 — active, keep**. Reduces context that would otherwise be resent on later turns |
+| [HarnessTrim](https://github.com/giuliastro/HarnessTrim) | Deterministic reducers, harness adapters, skills, pipes, and MCP reduction | **P1 — active, keep**. Continue only on proven non-overlapping surfaces |
+| [Lazy MCP](https://gitlab.com/gitlab-org/ai/lazy-mcp) | Load MCP tool schemas only when needed | **P1 — high priority**. Directly attacks schema/context overhead; benchmark against native Codex tool deferral before installing another owner |
+| [Context Mode](https://github.com/mksglu/context-mode) | Keep raw tool/MCP results outside model context | **P2 — alternative broad context owner**. Evaluate against Headroom, not alongside overlapping reducers by default |
+| [Headroom](https://github.com/headroomlabs-ai/headroom) | Compress tool, MCP, file, and RAG payloads | **P2 — alternative broad context owner**. Admit only after pair-specific quality and attribution fixtures |
+| [Dejavu](https://github.com/Salnika/dejavu) | Emit only the delta when command output repeats | **P2 — useful for test/rerun loops** after the normal output-reduction path is measured |
+| [repowise](https://github.com/repowise-dev/repowise) | Retrieve task-specific repository context | **P2 — conditional**. Its MCP overhead must be lower than the repository context it avoids |
+| LiteLLM, Claude Code Router, RouteLLM, LLMRouter, vLLM Semantic Router | Route requests across models/providers | **P3 — overflow/API routing only**. Useful after included quota is exhausted or for explicit external-provider policy; not a core subscription-quota optimizer |
+| [LLMLingua](https://github.com/microsoft/LLMLingua) | Generic prompt compression | **Research only** until a harness-aware lifecycle proves must-keep recall and quality |
+| [Caveman](https://github.com/JuliusBrussee/caveman) | Reduce visible model-output verbosity | **De-prioritized**. Use native verbosity/effort controls first and measure their effect before adding another instruction owner |
+Candidate status still means that Token Harness neither installs nor configures the tool until its
+installation, conflicts, rollback behavior, verification, quality gates, and metrics attribution are
+implemented and tested. The intake evidence lives in
 [docs/provider-landscape.md](docs/provider-landscape.md).
+### Why generic routers moved down
+The original roadmap treated model routers as high priority. For the new objective that is backwards:
+a router can reduce API cost by sending work to another provider while consuming **none of the
+included Claude Code or Codex allowance**, or it can bypass subscription authentication entirely.
+That can be valuable as explicit overflow, but it does not demonstrate better use of the allowance
+the user already paid for.
+Token Harness should first exploit the harness-native choices that are actually inside the plan:
+model tier, reasoning effort, verbosity, session lifecycle, instruction size, MCP exposure, and tool
+output. External routing becomes an opt-in second budget, never an invisible shortcut.
 ## Quick start
 Install the CLI:
@@ -61,15 +91,24 @@ Then run the complete workflow from the project in which you use your coding age
 # 1. Inspect the machine. This does not change agent configuration.
 token-harness doctor
-# 2. Preview every proposed change.
+# 2. Inspect subscription headroom and avoidable context. Still read-only.
+token-harness budget
+token-harness context
+token-harness history --since 7d
+token-harness optimize
+# Optional: Claude live quota can use an already-installed cclimits build that
+# supports --no-cache-write. Token Harness never installs it automatically.
+# 3. Preview every proposed configuration change.
 token-harness plan
-# 3. Apply the reviewed plan. This is the first configuration-changing step.
+# 4. Apply the reviewed plan. This is the first configuration-changing step.
 token-harness apply --yes
-# 4. Restart the coding agent, then run a normal shell command through it.
+# 5. Restart the coding agent, then run a normal shell command through it.
-# 5. Check configuration, real interception evidence, and savings.
+# 6. Check configuration, real interception evidence, and savings.
 token-harness status
 token-harness verify
 token-harness metrics --since 7d
@@ -90,26 +129,41 @@ HarnessTrim, or a coding agent.
 ### Managed compatibility rows
 Token Harness changes a harness configuration only when a reviewed compatibility row covers the
-exact provider version, harness version, platform, and configuration schema. Two rows ship, and each
+exact provider version, harness version, platform, and configuration schema. Three rows ship, and each
 names the recording it stands on:
 | Provider | Harness | Platform | Tested versions | Tier |
 | --- | --- | --- | --- | --- |
 | RTK | Claude Code | Windows | rtk 0.44.0, Claude Code 2.1.220 | `canary` |
 | HarnessTrim | Claude Code | Windows | harnesstrim 0.1.0, Claude Code 2.1.220 | `config-only` |
+| HarnessTrim | Codex | Windows | harnesstrim 0.1.0, Codex 0.146.0 | `config-only` |
 Everything else is refused, and that is the design rather than a gap: `doctor` detects and reports on
 every supported platform, and only the *mutation* is narrower. An uncovered combination exits 9 and
 the diagnostic names what is missing — the reviewed fixture, or the nearest row it does have.
+A live Linux check on 2026-09-02 with Codex 0.152.1 confirmed that boundary: the current row covers
+Codex 0.146.0 on Windows only, so `plan` and `apply --yes` refused with exit 9 and wrote nothing.
+That combination can still be observed and benchmarked with a provider installed through its own
+installer; it is not promoted to managed mutation until a real compatibility fixture is recorded.
 What is not covered today, and why:
 - **macOS and Linux.** No row on either. The recordings a row needs are states of a real machine, and
   a fixture cannot be written from a machine nobody ran. On those platforms `plan` and `apply` refuse;
   install the provider with its own installer and Token Harness will detect, verify, and measure it.
-- **Codex and OpenCode.** Both providers are detected and adopted there, and neither is written:
-  RTK's plan builder produces a Claude-shaped hook list, and HarnessTrim's reviewed write set covers
-  Claude only. A row would admit a mutation that nothing proposes.
+- **OpenCode, and permanently rather than pending.** Both providers are detected, adopted, verified
+  and measured there, and neither is written. RTK reaches OpenCode through a plugin module its own
+  installer places globally, which this build has no action for. HarnessTrim's OpenCode installer
+  writes a plugin wrapper *and runs an npm install*, so a containment boundary covering what it wrote
+  would hold a `node_modules` tree — and that is not a decision deferred for want of a fixture. A
+  dependency tree is not configuration, so it cannot be a reviewed write set; snapshotting it on
+  every apply to keep the rollback honest would be slow and would be restoring upstream's install
+  rather than our change; and excluding it would leave a transaction claiming a reversibility it does
+  not have. So the assignment is not producible, and RFC 0003 is explicit about what that means: a
+  capability the provider has but cannot be asked for is not an assignable capability. OpenCode stays
+  adoption-only by decision.
+- **RTK on Codex.** Not managed, and no row: RTK writes a Claude-shaped hook list and nothing else.
 - **A newer Claude Code.** The range is a single observed version. `2.1.221` reads `unknown-newer` and
   refuses rather than assuming it behaves like `2.1.220`.
@@ -122,21 +176,35 @@ There are three separate layers. Installing one does not automatically provide t
 | Layer | Examples | Who installs it? |
 | --- | --- | --- |
-| Coding agent (harness) | Claude Code, Codex, OpenCode | You, using the agent's official installer |
+| Coding agent (harness) | Claude Code, Codex, OpenCode, Hermes, Pi | You, using the agent's official installer |
 | Token Harness | `token-harness` | You, from npm or this repository |
 | Optimization provider | RTK, HarnessTrim | Both can be installed by Token Harness where a compatibility row covers the combination; otherwise install them with their own installers and Token Harness detects and measures them |
-Token Harness does not install Claude Code, Codex, or OpenCode. Install and run at least one of
+Token Harness does not install Claude Code, Codex, OpenCode, Hermes, or Pi. Install and run at least one of
 them first so that `token-harness doctor` can detect it.
-| Provider | Claude Code | Codex | OpenCode | Installed by Token Harness |
-| --- | --- | --- | --- | --- |
-| RTK | Configure, verify, and measure | Not managed | Detect, adopt, verify, and measure | **Yes**, for the supported Claude Code path |
-| HarnessTrim | Claude skills only; no reducer hook or reduce-pipe instruction | Detect, adopt, verify, and measure | Detect, adopt, verify, and measure | **Yes**, on a covered row — see above |
+| Provider | Claude Code | Codex | OpenCode | Hermes | Pi | Installed by Token Harness |
+| --- | --- | --- | --- | --- | --- | --- |
+| RTK | Configure, verify, and measure | Not managed | Detect, adopt, verify, and measure | Not managed | Not managed | **Yes**, for the supported Claude Code path |
+| HarnessTrim | Claude skills only; no reducer hook or reduce-pipe instruction | Detect, adopt, verify, and measure | Detect, adopt, verify, and measure | Detect, verify, and measure | Detect, verify, and measure | **Yes**, on a covered row — see above |
 "Not managed" does not mean the upstream tool cannot support that agent. It means this release
 does not claim ownership of that integration and will not modify it.
+Hermes is read-only in both directions: the adapter finds the HarnessTrim plugin, reads whether it
+is enabled, and imports the telemetry it writes to `~/.hermes/harnesstrim-metrics.jsonl`, but nothing
+here enables the plugin or restarts the gateway. Enabling it is
+`hermes plugins enable harnesstrim`, and that stays your command to run. No compatibility row ships
+for Hermes because a row is the precondition for a *mutation*, and none is proposed.
+Pi is read-only in both directions too: the adapter finds the HarnessTrim extension module in the
+directories Pi auto-loads (`~/.pi/agent/extensions/` and `<project>/.pi/extensions/`) and verifies
+the configuration, but nothing here installs it, and nothing here can say which mode it runs in —
+the extension defaults to `dryrun` and only `HARNESSTRIM_MODE=active` in Pi's environment makes it
+reduce. Installing it is `harnesstrim install pi --apply`, and that stays your command to run. No
+compatibility row ships for Pi because a row is the precondition for a *mutation*, and none is
+proposed.
 RTK on OpenCode is detected and verified, not written: `rtk init -g --opencode` installs a plugin
 module at `~/.config/opencode/plugins/rtk.ts`, and Token Harness reads that file rather than
 producing it. Note that the plugin is inert under OpenCode Desktop — see

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "token-harness",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "One control plane for token-efficient coding agents.",
   "license": "Apache-2.0",
   "type": "module",

package/sbom.json CHANGED Viewed

@@ -1,13 +1,14 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
+  "serialNumber": "urn:uuid:f4cf234e-2ad8-b2a3-a085-7056eb8a17c4",
   "version": 1,
   "metadata": {
     "component": {
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.2",
+      "version": "0.1.5",
       "description": "One control plane for token-efficient coding agents.",
       "licenses": [
         {
@@ -19,7 +20,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8e2f96efbb15fd8aec72a98ae3b62d128265abd779e9f911c8c0d4bf024adfb2"
+          "content": "f4cf234e2ad8b2a3a0857056eb8a17c494730c3d5c11e702edc98b270f18d203"
         }
       ]
     },