opencode-cache-engine 0.2.0 → 0.3.0

package/README_rewritten.md

@@ -1,965 +0,0 @@
-# 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.