OpenCode Cache Miss Notices

Prompt-cache billing notices in OpenCode's TUI and Web transcripts, ported from pi's showCacheMissNotices.

Cache miss after 7m idle: 45k tokens re-billed (~$0.14)

Compaction: 61k tokens billed (~$0.21)

Install

Requires OpenCode 1.18.30 or later in the 1.x series. This package ships TypeScript source, loaded directly by OpenCode; no build step is needed.

For local development, run bun install in this repository and add its entry point to your opencode.jsonc (replace the path):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "file:///absolute/path/opencode-cache-miss-notices/src/index.ts"
  ]
}

After publishing the package to npm, the entry can instead be "opencode-cache-miss-notices". Installing enables notices. Quit and restart OpenCode after changing plugins or their options.

Optional settings (shown with their defaults):

["opencode-cache-miss-notices", {
  "noiseFloorTokens": 1024,
  "noticeThresholdTokens": 20000,
  "noticeThresholdCost": 0.10,
  "cacheTtlMinutes": 5
}]

The same tuple form works with a file:// entry. Values must be finite, non-negative numbers; unknown option names are rejected.

Behavior

• A request is an assistant message with reported prompt tokens, including billed requests that subsequently fail or are aborted.
• Prompt tokens are fresh input plus cache reads plus cache writes. Re-billed tokens are min(previous prompt, current prompt) − current cache reads.
• The first request after a reset establishes the previous request. Providers that have never reported cache activity since that reset produce no misses.
• Re-billed tokens at or below the noise floor are ignored. A miss earns a notice when either the token threshold or the extra-cost threshold is reached.
• Extra cost is an estimate from OpenCode's model pricing, including context tiers and cache-write premiums. Unknown pricing falls back to token-only detection. It is not an invoice or a claim about subscription charges.
• A provider/model change takes precedence over an idle label. Idle time uses request creation timestamps, matching pi. The TTL only affects the label.
• Each compaction summary gets a cost notice, including reasoning tokens. It resets the previous request and cache reporting, is never a cache miss, and never establishes the next comparison baseline.
• Child sessions get notices in their own transcripts. Notices persist across reloads and travel with shared or forked sessions. Existing requests are read once per session to establish state, but historical notices are not backfilled.

Cache miss notices appear above the response. Compaction costs appear on the preceding compaction marker: attaching them to the summary would let OpenCode include them in a later summary before the plugin can filter them. An invisible companion part preserves empty subagent answers; it and the notice are both removed from model-bound history.

Compatibility

The plugin uses persisted text parts because TUI toasts do not reach the Web UI. It relies on experimental.chat.messages.transform to remove its tagged parts from model-bound history. OpenCode does not honor ignored on assistant text, so removing the plugin leaves existing assistant notices readable by the model. See the design decision.

The v1 plugin SDK lacks part.update; the plugin reuses the supplied client's internal transport for that endpoint, preserving server authentication, directory routing, and in-process requests. This is a version-sensitive integration. A failed operation is logged once at warn; a failed notice write is dropped and never interrupts the request.

OpenCode does not expose pi's dropped-thinking diagnostics or branch summaries to this plugin. Requests without reported prompt tokens cannot be evaluated.

Development

bun install
bun run typecheck
bun test test/detection.test.ts
bun test

Terminology is in CONTEXT.md. Detection is pure in src/detection.ts; src/index.ts handles the OpenCode events and transport; src/notices.ts formats persisted notices. MIT licensed; the detection arithmetic and notice formatting follow pi (copyright Mario Zechner).