Skip to content

v1.3.0

Choose a tag to compare

View all tags
@AlexJoaquimPereira AlexJoaquimPereira released this 15 Oct 16:28
· 56 commits to master since this release
v1.3.0
21afdc2

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

Assets 3
Loading