@toninho09/opencode-cache-scope 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toninho09
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# opencode-cache-scope
+
+An [opencode](https://opencode.ai) plugin that warns you when prompt caching
+breaks mid-session, so you notice a token/cost spike before it surprises you
+in the bill.
+
+It ships two independent pieces:
+
+- **Server plugin** (`index.ts`) — listens to session events and shows a TUI
+  toast the moment the model stops hitting the prompt cache.
+- **TUI sidebar plugin** (`tui-sidebar.tsx`) — an optional always-visible
+  widget showing live cache hit rate / read / write stats for the current
+  session.
+
+You can use either one alone or both together.
+
+## Why
+
+Providers like Anthropic cache your growing conversation context so you only
+pay full price for the *new* tokens on each turn. If something invalidates
+that cache (a system prompt change, a tool definition change, hitting a TTL,
+provider-side issues, etc.), every subsequent turn re-sends the *entire*
+context at full price — often 10-50x more expensive — without any obvious
+signal in the UI. This plugin makes that moment visible.
+
+## Installation
+
+### From npm (recommended)
+
+Add the package name to your `opencode.json` (project-level or global
+`~/.config/opencode/opencode.json`). opencode installs it automatically via
+Bun at startup:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@toninho09/opencode-cache-scope"]
+}
+```
+
+Or with options (see [Configuration](#configuration) below):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["@toninho09/opencode-cache-scope", { "toast": true, "minTokens": 500 }]]
+}
+```
+
+(Optional) Enable the sidebar widget in your `tui.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["@toninho09/opencode-cache-scope/tui"]
+}
+```
+
+### From a local clone
+
+1. Clone or copy this repo somewhere on disk.
+2. Install its dependencies:
+
+   ```bash
+   bun install
+   ```
+
+3. Reference it from your `opencode.json` by path instead of package name:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["/absolute/path/to/opencode-cache-scope"]
+   }
+   ```
+
+4. (Optional) Enable the sidebar widget in your `tui.json`:
+
+   ```json
+   {
+     "$schema": "https://opencode.ai/tui.json",
+     "plugin": ["/absolute/path/to/opencode-cache-scope/tui-sidebar.tsx"]
+   }
+   ```
+
+   The sidebar has peer dependencies (`@opentui/core`, `@opentui/keymap`,
+   `@opentui/solid`) that must be resolvable from the plugin's `node_modules`
+   — running `bun install` in this repo covers that.
+
+## Configuration
+
+The server plugin accepts an options object as the second element of the
+plugin tuple in `opencode.json`:
+
+```json
+"plugin": [["/absolute/path/to/opencode-cache-scope", { "toast": true, "minTokens": 0, "dropThreshold": 0.5 }]]
+```
+
+| Option         | Type      | Default | Description                                                                                                                    |
+| -------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `toast`        | `boolean` | `true`  | Whether to show the toast notification when a cache miss is detected. Set to `false` to silence popups while keeping the plugin loaded (e.g. if you only care about the sidebar stats). |
+| `minTokens`    | `number`  | `0`     | Minimum number of input tokens a miss must involve before it's worth alerting. Applies to both total misses and drop-based misses (see below). Misses below this threshold are ignored entirely (no toast, no state change), so a small miss won't suppress a later, larger miss in the same streak. |
+| `dropThreshold`| `number`  | `0.5`   | Fraction (0-1) of relative drop in hit rate, compared to the previous turn, that counts as a (partial) cache miss even when `cache.read` is still greater than zero. `0.5` means a 50%-or-greater relative drop triggers an alert (e.g. hit rate falling from 90% to 40% is a ~56% relative drop). |
+
+If you pass no options (or omit the tuple entirely and use a plain string
+path), both defaults apply: every cache miss triggers a toast.
+
+## How it works
+
+The plugin tracks per-session state from `message.updated` events on
+assistant messages:
+
+1. **Baseline detection** — it never alerts until the session has proven it
+   supports caching at least once (`cache.read > 0` or `cache.write > 0`).
+   This avoids false alarms on models/providers without cache support.
+2. **Two kinds of miss are detected**, once caching is active for the session:
+   - **Total miss**: `cache.read === 0`. The cache didn't get reused at all
+     this turn.
+   - **Partial miss (percentage drop)**: the turn's hit rate
+     (`cache.read / (cache.read + cache.write + input)`) drops by `dropThreshold` or more
+     *relative to the previous turn's hit rate*, even though `cache.read` is
+     still greater than zero. This catches cases where a chunk of the cached
+     context was invalidated but not the whole thing — e.g. hit rate falling
+     from 90% to 40% between two consecutive turns.
+   Both kinds of miss go through the same downstream logic (dedup, `minTokens`
+   filter, toast).
+3. **Debounced per streak** — only the *first* miss (of either kind) after a
+   normal turn triggers a toast. Consecutive misses don't spam you again. The
+   streak resets as soon as a turn is neither a total miss nor a relative drop
+   from the turn before it — note this compares strictly turn-to-turn, so a
+   sustained-but-stable degraded hit rate (e.g. stuck at 40% after the initial
+   drop) won't re-alert unless it drops further or hits zero.
+4. **Threshold filter** — if `minTokens` is set, a miss (of either kind) is
+   only considered "alert-worthy" once its `input` token count reaches that
+   threshold.
+5. **Streaming-safe** — partial/streaming message updates (no
+   `time.completed`) are ignored; only the final, completed message is
+   evaluated.
+6. **Session cleanup** — state is cleared on `session.deleted` to avoid
+   unbounded memory growth across long-running opencode processes.
+
+### Toast examples
+
+Total miss:
+
+```
+Cache miss
+anthropic/claude-sonnet-4-6: cache broke (~3100 tokens with no cache hit)
+```
+
+Partial miss (percentage drop):
+
+```
+Cache miss
+anthropic/claude-sonnet-4-6: cache broke (hit rate dropped from 99% to 20% (~8000 tokens))
+```
+
+### Sidebar widget
+
+When `tui-sidebar.tsx` is loaded, it renders a small "Usage" block in the
+session sidebar, accumulated across the session's assistant messages:
+
+- `hit rate`
+- cache `read` and cache `write` tokens (with their $ cost)
+- `input` and `output` tokens (with their $ cost)
+- a `total` cost line
+
+Cost per token type is computed locally from each message's model pricing
+(`$ per 1M tokens`), since providers don't return a dollar cost in their API
+responses. This is an approximation: it doesn't reproduce opencode's tiered
+pricing for very large contexts, so the sum of the parts may differ slightly
+from the real cost in that edge case.
+
+The widget only appears once the session has used caching at least once (same
+baseline logic as the server plugin), and it's read-only/passive — it doesn't
+have its own configuration options.
+
+![Sidebar widget showing hit rate, cache read/write, input/output tokens and total cost](cost.png)
+
+## Development
+
+```bash
+bun install
+bun test        # runs index.test.ts
+bunx tsc --noEmit  # type-check
+```
+
+`index.test.ts` covers: no-cache-support models never alert, first
+cache-write doesn't alert, normal reads don't alert, a total miss after a hit
+alerts once, consecutive misses don't repeat, recovery + a new miss alerts
+again, user messages and streaming partials are ignored, session cleanup
+resets state, independent sessions don't interfere, the `toast` / `minTokens`
+/ `dropThreshold` options behave as documented above, a large relative hit
+rate drop alerts even without `cache.read` hitting zero, a small drop below
+the threshold doesn't alert, and a stable (non-worsening) degraded hit rate
+doesn't re-alert on the following turn.
+
+## Requirements
+
+- opencode with plugin support (`@opencode-ai/plugin`).
+- Bun (used for install/tests; the plugin itself runs under opencode's own
+  runtime).
+- For the sidebar: `@opentui/core`, `@opentui/keymap`, `@opentui/solid`
+  (`>=0.3.4`) available in the plugin's dependency tree.

package/index.ts

@@ -0,0 +1,110 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+type SessionCacheState = {
+  // true as soon as the session has had at least one cache.read or cache.write > 0,
+  // i.e. it has proven that the model/session supports caching. Until that
+  // happens, we never alert (covers models without cache support).
+  cacheEverActive: boolean
+  // true while we've already alerted for the current cache miss streak.
+  // Resets to false as soon as the hit rate returns to normal (no total miss
+  // nor large drop), allowing us to alert again if it breaks another time.
+  missing: boolean
+  // Hit rate (cache.read / (cache.read + cache.write + input)) of the last turn processed
+  // after the cache became active. Used as a reference to detect a
+  // percentage drop in the following turn. undefined until the first turn
+  // after the baseline.
+  lastHitRate?: number
+}
+
+export type CacheMissAlertOptions = {
+  // Show the alert toast. Default: true.
+  toast?: boolean
+  // Only alert if the miss involves at least this many input tokens.
+  // Default: 0 (alert on any miss).
+  minTokens?: number
+  // Fraction (0-1) of the hit rate drop, compared to the previous turn,
+  // that already counts as a miss even with cache.read > 0 (partial miss).
+  // Default: 0.5 (a drop of 50% or more). E.g.: hit rate dropping from 90%
+  // to 40% is a ~56% drop -> triggers with the default.
+  dropThreshold?: number
+}
+
+export const CacheMissAlertPlugin: Plugin = async ({ client }, options) => {
+  const opts = options as CacheMissAlertOptions | undefined
+  const toastEnabled = opts?.toast ?? true
+  const minTokens = opts?.minTokens ?? 0
+  const dropThreshold = opts?.dropThreshold ?? 0.5
+
+  const sessions = new Map<string, SessionCacheState>()
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.deleted") {
+        sessions.delete(event.properties.info.id)
+        return
+      }
+
+      if (event.type !== "message.updated") return
+
+      const info = event.properties.info
+      if (info.role !== "assistant") return
+      // Ignore partial streaming updates; only process the final message.
+      if (!info.time?.completed || !info.tokens) return
+
+      const cacheRead = info.tokens.cache?.read ?? 0
+      const cacheWrite = info.tokens.cache?.write ?? 0
+      const input = info.tokens.input ?? 0
+
+      let state = sessions.get(info.sessionID)
+      if (!state) {
+        state = { cacheEverActive: false, missing: false }
+        sessions.set(info.sessionID, state)
+      }
+
+      if (!state.cacheEverActive) {
+        // No baseline yet: if the cache shows up now, just record that it
+        // exists for this session. Never alert at this point.
+        if (cacheRead > 0 || cacheWrite > 0) state.cacheEverActive = true
+        return
+      }
+
+      const denom = cacheRead + cacheWrite + input
+      const hitRate = denom > 0 ? cacheRead / denom : 0
+
+      const totalMiss = cacheRead === 0
+      const previousHitRate = state.lastHitRate
+      const dropMiss =
+        previousHitRate !== undefined &&
+        previousHitRate > 0 &&
+        (previousHitRate - hitRate) / previousHitRate >= dropThreshold
+
+      state.lastHitRate = hitRate
+
+      if (!totalMiss && !dropMiss) {
+        // Cache reading normally, no relevant drop compared to the previous turn.
+        state.missing = false
+        return
+      }
+
+      if (input < minTokens) return // miss too small to bother about
+      if (state.missing) return // already alerted for this streak
+      state.missing = true
+
+      if (!toastEnabled) return
+
+      const detail = totalMiss
+        ? `~${input} tokens with no cache hit`
+        : `hit rate dropped from ${Math.round(previousHitRate! * 100)}% to ${Math.round(hitRate * 100)}% (~${input} tokens)`
+
+      await client.tui.showToast({
+        body: {
+          title: "Cache miss",
+          message: `${info.providerID}/${info.modelID}: cache broke (${detail})`,
+          variant: "warning",
+        },
+      })
+    },
+  }
+}
+
+export default CacheMissAlertPlugin

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@toninho09/opencode-cache-scope",
+  "version": "0.1.0",
+  "description": "opencode plugin that alerts you when prompt caching breaks mid-session",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui-sidebar.tsx"
+  },
+  "files": [
+    "index.ts",
+    "tui-sidebar.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "cache",
+    "prompt-caching",
+    "toast",
+    "alert"
+  ],
+  "author": "toninho09",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/toninho09/opencode-cache-scope.git"
+  },
+  "homepage": "https://github.com/toninho09/opencode-cache-scope#readme",
+  "bugs": {
+    "url": "https://github.com/toninho09/opencode-cache-scope/issues"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  },
+  "peerDependencies": {
+    "@opentui/core": ">=0.3.4",
+    "@opentui/keymap": ">=0.3.4",
+    "@opentui/solid": ">=0.3.4"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/core": { "optional": true },
+    "@opentui/keymap": { "optional": true },
+    "@opentui/solid": { "optional": true }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^25.2.2",
+    "@types/bun": "latest",
+    "@opentui/core": "0.3.4",
+    "@opentui/keymap": "0.3.4",
+    "@opentui/solid": "0.3.4",
+    "solid-js": "1.9.12"
+  },
+  "scripts": {
+    "test": "bun test"
+  }
+}

package/tui-sidebar.tsx

@@ -0,0 +1,121 @@
+/** @jsxImportSource @opentui/solid */
+import type { TuiPlugin, TuiPluginApi, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { createMemo, Show } from "solid-js"
+
+function fmt(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "m"
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + "k"
+  return String(n)
+}
+
+function fmtCost(n: number): string {
+  return "$" + n.toFixed(4)
+}
+
+function View(props: { api: TuiPluginApi; session_id: string }) {
+  const theme = () => props.api.theme.current
+
+  // Sums tokens (by type) and cost (by type) of all assistant messages in the
+  // session, and keeps track of whether the last message had cache.read > 0
+  // (cache ok) or 0 (miss).
+  //
+  // Per-type cost is computed locally from each message's model pricing
+  // (price per 1M tokens), since providers don't return a dollar cost in
+  // their API responses. This is an approximation: it doesn't reproduce the
+  // tiered pricing opencode applies for very large contexts
+  // (`model.cost.experimentalOver200K`), so the sum of these parts may
+  // differ slightly from the message's own `cost` field in that edge case.
+  const stats = createMemo(() => {
+    let input = 0
+    let output = 0
+    let cacheRead = 0
+    let cacheWrite = 0
+    let costInput = 0
+    let costOutput = 0
+    let costCacheRead = 0
+    let costCacheWrite = 0
+    let lastCacheRead: number | undefined
+
+    for (const m of props.api.state.session.messages(props.session_id)) {
+      if (m.role !== "assistant" || !m.tokens) continue
+      input += m.tokens.input
+      output += m.tokens.output
+      cacheRead += m.tokens.cache.read
+      cacheWrite += m.tokens.cache.write
+      lastCacheRead = m.tokens.cache.read
+
+      const cost = props.api.state.provider.find((p) => p.id === m.providerID)?.models[m.modelID]?.cost
+      if (cost) {
+        costInput += (m.tokens.input * cost.input) / 1_000_000
+        costOutput += (m.tokens.output * cost.output) / 1_000_000
+        costCacheRead += (m.tokens.cache.read * cost.cache.read) / 1_000_000
+        costCacheWrite += (m.tokens.cache.write * cost.cache.write) / 1_000_000
+      }
+    }
+
+    const active = cacheRead > 0 || cacheWrite > 0
+    const miss = active && lastCacheRead === 0
+    const denom = cacheRead + cacheWrite + input
+    const hitRate = denom > 0 ? Math.round((cacheRead / denom) * 100) : 0
+    const totalCost = costInput + costOutput + costCacheRead + costCacheWrite
+
+    return {
+      input,
+      output,
+      cacheRead,
+      cacheWrite,
+      active,
+      miss,
+      hitRate,
+      costInput,
+      costOutput,
+      costCacheRead,
+      costCacheWrite,
+      totalCost,
+    }
+  })
+
+  return (
+    <Show when={stats().active}>
+      <box>
+        <box flexDirection="row" gap={1}>
+          <text fg={theme().text}>
+            <b>Usage</b>
+          </text>
+        </box>
+        <text fg={theme().textMuted}>hit rate: {stats().hitRate}%</text>
+        <text fg={theme().textMuted}>
+          cache read: {fmt(stats().cacheRead)} ({fmtCost(stats().costCacheRead)})
+        </text>
+        <text fg={theme().textMuted}>
+          cache write: {fmt(stats().cacheWrite)} ({fmtCost(stats().costCacheWrite)})
+        </text>
+        <text fg={theme().textMuted}>
+          input: {fmt(stats().input)} ({fmtCost(stats().costInput)})
+        </text>
+        <text fg={theme().textMuted}>
+          output: {fmt(stats().output)} ({fmtCost(stats().costOutput)})
+        </text>
+        <text fg={theme().textMuted}>total: {fmtCost(stats().totalCost)}</text>
+      </box>
+    </Show>
+  )
+}
+
+const tui: TuiPlugin = async (api) => {
+  api.slots.register({
+    order: 450,
+    slots: {
+      sidebar_content(_ctx, props) {
+        return <View api={api} session_id={props.session_id} />
+      },
+    },
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "opencode-cache-scope.sidebar",
+  tui,
+}
+
+export default plugin