v1.4.0

OpenCode Cache Engine v1.4.0

Phase 7 — minimal user-facing observability. Adds a read-only, content-free cache report. No breaking changes.

Changes

• Cache report — node src/cache-report.mjs [--file <path>] (or npm run report). Reads the telemetry JSONL (CACHE_ENGINE_METRICS_FILE, else ~/.cache/opencode/cache-metrics.jsonl) and prints: policy mode · last structural change · first differing section · transformation status · wire verification · provider cache usage · accounting limitations · estimated cost impact. Exit 0 ok / 2 usage-or-unreadable.
• src/cache-report-core.mjs — pure parseReportInput(text) + renderReport(records); imports nothing, no side effects.
• src/cache-report.mjs — thin CLI (--file > env > default; ~ expanded exactly as the recorder does).
• 10 new tests: JSONL parse tolerance · purity/determinism · per-element coverage · unavailable ≠ zero · no ratio without provider data · privacy allow-list · no wire claim · CLI args/paths · CLI exit codes · isolation + a symlinked-entry regression.

Observations

• 0 bytes added to any prompt — the report is never on the request path and is never imported by ./server, ./v2, or ./tui (enforced by an isolation test over every src/ module).
• No prompt/reasoning content, credentials, headers, bodies, or session ids appear (allow-listed fields only).
• Missing is unavailable, never zero; no ratio without provider data with a non-zero denominator; estimates are omitted.
• An applied hook change is never presented as wire verification (wireEffect: "not_observed").

Compatibility

• No breaking changes. ./server, ./v2, ./tui keep their exact meaning; the report is opt-in by invocation.
• No new runtime dependency, no bin, no new exports entry; npm pack ships 11 files.

Notes

• Provider cache metrics appear only when the provider reports them; offline they render unavailable.
• Wire verification is always "not observed" today (the plugin has no wire observer); a future wire-evidence source would surface automatically.
• An interactive ./tui panel remains deferred until the OpenCode TUI-panel API is verified.

Full Changelog: v1.3.0...v1.4.0

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.3.0

OpenCode Cache Engine v1.3.0

Phase 5 — usage accounting & telemetry. Additive telemetry, tests, and documentation; no request behavior change. Accounting stays best-effort (never exactly-once).

Changes

• stage on every record — observation | decision | applied | outcome | error — plus wireEffect: "not_observed" on applied records, so a consumer cannot read an applied hook-object change as a wire effect or a provider outcome.
• cache-options: keyInjected / keyPreserved (V1+V2) and optionsInjected (V1+V2). A V1 once-per-session record that wrote nothing is now stage: "decision", not "applied".
• usage: tokenSource: "provider" (read/write/input are provider-reported; *HitRate/promptTokens are derived).

Documentation

• Per-record metric catalogue (source, meaning, presence, trigger).
• Precise terminology — cache_read_tokens, cache_write_tokens, input_tokens, observed_cache_read_ratio; estimated_cost_delta is not produced (pricing is out of scope).
• Provider-specific formulas, never universalised: generic read/(read+write) · GLM read/(read+write+input) · MiMo cachedTokens/(read+input).
• Under/recount scenarios and a failure-mode matrix (duplicate/missing events, compaction, same-timestamp, eviction, telemetry-write failure); the across-restart recount is documented.

Tests

• 5 new: stage classification; the caching-options no-false-success path; restart/non-durable-cursor; and a privacy guard (no prompt content, reasoning, or credentials in telemetry). npm test 378/0; all four capture-harness suites pass.

Compatibility & breaking changes

• Exports/runtime unchanged: ./server (V1), ./v2 (V2 preview), ./tui.
• No breaking changes — all new fields are additive; existing record kinds and field names are unchanged. Telemetry consumers should tolerate the new fields.

Full Changelog: v1.2.0...v1.3.0

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.2.0

OpenCode Cache Engine v1.2.0

Phase 3 begins — offline volatility-capture groundwork (P3-T1). This is a tooling/documentation release: no runtime request behavior changes — no provider-policy change, no prompt mutation, and stabilizeDate remains experimental and default off.

Changes

• Capture-harness knobs (offline test infrastructure only): OC_CAPTURE_TURNS=<n> (equivalent turns, ≥ 2) and OC_CAPTURE_CONTINUE=1 (one session-continue turn → a subsequent request), with fail-closed validation and hermetic coverage.
• test/fixtures/volatility-shapes.mjs — observed request shapes (request kinds, tool order, pair semantics) for P3-T2…P3-T5.
• docs/phase3-p3t1-capture-groundwork.md — procedure, findings (Q1–Q6), and go/no-go.

Documentation

• RF-OC-040 — request/pair shape: an aux (no-tools) request then a main (12-tool) request per run; the system prompt rides inside messages[0]; equivalent turns byte-identical, session-continue differs only in messages.
• RF-OC-041 — tool order: 11 ASCII-sorted core tools with execute appended after the sort (stable across runs).

Compatibility

• Exports/runtime unchanged: ./server (V1), ./v2 (V2 preview), ./tui.
• Install-by-name verified paths unchanged from 1.1.x (OpenCode 1.18.35 V1 / 2.0.26 V2).

Notes

• No provider/network behavior change; no paid calls.
• stabilizeDate stays experimental / default off (P2-T5).

Full Changelog: v1.1.2...v1.2.0

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.1.2

OpenCode Cache Engine v1.1.2

This release completes P2-T3: it proves — offline, on the serialized provider request — that the experimental date-line relocation (stabilizeDate, added in v1.1.1) actually reaches the wire, and it ships the harness tooling and evidence to keep that verifiable. It is a verification/tooling release: no runtime behavior changes and stabilizeDate remains off by default.

Changes

• New offline wire verifier (verify-date-relocation.mjs) that compares an off/on capture pair on the serialized system content.
• New harness option OC_CAPTURE_ENGINE_CONFIG (inject an inline CacheEngine config into the sandbox) and a hermetic date-relocation suite wired into npm run test:harness.
• New research finding RF-OC-036: a V2 context-hook mutation of a system text part reaches the serialized request (closing the hook→wire gap flagged for system).

Wire evidence (gate G3) — offline, no provider calls

Harness run per model: baseline (transform off) vs candidate (stabilizeDate: true), then compared with verify-date-relocation.mjs. Lengths/offsets are on the temp-root-normalized text.

model	off → on	date offset	(open–close)	Δlen
GLM-5.3	7534 → 7535	6891 → 7267	6996–7289 → 6967–7260	+1
MiMo-V2.6	7538 → 7539	6895 → 7271	7000–7293 → 6971–7264	+1
neutral (control)	7526 → 7526	6883 → 6883	unchanged	0

Checks that must all hold: exactly one anchored date line and one pair; the off date is before , the on date is after ; the date value is unchanged; and — order-sensitively — the text with only the date line's bytes removed is identical apart from at most one separator newline. The date line genuinely moves past the block in the serialized request for GLM/MiMo, while a neutral model is unchanged.

Detailed Changes

• Harness (test/harness/capture/): OC_CAPTURE_ENGINE_CONFIG= writes an inline CacheEngine config to the sandbox ~/.config/opencode/cache-engine.json (invalid JSON is a blocker; it warns if set under a debug path). The verifier reports the compared req-*.json, byte lengths, and date/ offsets.
• Tests: date-relocation.test.sh (hermetic; exit-contract checks for correct relocation, no-relocation, changed value, duplicate date, capture/ subdir layout, multi-file selection, and the temp-root-normalized control) joins npm run test:harness.
• Docs: AGENTS.md documents npm run test:harness and current Phase-2 status; README.md lists the new coverage; the implementation plan's status reflects Phase 2 progress; RF-OC-036 recorded.

Compatibility

• No runtime change: exports are unchanged and the stabilizeDate policy is still default off; enabling it changes only the date-line position for GLM-5.3 / MiMo-V2.6.

Testing

• npm test 368/0; npm run test:harness — all four suites pass (exit-contract, retention, port-parity, date-relocation). package-lock.json untouched.

Limitations / evidence boundary

• G3 is structural (serialized-request) evidence for the tested shim route; provider cache benefit remains unmeasured. Neutral/transform-off is unchanged. Matched sessions and provider-reported metrics are future work (P2-T4, which needs provider-access authorization; P2-T5 then decides promote / keep experimental / reject).

Full Changelog: v1.1.1...v1.1.2

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.1.1

OpenCode Cache Engine v1.1.1

This release lands Phase 2 of the post-1.0.0 plan: it verifies the date-relocation hook shape and implements a content-preserving date-line relocation for GLM-5.3 / MiMo-V2.6 — opt-in and experimental (default off). No provider measurements were made and no cache benefit is claimed.

Changes

• New stabilizeDate policy (GLM-5.3 / MiMo-V2.6), default false — moves the standalone Today's date: … line to the system-prompt tail.
• New core helper relocateVolatileDateLine(text) — byte-preserving, fail-closed.
• New telemetry: additive boundary record reason: "system_date_relocated" (V1 + V2).
• Phase 2 research shipped: RF-OC-035, a hook-shape report, and a shape-fixture corpus; stale <env> relocation notes corrected.

The problem (verified on OpenCode 2.0.26)

The V2 context hook delivers system as four text parts. The daily date is a standalone line (Today's date: Wed Oct 14 2026) that sits outside the <env> block, inside part 2 — so the existing <env> relocation does not move it (and, on 2.0.26, the <env> relocation is itself a within-part no-op because the block is terminal in its part). The date line is therefore the only per-day byte that breaks the cacheable prefix.

Detailed Changes:

Core (src/cache-engine-core.mjs)

• relocateVolatileDateLine(text) → { text, changed }: moves the single standalone date line to the end of its containing text. All non-date bytes are preserved byte-for-byte; at most one separator \n is inserted. The date value/format is never changed and never pinned.
• Fail-closed: no-op for missing / duplicate / malformed / ambiguous dates, for a date inside any <env> block, when the <env> structure is not a single well-formed pair, and when the date is already at the tail.
• New policy flag stabilizeDate (default false) for glm53 and mimo26, controllable independently of stabilizeSystem.

V1 + V2 wiring (src/cache-engine.ts, src/cache-engine-v2.mjs)

• Same families, same content-preserving contract as the <env> relocation. V2 relocates only the single eligible text part and leaves every other part byte-identical; if zero or more than one part is eligible, nothing changes.

Telemetry (additive)

• New boundary record reason: "system_date_relocated" with policy / provider / model when the transform fires. Existing record kinds and fields are unchanged.

Docs & research

• README.md + examples/cache-engine.json document stabilizeDate; AGENTS.md GLM/MiMo invariant updated.
• docs/phase2-date-relocation-hook-shape.md (anchor-per-version report + go/no-go); RF-OC-035 added and RF-OC-033 superseded in docs/research-findings.md; stale reasons corrected in the plan and the v2 record.
• Offline capture harness gains a OC_CAPTURE_MODEL override (per-model captures).

Compatibility

• No breaking changes. Exports (./server, ./tui, ./v2) and existing telemetry are unchanged; the new transform is off by default and every addition is read-only until enabled.
• When stabilizeDate is enabled, requests for GLM-5.3/MiMo-V2.6 have the date line moved to the tail (the only prompt-byte change).

Testing & audit

• 368 tests pass / 0 fail; npm run test:harness all pass.
• Independent adversarial review → fixes applied: single-<env>-pair guard, label-based ambiguity detection, already-at-tail no-op, exact-byte corpus assertions, multi-part/ambiguity adapter tests, and the system_date_relocated telemetry.

Limitations / evidence boundary

• Default off / experimental. Structurally and offline verified only — no provider requests, so no cache-read/write benefit is measured or claimed (deferred to P2-T4).
• The date matcher is intentionally narrow (OpenCode's Today's date: template); a format change makes it a safe no-op.

Full Changelog: v1.1.0...v1.1.1

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.1.0

OpenCode Cache Engine v1.1.0

This release completes Phase 1 of the post-1.0.0 plan: detect and explain system-prompt volatility without changing request behavior, add the corresponding telemetry, and ship a reusable offline harness for comparing serialized requests. It is diagnostics-only — no cache-policy or request-mutation changes.

Highlights

• New read-only silent-invalidator linter for system text.
• New first-difference primitive and a baseline-relative systemStablePrefixLength telemetry field.
• A system_volatility boundary event, emitted once per high-severity state transition.
• Full V1 + V2 integration with bounded, per-session dedup (V2 no longer allocates session state for neutral/unknown models).
• A reusable offline/mock capture harness with a documented 0/1/2 exit contract, now runnable via npm run test:harness.

Core diagnostics (src/cache-engine-core.mjs)

• firstSystemDifference(baseline, current) — byte offset of the first difference plus before/after lengths (empty-, equal-, prefix-, insertion-, deletion-, and reorder-safe).
• lintSystemVolatility(parts, tools, options) — advisory, pure, never rewrites. Rules and severities:
  • high — VOL-TIMESTAMP, VOL-SESSION-ID, VOL-TOOL-SET
  • medium — VOL-TOOL-ORDER (implemented); VOL-CONDITIONAL, VOL-NONDET-JSON, VOL-DYNAMIC-BEFORE-STABLE are reserved and intentionally not emitted (a single snapshot cannot detect them reliably)
  • info (allow-listed) — VOL-DATE, VOL-CWD-PATH
• effectiveSeverity() pins allow-listed rules to info regardless of their default, so an expected-volatility finding can never trigger a high-severity signal.
• volatilitySignature() / volatilityTransition() — deterministic, content-free dedup (sorted, unique rule IDs).
• Session-ID detection keeps ses_…/UUID forms high, and only treats a bare 32-hex token as a finding when session context is adjacent (avoids flagging stable hashes).
• systemShapeHashes() now also returns stablePrefixLength.

V1 runtime (src/cache-engine.ts)

• Lints the post-relocation system text (guarded; a diagnostic failure can never break a request).
• Emits one boundary record with reason: "system_volatility" per transition into a high state (never every turn).
• Persists systemStablePrefixLength on prefix-observation and prefix-change.

V2 runtime (src/cache-engine-v2.mjs)

• Lints every family (including neutral/unknown), using a dedicated bounded lintSigs map so neutral models never allocate or refresh main session state.
• system_volatility records carry provider/model when available (omitted, not empty-string placeholders, otherwise).
• lintSigs is cleared on session deletion and cleanup.

New telemetry (consumer note)

Additive only — existing record kinds and fields are unchanged:

• systemStablePrefixLength — byte length of the stable prefix, i.e. the first-differing byte offset relative to the session baseline system text (not the previous observation, not a raw wire offset).
• boundary reason system_volatility — severity: "high" and rules: [...] (sorted high-severity rule IDs only; no prompt content). Emitted by both V1 and V2.

Consumers that enumerate boundary reasons or assume a fixed prefix-* field set may need to accommodate these additions.

Offline capture harness (test/harness/capture/)

Reusable, isolated two-request capture and structural diff:

• run.sh (orchestrator) → inner.sh (sandboxed turns) → mock-provider.mjs (loopback-only mock) → decide.sh/diff-requests.mjs.
• bwrap --unshare-net, private HOME/XDG, per-turn timeout, fail-closed temp root, retention via prune.sh; no unisolated fallback.
• Documented exit contract: 0 identical/expected, 1 unexpected structural difference, 2 blocker/invalid input.
• Run it: npm run test:harness (exit-contract + retention + port-parity). npm test is unchanged.

This harness proves structural equivalence of two equivalent mock requests; it is verification infrastructure and does not itself demonstrate any provider-side cache benefit.

Documentation

• Phase 1 marked COMPLETE in docs/opencode-cache-engine-v1.x.x-implementation-plan.md and AGENTS.md (Phase 2 — date relocation — is not started and remains gated on provider-side rollover evidence).
• docs/research-findings.md now notes that the competitor research report is gitignored/local-only and that the tracked plan holds its distilled conclusions.
• baseline-report-*.md is gitignored (local-only), alongside audit-report-*.md.

Compatibility & testing

• No breaking changes: exports (./server, ./tui, ./v2) and existing telemetry record kinds/fields are unchanged; all diagnostic additions are read-only.
• 362 tests pass / 0 fail; npm run test:harness passes; git diff --check clean; package packs 9 files.

Limitations / evidence boundary

• Diagnostics are structurally verified and offline/mock verified; no provider calls were made and no cache-read/write metrics or cache-stability improvement are measured or claimed.
• Usage accounting remains best-effort (not exactly-once).
• Reserved linter rules are deliberately not emitted.

Full Changelog: v1.0.1...v1.1.0

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and offline-tested; isolated shim-based loading, setup, and hook registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime, but managed-config discovery/registration remain unverified.

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.

The plugin currently has eleven cache-policy families: DeepSeek, GPT-5.6+, GLM-5.3+, MiMo V2.6+, Kimi, Claude, Gemini, Qwen, Grok, Muse, MiniMax

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.0.1

OpenCode Cache Engine release v1.0.1

Changes:

• Bugfix: fixed error with the OpenCode V2 TUI module contract

Detailed Changelog:

• fix(tui): satisfy the OpenCode V2 TUI plugin module contract

Full Changelog: v1.0.0...v1.0.1

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and
  offline-tested; isolated shim-based loading, setup, and hook
  registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime,
  but managed-config discovery/registration remain unverified (and the direct
  plugins: ["opencode-cache-engine/v2"] entry did not resolve in the tested
  offline configuration)

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.

The plugin currently has eleven cache-policy families:

• DeepSeek — passive cache observability; request structure is preserved.
• GPT-5.6 and later — documented cache-key/options metadata, with prompt text unchanged. GPT-6 and future 5.6+/6+/7+ versions resolve through the same documented boundary.
• GLM-5.3 and later — GLM implicit-cache baseline and diagnostics; GLM-5.3 additionally uses a narrow, content-preserving <env> relocation overlay.
• MiMo V2.6 and later — MiMo implicit-cache baseline and diagnostics; MiMo V2.6 Flash/Pro additionally use a narrow content-preserving <env> relocation overlay.
• Kimi — passive Moonshot/Kimi implicit-cache observability; the request is left unchanged. The Anthropic-compatible cache_control route is not implemented.
• Claude (Anthropic) — passive classification and accounting; the request is left unchanged because OpenCode itself applies Anthropic cache_control breakpoints.
• Google Gemini — passive classification and accounting; Gemini 2.5+ provider-managed implicit caching is left untouched. CacheEngine creates no CachedContent resources and injects no Gemini cache-control field.
• Alibaba Qwen — passive classification and accounting; Qwen's provider-managed implicit caching is left untouched on every route. CacheEngine places no explicit block-level cache_control marker and adds no affinity, because the V1 hook cannot reach message content blocks and OpenCode already applies breakpoints on the Qwen Messages routes.
• xAI Grok — passive classification and accounting. Grok caching is automatic on all Grok language models, and direct xAI already receives a stable conversation affinity key from OpenCode itself, so CacheEngine injects no header or key and rewrites nothing.
• Meta Muse — passive classification and accounting. Muse caching is automatic positional prefix caching; Meta's prompt_cache_key must be an application-stable routing hint (never per-session) and prompt_cache_retention is a request-level policy, so CacheEngine injects neither and rewrites nothing.
• MiniMax — passive classification and accounting, route-aware. MiniMax caching is automatic; M2.x additionally supports explicit Anthropic cache_control (M3 does not), but OpenCode already owns those breakpoints on the Anthropic-compatible routes, so CacheEngine injects nothing.

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Installation

V1 (stable):

opencode plugin opencode-cache-engine          # TUI/CLI installer

or set config:

"plugin": ["opencode-cache-engine"]

V2 (preview):

opencode plugin add opencode-cache-engine      # TUI/CLI installer

or set config:

"plugins": ["opencode-cache-engine"]

Both install the package by name, and each runtime selects the interface it supports from the package's ./server export (V1 → server, V2 → setup). Do not pass opencode-cache-engine/v2 as the package specifier; use the bare name.

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v1.0.0

OpenCode Cache Engine release v1.0.0

Dual-runtime release — one package, native support for OpenCode V1 and the OpenCode V2 adapter.

I'm proud to announce the release of the first stable milestone of the project!

After the v0.5.x provider line and the v0.6.0 shared-core consolidation, v1.0.0 ships a single npm package that loads on both OpenCode runtimes, keeps the mature V1 behavior intact, and adds a preview V2 adapter that reuses the same policy resolver and usage/accounting core.

Highlights

• One package, two runtimes: opencode-cache-engine now registers cleanly on OpenCode V1 (1.18.35) and OpenCode V2 (2.0.26) by package name — verified end-to-end in isolated runtimes.
• Dual default entry: ./server exposes both the V1 Plugin and a V2-compatible default object, with a lazy V2 import so V1 never initializes V2 code.
• New ./v2 export — the OpenCode V2 adapter (preview).
• Provider-aware cache stability across 11 model families (10 shipped + neutral fallback), with the shared core extracted for reuse.
• 335 tests, 0 failures.

V2 compatibility:

This is the first release with full V2 compatibility.

The dual-entry model

./server (src/cache-engine.ts) now provides:

• the named CacheEngine (the V1 Plugin), and
• a default object { id, server: CacheEngine, setup(ctx) }, whose setup lazily import("./cache-engine-v2.mjs") and delegates.

V1 selects server(input, options); V2 selects setup(ctx). Package exports: ./server → src/cache-engine.ts, ./tui → src/tui.mjs, ./v2 → src/cache-engine-v2.mjs.

Verified loading (isolated, by package name)

• V1 1.18.35 — opencode plugin -g opencode-cache-engine (writes plugin:["opencode-cache-engine"]) → run executed V1 hooks and emitted V1 telemetry (policy-resolution, prefix-observation, prefix-change, usage), 0 V2-only signals.
• V2 2.0.26 — opencode plugin add opencode-cache-engine (writes plugins:["opencode-cache-engine"]) → run logged loading plugin id=opencode-cache-engine entrypoint=…/src/cache-engine.ts and the V2 adapter produced telemetry.

Important: install by name

• Recommended: opencode-cache-engine (bare name).
• Do not pass a subpath (opencode-cache-engine/v2): the loader reads it as an npm/Git spec and the install fails.

Preview caveats (please read)

• Managed-config discovery/registration of ./v2 remains unverified beyond the isolated shim/name-based tests (project-local shim and by-name install verified).
• GPT cache-key wire carriage — NOT PASS (Gate 4). The adapter mutates the request as designed, but on the tested routes the field could not be attributed to the adapter (the OpenAI-compatible schema strips it; the OpenAI/Azure route is independently pre-populated by the harness).
• OpenRouter header attribution — unverified. Evidence shows preservation/fallback, not that the adapter attached the header in the integration path.
• Usage accounting is best-effort, never exactly-once (volatile events, in-memory cursor, compaction truncation, eviction/mark-expiry edge cases).

Changes

V1 runtime (mature, unchanged behavior)

• Hooks: chat.headers, chat.params, experimental.chat.system.transform, experimental.session.compacting, and friendlier event aggregation on session.idle.
• Provider policies: passive by default, with narrowly scoped, evidence-backed interventions only where a documented benefit exists:
  • GPT‑5.6+ — inject only missing promptCacheKey/promptCacheOptions (implicit, 30m).
  • GLM‑5.3 / MiMo‑V2.6 — the single prompt-text transform: content-preserving relocation of the identifiable <env> block.
  • OpenRouter affinity — deterministic x-session-id for GLM/MiMo only, preserving any existing header.
  • Everything else (DeepSeek, Kimi, Claude, Gemini, Qwen, Grok, Meta Muse, MiniMax) stays loopback-passive and observes provider-reported usage.

V2 runtime (preview adapter)

• ./v2 → src/cache-engine-v2.mjs: a plain { id, setup(ctx) } plugin that reuses the shared policy resolver and usage/accounting core.
• Hooks:
  • context — GPT‑5.6+ missing-field cache key/options; GLM/MiMo structural <env> relocation (now multi-part-aware; it relocates exactly the single eligible system text part and leaves every other part untouched).
  • model.request — OpenRouter x-session-id affinity (guarded; it never duplicates a pre-existing session header).
  • Usage — session.usage.updated (primary) and session.idle (secondary) drive the shared history scan via session.context({ sessionID }), with a bounded per-session model (LRU cap + tombstones + evicted marks), cancellation, and fail-safe error handling.

Verification & evidence

• Unit tests: 335 pass / 0 fail (Node's built-in runner).
• Package: npm pack → 9 files, includes src/cache-engine-v2.mjs (~21 kB).
• Isolated live load test (this release):
  • Tarball opencode-cache-engine-0.7.1.tgz sha256 4103ecb214d4f36c97707160de522f7f94d32ce1dd8566fb3974cc16eb176fa9.
  • Installed src/cache-engine.ts sha256 c449b2655a98362c156c14905ffa636e9ece5d0a4500243e88863390aa727d9e (matched the tarball).
  • V1 1.18.35 and V2 2.0.26 both installed by name from a disposable local registry and loaded/executed the plugin; no real provider traffic.
• Isolation: all tests ran in bubblewrap --unshare-net with private HOME/XDG; the host managed service was never touched.

Detailed changes

Feature diff vs master@34ce537: 10 files, +3473 / −71.

File	Change
src/cache-engine.ts	+36 — dual V1/V2 default entry (lazy V2 import)
src/cache-engine-v2.mjs	new (~505) — V2 adapter
src/cache-engine-core.mjs	+73 — structural <env> eligibility (Platform: required), marker-after-<env> no-op, precise separator-newline contract
test/cache-engine.test.mjs	+1255 — cross-version entry, V2 fault-injection, multi-part relocation, L1/L2, C1 separator regression
package.json	adds ./v2 export; version → 1.0.0
docs/research-findings.md	+913 — RF-OC-017…034 (V2 API/hook/event/usage, loader/CLI, <env> compatibility, separator contract)
docs/implementation-plan-v2.md	+462 — V2 readiness §2B–§2D, Gate 0–4 results, limitations, closure
docs/cache-policy-inventory.md	+6 — GLM/MiMo V2 relocation-compatibility note
README.md	compatibility, installation, quick install (both runtimes), rollback
AGENTS.md	+73 — V2/roadmap guidance

Key commits on the way to 1.0.0: cross-version tests (ac720c5); structural <env> core fix (7b085c6, 4ed1a8f, 36323e7); multi-part V2 relocation (e36d513); V2 surface fault-injection tests (ce31caf); dual entry (947bbdd); C1 clarification (2ab2423, af154f0); docs (8f230c8, 1f0d8b8, 9b6bf56, 0ed32bd, de169fb); merge (0336957); version bump (fc6f6fc); README quick install (b301668).

Known limitations (explicit)

• The V2 adapter is preview, not production: managed-config registration is unproven; GPT wire carriage and OpenRouter header attribution are unresolved; compaction isolation, fork cache-root, and the secondary V1 diagnostics are not ported.
• No exactly-once accounting. Usage is best-effort and can undercount (volatile events, restarts, compaction, eviction); expired marks can recount.
• Loader behavior is version-specific (V1 default-object server selection; V2 ignoring the extra server key) — verified on 1.18.35 / 2.0.26; other versions are not asserted.

Not in this release

No public npm publish or git tag are performed here (the maintainer handles tagging/publishing; postpublish will create and push the v1.0.0 tag). The feature/v2-adapter-checkpoint branch remains available at its pre-merge tip.

Full Changelog: v0.7.1...v1.0.0

---

Thank you to everyone for using the plugin and helping make this project successful!

---

Provider-aware prompt-cache optimization and observability for OpenCode.

opencode-cache-engine is an OpenCode npm plugin that exposes three targets required by OpenCode's installed plugin model:

• ./server — the V1 CacheEngine runtime, hooks, provider policies, and telemetry (verified on OpenCode 1.x).
• ./tui — plugin-manager registration and enable/disable integration; it
  has no CacheEngine-specific UI.
• ./v2 — the OpenCode V2 adapter (preview): implemented and
  offline-tested; isolated shim-based loading, setup, and hook
  registration/dispatch are verified in an isolated OpenCode 2.0.26 runtime,
  but managed-config discovery/registration remain unverified (and the direct
  plugins: ["opencode-cache-engine/v2"] entry did not resolve in the tested
  offline configuration)

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.

The plugin currently has eleven cache-policy families:

• DeepSeek — passive cache observability; request structure is preserved.
• GPT-5.6 and later — documented cache-key/options metadata, with prompt text unchanged. GPT-6 and future 5.6+/6+/7+ versions resolve through the same documented boundary.
• GLM-5.3 and later — GLM implicit-cache baseline and diagnostics; GLM-5.3 additionally uses a narrow, content-preserving <env> relocation overlay.
• MiMo V2.6 and later — MiMo implicit-c...

v0.7.1

v0.7.1 — Session-state lifecycle: cursor/watermark correctness

Fixes a usage-accounting edge where a pruned or reverted message history could cause prompt-cache usage to be double-counted after the message id cursor reset behind an already-counted message.

Changes:

• The lastProcessedAt time watermark is now an absolute "already processed" floor applied on every scan path. Previously it was only applied when the cursor id was missing, so a revert that reset the id cursor behind a counted message re-counted history on restore.
• Minimal, backward-compatible change in src/cache-usage-core.mjs; no provider behaviour, request mutation, cache identity, TTL, telemetry schema, or public export changed.
• Conservative by design: a same-millisecond timestamp tie now undercounts rather than double-counting.

Documentation

• Implementation plan §2B.9 records the full session-state lifecycle contract: state ownership/lifetime (in-memory, per-session, not persisted), message selection/ordering, cursor advancement (non-transactional; normal-scan duplicate prevention vs. no durable exactly-once), pruned/reverted handling, missing/incomplete data, and idempotency/concurrency — plus the remaining unknowns.

Tests (+3; suite 281 → 284)

• Table-driven watermark-floor cases (tie skipped; below-watermark skipped; no-watermark → position decides; missing cursor + no watermark → nothing).
• Composed cursor+watermark prune/revert/restore lifecycle (each message counted exactly once; watermark monotonic).
• Adapter-level session.idle revert/restore probe (no duplicate usage record; forward progress recovers).

Detailed changelog:

• fix(usage): apply the time watermark floor on the located-cursor path
• test: cover the v0.7.1 cursor/watermark revert-restore lifecycle
• docs: record the v0.7.1 session-state lifecycle contract

Full Changelog: v0.7.0...v0.7.1

---

Provider-aware prompt-cache optimization and observability for OpenCode.

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.

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.

The plugin currently has eleven cache-policy families:

• DeepSeek — passive cache observability; request structure is preserved.
• GPT-5.6 and later — documented cache-key/options metadata, with prompt text unchanged. GPT-6 and future 5.6+/6+/7+ versions resolve through the same documented boundary.
• GLM-5.3 and later — GLM implicit-cache baseline and diagnostics; GLM-5.3 additionally uses a narrow, content-preserving <env> relocation overlay.
• MiMo V2.6 and later — MiMo implicit-cache baseline and diagnostics; MiMo V2.6 Flash/Pro additionally use a narrow content-preserving <env> relocation overlay.
• Kimi — passive Moonshot/Kimi implicit-cache observability; the request is left unchanged. The Anthropic-compatible cache_control route is not implemented.
• Claude (Anthropic) — passive classification and accounting; the request is left unchanged because OpenCode itself applies Anthropic cache_control breakpoints.
• Google Gemini — passive classification and accounting; Gemini 2.5+ provider-managed implicit caching is left untouched. CacheEngine creates no CachedContent resources and injects no Gemini cache-control field.
• Alibaba Qwen — passive classification and accounting; Qwen's provider-managed implicit caching is left untouched on every route. CacheEngine places no explicit block-level cache_control marker and adds no affinity, because the V1 hook cannot reach message content blocks and OpenCode already applies breakpoints on the Qwen Messages routes.
• xAI Grok — passive classification and accounting. Grok caching is automatic on all Grok language models, and direct xAI already receives a stable conversation affinity key from OpenCode itself, so CacheEngine injects no header or key and rewrites nothing.
• Meta Muse — passive classification and accounting. Muse caching is automatic positional prefix caching; Meta's prompt_cache_key must be an application-stable routing hint (never per-session) and prompt_cache_retention is a request-level policy, so CacheEngine injects neither and rewrites nothing.
• MiniMax — passive classification and accounting, route-aware. MiniMax caching is automatic; M2.x additionally supports explicit Anthropic cache_control (M3 does not), but OpenCode already owns those breakpoints on the Anthropic-compatible routes, so CacheEngine injects nothing.

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Quick Installation (TUI):

opencode plugin opencode-cache-engine --global

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config

v0.7.0

v0.7.0 — Shared-core / runtime-adapter contract

v0.7.0 makes the boundary between the runtime-independent shared core and the OpenCode V1 adapter explicit and testable. It is a narrowly scoped architecture milestone: no provider behavior changed and no request/telemetry semantics were altered.

Changes

• Audited boundary: cache-policy-core.mjs, cache-engine-core.mjs, and cache-usage-core.mjs import only Node builtins and sibling shared modules — no OpenCode client, hook, routing, or V2 dependency. Only cache-engine.ts (the V1 adapter) registers hooks and calls the client.
• Documented contract (implementation plan §2B.8): policy resolution; shared transformations and identity; usage/accounting; the V1 adapter boundary; fail-closed error/unknown handling.

Tests (+4; suite 277 → 281):

• Shared-core import isolation; adapter hook-registration ownership; full re-export single-definition contract; resolveRuntimePolicy capability-shape contract.
• No source changes were required — the audit found no boundary violation.

Scope

• Does not implement a V2 adapter and does not claim dual-runtime support.
• Session-state lifecycle (v0.7.1) and V2 API verification (v0.7.2+) remain future work.
• No changes to provider policy, request mutation, cache identity, TTLs, or telemetry schema.

Detailed changelog:

• test: add v0.7.0 shared-core/adapter contract tests
• docs: record the v0.7.0 core/adapter contract and reconcile status

Full Changelog: v0.6.0...v0.7.0

---

Provider-aware prompt-cache optimization and observability for OpenCode.

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.

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.

The plugin currently has eleven cache-policy families:

• DeepSeek — passive cache observability; request structure is preserved.
• GPT-5.6 and later — documented cache-key/options metadata, with prompt text unchanged. GPT-6 and future 5.6+/6+/7+ versions resolve through the same documented boundary.
• GLM-5.3 and later — GLM implicit-cache baseline and diagnostics; GLM-5.3 additionally uses a narrow, content-preserving <env> relocation overlay.
• MiMo V2.6 and later — MiMo implicit-cache baseline and diagnostics; MiMo V2.6 Flash/Pro additionally use a narrow content-preserving <env> relocation overlay.
• Kimi — passive Moonshot/Kimi implicit-cache observability; the request is left unchanged. The Anthropic-compatible cache_control route is not implemented.
• Claude (Anthropic) — passive classification and accounting; the request is left unchanged because OpenCode itself applies Anthropic cache_control breakpoints.
• Google Gemini — passive classification and accounting; Gemini 2.5+ provider-managed implicit caching is left untouched. CacheEngine creates no CachedContent resources and injects no Gemini cache-control field.
• Alibaba Qwen — passive classification and accounting; Qwen's provider-managed implicit caching is left untouched on every route. CacheEngine places no explicit block-level cache_control marker and adds no affinity, because the V1 hook cannot reach message content blocks and OpenCode already applies breakpoints on the Qwen Messages routes.
• xAI Grok — passive classification and accounting. Grok caching is automatic on all Grok language models, and direct xAI already receives a stable conversation affinity key from OpenCode itself, so CacheEngine injects no header or key and rewrites nothing.
• Meta Muse — passive classification and accounting. Muse caching is automatic positional prefix caching; Meta's prompt_cache_key must be an application-stable routing hint (never per-session) and prompt_cache_retention is a request-level policy, so CacheEngine injects neither and rewrites nothing.
• MiniMax — passive classification and accounting, route-aware. MiniMax caching is automatic; M2.x additionally supports explicit Anthropic cache_control (M3 does not), but OpenCode already owns those breakpoints on the Anthropic-compatible routes, so CacheEngine injects nothing.

Initial models were personally chosen for their performance in max programming task completed per dollar. More models can be added based on newer releases or updates.

Future releases will be based on newer versions of models from the above providers, as well as any model that performs optimally over the Pareto distribution on OpenRouter as well as on personal discretion. Since cache stability policy doesn't change much for the providers, there's no need for a code rebase.

Quick Installation (TUI):

opencode plugin opencode-cache-engine --global

Best complemented with agents for the particular models configured at AlexJoaquimPereira/opencode-agent-config