token-harness 0.1.1 → 0.1.3

package/README.md

@@ -32,6 +32,8 @@ neither installed nor configured by Token Harness.
 | [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 |
@@ -40,7 +42,9 @@ neither installed nor configured by Token Harness.
 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.
+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
+[docs/provider-landscape.md](docs/provider-landscape.md).
 
 ## Quick start
 
@@ -83,27 +87,85 @@ npx token-harness doctor
 `npx` may download Token Harness into npm's cache, but it does not install or configure RTK,
 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. 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.
+
+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.
+- **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`.
+
+The recordings are under `tests/fixtures/rows/`, one directory per row, each with a README stating
+which stages exist and which do not.
+
 ## How the components fit together
 
 There are three separate layers. Installing one does not automatically provide the others.
 
 | 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 | RTK can be installed by Token Harness; HarnessTrim Claude skills can be installed safely when HarnessTrim 0.0.7 is already available |
+| 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 | 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 | **Yes**, when `harnesstrim 0.0.7` is already installed |
+| 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
+[docs/matrices.md](docs/matrices.md) for what was measured.
+
 The generated compatibility tables, tested version ranges, platform coverage, and known
 limitations are in [docs/matrices.md](docs/matrices.md).
 
@@ -148,13 +210,13 @@ If `corepack` is unavailable, install the pinned package manager with
 
 ### 2. Install or adopt RTK
 
-For the supported managed path, you normally do **not** install RTK yourself:
+When a reviewed compatibility row covers the installed versions, you normally do **not** install RTK yourself:
 
 ```sh
 token-harness plan --harness claude --provider rtk
 ```
 
-If RTK is absent, the plan contains two actions:
+Once a matching compatibility row exists, if RTK is absent, the plan contains two actions:
 
 1. install RTK through the selected package manager;
 2. append one RTK entry to Claude Code's `PreToolUse` hook configuration.
@@ -205,9 +267,9 @@ token-harness doctor --provider rtk
 
 ### 3. Install or adopt HarnessTrim
 
-With HarnessTrim `0.0.7` already on `PATH`, `token-harness plan --harness claude` can install its
-Claude skills without creating the competing Bash hook or reduce-pipe instruction. The planned
-upstream invocation is:
+With HarnessTrim on `PATH`, `token-harness plan --harness claude` can install its Claude skills
+without creating the competing Bash hook or reduce-pipe instruction. The invocation it delegates to
+is:
 
 ```sh
 harnesstrim install claude <project> --apply --no-hook --no-instructions
@@ -234,6 +296,19 @@ conflict instead of guessing an execution order. It never deletes the competing
 HarnessTrim telemetry is opt-in in some adapters. Without a `.harnesstrim/metrics.jsonl` file,
 verification can still inspect configuration, but `metrics` has no HarnessTrim events to import.
 
+From `0.1.0`, HarnessTrim publishes a machine-readable capability declaration: the surfaces it
+intercepts per coding agent, the flags that narrow an install, and the paths each install writes.
+
+```sh
+harnesstrim capabilities
+```
+
+Detection reads that declaration and compares it against the one Token Harness records, so an
+upstream change is reported rather than assumed compatible. A disagreement becomes a
+`provider-capabilities-drift` warning naming both sides. A build older than the command cannot
+answer; Token Harness then falls back to its own recorded declaration and reports nothing, because a
+provider that cannot be asked must still be describable.
+
 ## The recommended operating workflow
 
 ### Step 1: diagnose
@@ -249,7 +324,9 @@ This answers:
 - which agent configuration files exist;
 - which provider is wired to which agent;
 - whether Token Harness owns the integration or merely adopted it;
-- whether a version, configuration file, or tool-family matcher needs attention.
+- whether a version, configuration file, or tool-family matcher needs attention;
+- whether the installed provider's own capability declaration still agrees with the one Token
+  Harness records.
 
 Common states:
 
@@ -369,6 +446,11 @@ The report keeps measurement types and units separate:
 Token counts are never added to character counts, and estimated or counterfactual values are never
 silently merged into an exact total.
 
+The report covers one project: the one `--project` names, or the current directory. An operation a
+provider recorded without a directory belongs to no project and is excluded, with a count reported
+so the difference is reconcilable. When no project identity can be established the report says so
+rather than presenting every project's events as one project's figures.
+
 ## Undoing changes
 
 Choose the command based on what you want to undo:
@@ -492,8 +574,10 @@ Run `token-harness doctor`. The usual causes are:
 - an existing user-managed integration already satisfies the target state;
 - the safe profile excluded an overlapping provider.
 
-RTK is managed only for Claude Code in 0.1.0. A Codex-only or OpenCode-only machine therefore does
-not produce an RTK installation action.
+RTK is written only for Claude Code in 0.1.0. It claims OpenCode too, but the plan builder appends
+a `hooks` entry, which is Claude Code's schema — OpenCode's integration is a plugin module, so an
+OpenCode scope produces no action and the existing installation is adopted instead. A Codex-only
+machine produces no RTK action at all.
 
 ### The plan is blocked by `exclusive-scope-contested`
 
@@ -519,6 +603,23 @@ Check all of the following:
 
 An empty metrics report exits 0 because it is a valid observation, not a command failure.
 
+### `doctor` or `status` reports `provider-capabilities-drift`
+
+The installed provider's own capability declaration no longer agrees with the one Token Harness
+records. The warning names both sides: what the recorded declaration claims, and what the installed
+build reported. Nothing is modified, and the recorded declaration still drives planning.
+
+Three disagreements are reported:
+
+- a coding agent that Token Harness records a capability on is missing from the build's declaration;
+- the reduction surface Token Harness records is absent from the surfaces the build reports;
+- the build no longer covers a reviewed write-set path, or declares a path outside the reviewed
+  containment boundary.
+
+The last one matters most before a delegated install. Rollback restores the reviewed boundary, so a
+path outside it would survive a rollback. Re-review the write set at the installed version, or hold
+at the reviewed one.
+
 ### A newer provider or agent version is reported
 
 The tested ranges record versions actually exercised by this project. A newer version is reported

package/package.json

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

package/sbom.json

@@ -7,7 +7,7 @@
       "type": "application",
       "bom-ref": "token-harness",
       "name": "token-harness",
-      "version": "0.1.1",
+      "version": "0.1.3",
       "description": "One control plane for token-efficient coding agents.",
       "licenses": [
         {
@@ -19,7 +19,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b1b9b3a2ec23b44026974033120fa37ed93567d3286dee9278d4e3d600c9283e"
+          "content": "d28d7044c0215e3471e990732b14275cca61e57a823e7a04a505748be73613c8"
         }
       ]
     },