opencode-cache-engine 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,14 @@
 # OpenCode Cache Engine
 
-Provider-aware prompt-cache optimization and observability for [OpenCode](https://opencode.ai).
+Provider-aware prompt-cache optimization and observability for
+[OpenCode](https://opencode.ai).
+
+`opencode-cache-engine` is an OpenCode npm plugin with two targets:
+
+- **Server target** — the actual cache-engine runtime and provider policies.
+- **TUI target** — registration with OpenCode's TUI plugin manager.
+
+The server target handles cache optimization, prompt-shape diagnostics, compaction handling, and cache telemetry. The TUI target provides the plugin-manager integration and enable/disable state for the TUI-facing plugin entry.
 
 `CacheEngine` is an OpenCode plugin designed for long-running agent sessions where prompt-cache efficiency affects both latency and cost. It keeps the harness conservative for providers whose cache behavior is already automatic, while applying provider-specific optimizations where the provider exposes useful cache controls or where prompt structure can be safely improved.
 
@@ -14,7 +22,6 @@ The central design principle is:
 
 > Optimize the request structure only when there is a clear provider-specific reason to do so. Otherwise, preserve OpenCode's native request behavior and measure what the provider actually reports.
 
----
 
 ## What this plugin does
 
@@ -33,7 +40,6 @@ It:
 
 The plugin deliberately avoids pretending that a local hash is proof of a provider cache hit. Provider-reported token usage remains the authoritative signal.
 
----
 
 # Provider behavior
 
@@ -88,7 +94,6 @@ DeepSeek:
     force cache behavior
 ```
 
----
 
 ## GPT-5.6 Luna
 
@@ -153,7 +158,6 @@ compaction:
 
 This prevents a compaction-specific prompt from sharing the same GPT cache namespace as the normal live-session prompt. The behavior is deterministic and tested explicitly.
 
----
 
 ## GLM-5.3 Flash
 
@@ -219,7 +223,6 @@ It only occurs when:
 
 The plugin does not arbitrarily rearrange unrelated prompt content.
 
----
 
 # Prompt-cache strategy
 
@@ -237,7 +240,6 @@ The plugin is **not** a generic "rewrite every prompt for caching" engine.
 
 It is a provider-aware cache policy engine.
 
----
 
 # System-prompt diagnostics
 
@@ -261,7 +263,6 @@ It does **not** mean:
 
 This distinction is intentional. Provider-reported cache token counts are the authoritative cache signal.
 
----
 
 # Tool-definition diagnostics
 
@@ -294,7 +295,6 @@ This distinction matters because semantic equality and byte-level request equali
 
 The plugin uses these fingerprints for **diagnostics only**. It does not reorder the tools to force a particular fingerprint.
 
----
 
 # Compaction handling
 
@@ -313,7 +313,6 @@ The plugin adds a deterministic continuation template:
 The digest is inserted once per compaction operation using a guard that prevents duplicate insertion if the compaction hook fires multiple times.
 The objective is to provide a deterministic continuation structure rather than generating a different arbitrary cache-affecting block on every compaction.
 
----
 
 # Cache metrics
 
@@ -388,7 +387,6 @@ Telemetry is best-effort.
 
 A failed metrics write must never break an OpenCode request. The recorder catches write failures rather than allowing telemetry failures to affect execution.
 
----
 
 # Metrics examples
 
@@ -447,7 +445,6 @@ Telemetry is intended to answer questions such as:
 * Which provider/model/policy was active?
 * Did the GLM system stabilization actually change the observed prompt shape?
 
----
 
 # Configuration
 
@@ -483,7 +480,6 @@ The default configuration is:
 
 The configuration parser starts from these defaults and applies valid file/environment overrides without mutating the caller's configuration object.
 
----
 
 # Configuration options
 
@@ -535,7 +531,6 @@ Controls whether the deterministic compaction continuation block is inserted.
 
 Controls warning logs for observed prefix-shape changes.
 
----
 
 # DeepSeek configuration
 
@@ -549,7 +544,6 @@ There are intentionally very few settings here.
 
 DeepSeek is treated as the conservative/passive policy.
 
----
 
 # GPT-5.6 configuration
 
@@ -601,7 +595,6 @@ Defaults to:
 
 Existing request options are not overwritten by the plugin.
 
----
 
 # GLM-5.3 configuration
 
@@ -629,7 +622,6 @@ The reasoning instrumentation is intended to identify anomalies such as:
 
 It is diagnostic rather than a reason to rewrite or fabricate reasoning content. The implementation maps these conditions to explicit diagnostic reasons.
 
----
 
 # Model detection
 
@@ -658,7 +650,6 @@ Neutral means:
 no provider-specific request mutation
 ```
 
----
 
 # OpenRouter usage
 
@@ -670,7 +661,6 @@ The plugin does not attempt to compensate for provider switching by rewriting pr
 
 For that reason, a stable provider route is preferable when your goal is to measure and maximize prefix reuse.
 
----
 
 # Architecture
 
@@ -893,14 +883,15 @@ A typical standalone repository can use:
 opencode-cache-engine/
 ├── src/
 │   ├── cache-engine.ts
-│   └── cache-engine-core.mjs
+│   ├── cache-engine-core.mjs
+│   └── tui.mjs
 ├── test/
 │   └── cache-engine.test.mjs
 ├── examples/
 │   └── cache-engine.json
+├── package.json
 ├── README.md
-├── LICENSE
-└── package.json
+└── LICENSE
 ```
 
 The OpenCode plugin export remains:
@@ -925,6 +916,20 @@ without changing the `CacheEngine` export identifier.
 
 Install the plugin into the OpenCode plugins directory according to your OpenCode plugin-loading setup.
 
+`opencode-cache-engine` is distributed as an npm package.
+
+## Server/runtime plugin
+
+Add the package to the OpenCode runtime plugin configuration:
+
+```json
+{
+  "plugin": [
+    "opencode-cache-engine"
+  ]
+}
+```
+
 The runtime entry should expose:
 
 ```ts

package/README_rewritten.md

@@ -0,0 +1,965 @@
+# OpenCode Cache Engine
+
+Provider-aware prompt-cache optimization and observability for [OpenCode](https://opencode.ai).
+
+`opencode-cache-engine` is an OpenCode npm plugin designed for long-running agent sessions where prompt-cache efficiency affects latency, token usage, and total task cost.
+
+The package has two targets:
+
+- **Server target** — the actual cache engine, provider policies, prompt transformations, compaction handling, and telemetry.
+- **TUI target** — registration with OpenCode's TUI plugin manager.
+
+The two targets are intentionally separate. The TUI target does not duplicate the cache-engine implementation.
+
+## Design principle
+
+> Optimize the request structure only when there is a clear provider-specific reason to do so. Otherwise, preserve OpenCode's native request behavior and measure what the provider actually reports.
+
+Local hashes and structural diagnostics describe observed request shape. They are not proof of a provider cache hit or miss. Provider-reported cache-token usage is the authoritative signal.
+
+---
+
+# Provider policies
+
+The current implementation has three cache-policy families.
+
+| Provider | Policy | Prompt text changed? | Cache metadata changed? | Main strategy |
+| --- | --- | --- | --- | --- |
+| DeepSeek V4.1 Flash | Passive | No | No | Preserve stable harness + observe |
+| GPT-5.6 Luna | Active cache control | No | Yes | Stable cache key + cache options |
+| GLM-5.3 Flash | Input-shape optimization | Yes, narrowly | No provider cache key | Isolate volatile system content |
+
+The plugin is intentionally **not** a generic prompt-rewriter. Each provider receives only the behavior justified by its cache model.
+
+---
+
+# What the plugin does
+
+The server target operates at the OpenCode harness level rather than implementing a provider-specific client.
+
+It:
+
+1. Detects the model/provider family in use.
+2. Applies only the policy appropriate for that family.
+3. Observes system-prompt and tool-definition stability.
+4. Records provider-reported cache-token usage.
+5. Adds a deterministic compaction continuation block.
+6. Applies GPT-5.6 cache-control metadata.
+7. Applies the GLM-5.3 volatile-environment relocation.
+8. Records diagnostics that help correlate request-shape changes with provider cache behavior.
+
+Telemetry is best-effort and must never become a dependency of model execution.
+
+---
+
+# DeepSeek V4.1 Flash
+
+## Policy: passive
+
+DeepSeek receives no cache-specific request mutation.
+
+The plugin does not:
+
+- rewrite the system prompt
+- reorder tools
+- modify messages
+- inject cache-control fields
+- inject a prompt-cache key
+- alter provider request options
+
+The DeepSeek branch exists primarily to preserve a stable harness while providing observability around prefix structure and actual cache usage.
+
+The plugin observes:
+
+- system-prompt shape
+- semantic tool definitions
+- wire-order tool definitions
+- prefix changes
+- cache read tokens
+- cache write tokens
+- compaction boundaries
+
+The rule is deliberately simple:
+
+```text
+DeepSeek:
+    preserve request
+    preserve prefix
+    measure cache
+```
+
+rather than attempting to guess or force the provider's cache behavior.
+
+---
+
+# GPT-5.6 Luna
+
+## Policy: active cache control
+
+GPT-5.6 is the current policy that actively injects cache-control request metadata.
+
+The plugin adds, when the corresponding fields are not already present:
+
+```json
+{
+  "promptCacheKey": "<stable-session-key>",
+  "promptCacheOptions": {
+    "mode": "implicit",
+    "ttl": "30m"
+  }
+}
+```
+
+The key is derived from stable OpenCode session identity and is independent of transient request data.
+
+Existing provider-supplied cache options are not overwritten.
+
+## The prompt text is not rewritten
+
+For GPT-5.6:
+
+```text
+system prompt     -> unchanged
+conversation      -> unchanged
+tool definitions  -> unchanged
+
+request metadata  -> cache key/options added
+```
+
+This controls cache behavior without performing prompt surgery.
+
+## Default GPT configuration
+
+```json
+{
+  "promptCacheKey": true,
+  "cacheRootKey": false,
+  "compactionCacheIsolation": true,
+  "reasoningEffortDiagnostics": true,
+  "mode": "implicit",
+  "ttl": "30m"
+}
+```
+
+`cacheRootKey` is disabled by default because the current OpenCode runtime does not expose sufficiently reliable fork lineage for safe cross-fork cache-root inheritance.
+
+## Compaction isolation
+
+Compaction uses a deterministic separate cache-key namespace:
+
+```text
+live session:
+    ses_abc123
+
+compaction:
+    ses_abc123:compact
+```
+
+This prevents compaction-specific cache writes from sharing the normal live-session namespace.
+
+---
+
+# GLM-5.3 Flash
+
+## Policy: input-shape optimization
+
+GLM-5.3 receives the only current prompt-text transformation.
+
+The plugin identifies OpenCode's volatile `<env>` section and moves it to the **tail of the system prompt**.
+
+Conceptually:
+
+```text
+BEFORE
+
+[large stable instructions]
+[volatile environment/date block]
+[more stable instructions]
+```
+
+becomes:
+
+```text
+AFTER
+
+[large stable instructions]
+[more stable instructions]
+[volatile environment/date block]
+```
+
+The environment block's contents are preserved. Only its position changes.
+
+The objective is to isolate volatile information so that a changing date or environment value does not unnecessarily disturb the earlier stable prefix.
+
+## GLM safety constraints
+
+The transformation occurs only when:
+
+- the selected model is GLM-5.3;
+- GLM stabilization is enabled;
+- there is exactly one system string;
+- the expected environment markers exist; and
+- the block can be identified unambiguously.
+
+The plugin does not arbitrarily reorder unrelated system-prompt content.
+
+---
+
+# System-prompt diagnostics
+
+The plugin fingerprints the system prompt to detect structural changes between requests.
+
+Provider-aware diagnostics track:
+
+- full system hash
+- stable system-prefix hash
+- volatile system-suffix hash
+
+The stable/volatile decomposition is based on the longest common prefix against the session baseline.
+
+A changed hash means:
+
+```text
+The observed request bytes changed.
+```
+
+It does **not** mean:
+
+```text
+The provider definitely generated a cache miss.
+```
+
+Provider-reported cache-token usage remains authoritative.
+
+---
+
+# Tool-definition diagnostics
+
+Tool definitions are normalized before fingerprinting.
+
+Runtime-only fields such as object identity, function references, timestamps, and arbitrary runtime metadata are excluded.
+
+The plugin maintains two useful fingerprints:
+
+- **semantic fingerprint** — order-insensitive representation of model-visible tool definitions;
+- **wire-order fingerprint** — order-sensitive diagnostic representation of the closest deterministic pre-wire tool ordering available to the plugin.
+
+These fingerprints are diagnostic only. The plugin does not reorder tools merely to force a particular fingerprint.
+
+---
+
+# Compaction handling
+
+OpenCode sessions eventually undergo compaction as conversation history grows.
+
+The plugin adds a deterministic continuation template:
+
+```text
+## Session digest (cache-stable continuation block)
+- Goal:
+- Decisions made:
+- Pending:
+- Active files:
+```
+
+The digest is inserted once per compaction invocation using a guard that prevents duplicate insertion if the hook fires more than once.
+
+The objective is to provide a deterministic continuation structure rather than generating a different arbitrary cache-affecting block on every compaction.
+
+---
+
+# Cache metrics
+
+The plugin records cache usage from OpenCode assistant-message token data.
+
+At minimum it tracks:
+
+```text
+cache.read
+cache.write
+```
+
+and aggregates those values across the session.
+
+## Generic cache ratio
+
+The core helper reports:
+
+```text
+hit rate = read / (read + write)
+```
+
+This is an accounting metric based on cache read/write tokens.
+
+## GLM prompt-token ratio
+
+For GLM, the implementation additionally calculates:
+
+```text
+read / (read + write + input)
+```
+
+These ratios answer different questions and should not be treated as interchangeable.
+
+---
+
+# Telemetry
+
+Metrics are written as JSONL.
+
+Default metrics path:
+
+```text
+~/.cache/opencode/cache-metrics.jsonl
+```
+
+Default plugin configuration path:
+
+```text
+~/.config/opencode/cache-engine.json
+```
+
+Telemetry is best-effort. A failed metrics write must never break an OpenCode request.
+
+## Example usage record
+
+```json
+{
+  "kind": "usage-event",
+  "sid": "session-id",
+  "ts": 1750000000000,
+  "read": 120000,
+  "write": 3000,
+  "cost": 0.0123,
+  "provider": "z-ai",
+  "model": "glm-5.3-flash",
+  "policy": "glm53"
+}
+```
+
+## Example prefix-change record
+
+```json
+{
+  "kind": "prefix-change",
+  "sid": "session-id",
+  "ts": 1750000000000,
+  "dimensions": [
+    "system"
+  ]
+}
+```
+
+## Example compaction record
+
+```json
+{
+  "kind": "compaction",
+  "sid": "session-id",
+  "ts": 1750000000000,
+  "reason": "compaction",
+  "usageSamples": 7,
+  "cumulative": {
+    "read": 900000,
+    "write": 12000
+  }
+}
+```
+
+Telemetry is intended to answer questions such as:
+
+- Did the system prompt change?
+- Did the tool definitions change?
+- Did cache reads increase?
+- Did cache writes increase?
+- Did a compaction occur?
+- Which provider/model/policy was active?
+- Did provider-specific system stabilization change the observed prompt shape?
+
+---
+
+# Configuration
+
+A representative default configuration is:
+
+```json
+{
+  "enabled": true,
+  "metricsFile": "~/.cache/opencode/cache-metrics.jsonl",
+  "compactTemplate": true,
+  "logPrefixChanges": true,
+  "policies": {
+    "deepseek": {
+      "enabled": true
+    },
+    "gpt56": {
+      "enabled": true,
+      "promptCacheKey": true,
+      "cacheRootKey": false,
+      "compactionCacheIsolation": true,
+      "reasoningEffortDiagnostics": true,
+      "mode": "implicit",
+      "ttl": "30m"
+    },
+    "glm53": {
+      "enabled": true,
+      "stabilizeSystem": true,
+      "preserveThinkingIntegrity": true
+    }
+  }
+}
+```
+
+The configuration parser starts from defaults and applies valid file/environment overrides without mutating the caller's object.
+
+---
+
+# Configuration options
+
+## Global
+
+### `enabled`
+
+Enables or disables the entire server plugin.
+
+### `metricsFile`
+
+Controls where JSONL telemetry is written.
+
+### `compactTemplate`
+
+Controls whether the deterministic compaction continuation block is inserted.
+
+### `logPrefixChanges`
+
+Controls warning logs for observed prefix-shape changes.
+
+## DeepSeek
+
+```json
+"deepseek": {
+  "enabled": true
+}
+```
+
+There are intentionally few DeepSeek settings because the policy is passive.
+
+## GPT-5.6
+
+```json
+"gpt56": {
+  "enabled": true,
+  "promptCacheKey": true,
+  "cacheRootKey": false,
+  "compactionCacheIsolation": true,
+  "reasoningEffortDiagnostics": true,
+  "mode": "implicit",
+  "ttl": "30m"
+}
+```
+
+### `promptCacheKey`
+
+Controls whether the plugin provides a stable session-derived GPT cache key.
+
+### `cacheRootKey`
+
+Controls parent/fork cache-root inheritance. Disabled by default because reliable fork lineage is not currently guaranteed by the runtime.
+
+### `compactionCacheIsolation`
+
+Uses a separate deterministic cache namespace for compaction requests.
+
+### `reasoningEffortDiagnostics`
+
+Tracks GPT reasoning-effort changes for diagnostics.
+
+### `mode`
+
+Defaults to `implicit`.
+
+### `ttl`
+
+Defaults to `30m`.
+
+Existing request options are not overwritten.
+
+## GLM-5.3
+
+```json
+"glm53": {
+  "enabled": true,
+  "stabilizeSystem": true,
+  "preserveThinkingIntegrity": true
+}
+```
+
+### `stabilizeSystem`
+
+Enables relocation of the volatile `<env>` section to the system-prompt tail.
+
+### `preserveThinkingIntegrity`
+
+Enables diagnostic checks around reasoning continuity.
+
+The reasoning instrumentation is diagnostic only. It does not rewrite, fabricate, or reorder reasoning content.
+
+---
+
+# Model detection
+
+The server plugin classifies requests into:
+
+```text
+deepseek
+gpt56
+glm53
+neutral
+```
+
+The detector recognizes provider/model identifiers for the supported policy families.
+
+GPT-5.6 has an additional OpenAI/Azure-context check so a string containing `gpt-5.6` does not automatically cause GPT-specific fields to be sent to an unrelated endpoint.
+
+Unknown models use the neutral policy:
+
+```text
+no provider-specific request mutation
+```
+
+---
+
+# OpenRouter usage
+
+The plugin is compatible with OpenRouter because policy selection is based on the provider/model information exposed by OpenCode.
+
+For cache-sensitive workloads, provider stability is important.
+
+The plugin does not attempt to compensate for provider switching by rewriting prompts. Stable provider routing is preferable when the objective is to preserve reusable prefixes.
+
+---
+
+# Package architecture
+
+`opencode-cache-engine` is an npm package with separate server and TUI targets.
+
+```text
+opencode-cache-engine/
+├── src/
+│   ├── cache-engine.ts
+│   ├── cache-engine-core.mjs
+│   └── tui.mjs
+├── test/
+│   └── cache-engine.test.mjs
+├── examples/
+│   └── cache-engine.json
+├── package.json
+├── README.md
+└── LICENSE
+```
+
+The package exports two OpenCode targets:
+
+```json
+{
+  "exports": {
+    "./server": "./src/cache-engine.ts",
+    "./tui": "./src/tui.mjs"
+  }
+}
+```
+
+## Server target
+
+`./server` points to the actual CacheEngine implementation.
+
+It owns:
+
+- OpenCode server hooks
+- session state
+- provider-policy selection
+- request mutation
+- system-prompt transformation
+- telemetry
+- compaction handling
+
+The implementation exports:
+
+```ts
+export const CacheEngine: Plugin = async ({ client, directory }) => {
+  // ...
+}
+```
+
+The identifier `CacheEngine` is the code export name. It does not determine the npm package name.
+
+## TUI target
+
+`./tui` is a small TUI-only registration module.
+
+Its purpose is to make the npm package discoverable by OpenCode's TUI plugin manager.
+
+The TUI target does not duplicate or contain cache-engine logic.
+
+TUI activation state and server-runtime activation are separate concepts unless an explicit state bridge is implemented.
+
+---
+
+# Installation
+
+## npm package
+
+The package name is:
+
+```text
+opencode-cache-engine
+```
+
+For the normal runtime/release configuration, add the package to the OpenCode server plugin configuration:
+
+```jsonc
+{
+  "plugin": [
+    "opencode-cache-engine"
+  ]
+}
+```
+
+Add the same package to the TUI plugin registry when you want it displayed and managed by the OpenCode TUI plugin manager:
+
+```json
+{
+  "plugin": [
+    "opencode-cache-engine"
+  ],
+  "$schema": "https://www.opencode.ai/tui.json"
+}
+```
+
+The package must expose both server and TUI targets for the TUI registry to accept it.
+
+## No direct local plugin copy
+
+Do not install a second CacheEngine copy by placing `cache-engine.ts` or related source files under:
+
+```text
+~/.config/opencode/plugins/
+```
+
+when using the configured npm package.
+
+A duplicate local copy can cause multiple plugin instances to be loaded from different sources.
+
+---
+
+# Development from Git
+
+The Git repository is the development source of truth.
+
+During active development, work directly in the checkout:
+
+```text
+~/Desktop/opencode-cache-engine/
+```
+
+The development workflow is:
+
+```text
+Git working tree
+      ↓
+unit tests
+      ↓
+OpenCode local development target
+      ↓
+runtime validation
+      ↓
+git commit
+      ↓
+npm release
+```
+
+For local development, the server target can be loaded directly from the Git checkout through OpenCode's local plugin configuration rather than publishing an npm version for every change.
+
+The repository remains the only place where source code is edited.
+
+---
+
+# Testing
+
+## Unit tests
+
+Run the test suite from the repository root:
+
+```bash
+node --test test/cache-engine.test.mjs
+```
+
+The test file imports the pure core module from:
+
+```js
+from "../src/cache-engine-core.mjs"
+```
+
+The tests validate provider-independent and provider-specific logic, including:
+
+- model detection
+- GPT cache-key stability
+- GPT cache-option defaults
+- protection against overwriting existing cache options
+- GLM environment relocation
+- deterministic hashing
+- system-prefix decomposition
+- tool fingerprints
+- reasoning diagnostics
+- compaction isolation
+- cache-hit calculations
+- configuration behavior
+- JSONL telemetry behavior
+
+Runtime behavior is validated separately through actual OpenCode plugin loading.
+
+## Package validation
+
+Before publishing, inspect the package contents:
+
+```bash
+npm pack --dry-run
+```
+
+The package should contain the runtime source and documentation needed by OpenCode, including:
+
+```text
+src/cache-engine.ts
+src/cache-engine-core.mjs
+src/tui.mjs
+package.json
+README.md
+LICENSE
+examples/...
+```
+
+Test the TUI target directly with Node when appropriate:
+
+```bash
+node -e 'import("./src/tui.mjs").then(m => console.log(m.default))'
+```
+
+---
+
+# Design principles
+
+## 1. Provider-specific behavior
+
+Different providers expose different cache mechanisms.
+
+The plugin therefore does not assume that one strategy is optimal everywhere.
+
+## 2. Preserve working behavior
+
+The plugin should not modify a provider's request merely because a mutation is technically possible.
+
+This is especially important for DeepSeek, where the current policy is intentionally passive.
+
+## 3. Measure provider reality
+
+Local hashes are diagnostics.
+
+Provider-reported cache-token counts are authoritative.
+
+The implementation explicitly distinguishes:
+
+```text
+observed prefix change
+```
+
+from:
+
+```text
+confirmed provider cache miss
+```
+
+because the plugin cannot infer the latter reliably from local hashes alone.
+
+## 4. Never overwrite explicit provider configuration
+
+Where GPT cache options already exist, the plugin leaves them alone.
+
+## 5. Keep mutations deterministic
+
+When the plugin transforms a request, the transformation should be:
+
+- narrow
+- deterministic
+- content-preserving where possible
+- provider-specific
+- easy to disable
+
+## 6. Keep telemetry out of the critical path
+
+A metrics failure must not break model execution.
+
+---
+
+# What the plugin does NOT do
+
+The plugin does not:
+
+- invent cache hits;
+- claim a local hash proves a provider cache hit;
+- rewrite DeepSeek prompts;
+- reorder tools merely to force cache reuse;
+- fabricate reasoning;
+- modify conversation history arbitrarily;
+- force explicit GPT cache breakpoints by default;
+- silently overwrite existing GPT cache options;
+- assume every model named `gpt-5.6` is an OpenAI-compatible endpoint; or
+- use fork inheritance unless reliable lineage is available.
+
+---
+
+# Cost optimization philosophy
+
+Cache hit rate is useful, but it is not the only cost metric.
+
+The economic objective is:
+
+```text
+total task cost
+=
+prompt/cache cost
++
+output/reasoning cost
++
+additional requests
+```
+
+A model with a slightly lower cache hit rate can still be cheaper if it completes the task with fewer tokens or fewer model calls.
+
+For that reason, this plugin is primarily an **instrumentation + targeted optimization layer**, not a cache-rate maximizer at any cost.
+
+The preferred evaluation unit is:
+
+```text
+cost per completed task
+```
+
+rather than cache percentage alone.
+
+---
+
+# Operational recommendations
+
+For reliable cache measurements:
+
+1. Keep the provider fixed whenever possible.
+2. Avoid changing unrelated system-prompt content during a benchmark.
+3. Keep tool definitions stable.
+4. Compare equivalent tasks across models.
+5. Record actual provider cache-token counts.
+6. Compare total task cost, not only cache percentage.
+7. Treat compaction as a separate cache boundary when analyzing results.
+8. Avoid interpreting a local prefix hash change as definitive proof of a cache miss.
+
+---
+
+# Troubleshooting
+
+## `there is no TUI target`
+
+This means the npm package does not expose a TUI target that your installed OpenCode version recognizes.
+
+Verify that the package contains a TUI entrypoint and that `package.json` exposes the required `./tui` target.
+
+After changing the package, update/reinstall the npm package and restart OpenCode.
+
+## The old `oc-plugin-caching` still appears
+
+Search all OpenCode configuration and local-plugin locations for the old plugin name:
+
+```bash
+grep -R "oc-plugin-caching" ~/.config/opencode ~/.opencode .opencode 2>/dev/null
+```
+
+Remove the old configuration entry and remove the obsolete local plugin source copy.
+
+## DeepSeek cache rate dropped
+
+First check provider stability and whether OpenCode's system/tool prefix changed.
+
+The plugin does not intentionally mutate DeepSeek request options.
+
+Inspect telemetry for:
+
+```text
+prefix-change
+usage-event
+compaction
+```
+
+A prefix change is a diagnostic signal, not automatic proof of a cache miss.
+
+## GPT-5.6 cache options are missing
+
+Verify that the model is classified as GPT-5.6 and that the endpoint is recognized as OpenAI/Azure-compatible.
+
+Also check whether the outgoing request already supplied its own cache options. Existing settings are intentionally preserved.
+
+## GLM-5.3 prompt is not being changed
+
+The environment relocation only occurs when the plugin can identify the expected block unambiguously.
+
+The relevant block must contain the expected beginning and closing marker, and the system structure must meet the plugin's eligibility rules.
+
+## Metrics file is missing
+
+Telemetry is best-effort.
+
+Check:
+
+```text
+~/.cache/opencode/cache-metrics.jsonl
+```
+
+and verify that the configured parent directory is writable.
+
+---
+
+# Release workflow
+
+The Git repository is the source of truth for development.
+
+A normal release workflow is:
+
+```text
+edit source
+    ↓
+run tests
+    ↓
+run OpenCode runtime validation
+    ↓
+git commit
+    ↓
+bump package version
+    ↓
+npm publish
+    ↓
+use published opencode-cache-engine package
+```
+
+Do not edit the installed npm cache as a substitute for repository development.
+
+---
+
+# Status
+
+The current implementation is intentionally conservative:
+
+```text
+DeepSeek  -> preserve and measure
+GPT-5.6   -> configure cache controls
+GLM-5.3   -> isolate volatile prompt content
+```
+
+That separation is the core design of the project.
+
+The plugin should be evaluated using real provider-reported usage and real task cost rather than assuming that any particular local transformation guarantees a cache hit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Provider-aware prompt-cache optimization and telemetry for OpenCode",
   "keywords": [
@@ -27,6 +27,10 @@
     "example": "examples",
     "test": "test"
   },
+  "exports": {
+    "./server": "./src/cache-engine.ts",
+    "./tui": "./src/tui.mjs"
+  },
   "scripts": {
     "test": "node --test test/cache-engine.test.mjs",
     "postpublish": "VERSION=$(node -p \"require('./package').version\") && TAG=v$VERSION && echo \"Creating git tag $TAG for npm $VERSION\" && git tag $TAG && git push origin $TAG || echo \"Tag $TAG may already exist or push failed; continuing.\"",

package/src/tui.mjs

@@ -0,0 +1,11 @@
+const plugin = {
+  id: "opencode-cache-engine",
+
+  async tui() {
+    // CacheEngine has no TUI UI of its own.
+    // This target exists so the npm package can be registered,
+    // displayed, and enabled/disabled by the OpenCode plugin manager.
+  },
+}
+
+export default plugin