opencode-cache-coach 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# opencode-cache-coach
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [OpenCode](https://opencode.ai) plugin that coaches you on making better use of your tokens.
+It connects token usage and estimated costs to practical choices: when to compact, which model to
+compact on, and how to avoid carrying oversized tool results through the rest of a session.
+
+Your conversation and tool results become input to later requests. Prompt caching makes reusing
+that context cheaper, but switching models, letting the cache expire, or crossing a higher-price
+context threshold can make the next request more expensive. Cache Coach explains these trade-offs
+as you work, with cost comparisons and suggestions based on your session and model prices.
+
+The cache indicator and `/cache` details show where you stand. Tips and expiry messages help you
+decide what to do next, such as compacting while the cache is warm or using a cheaper model when
+the context must be written again.
+
+Requires OpenCode 2.2 or later.
+
+## Installation
+
+```bash
+opencode plugin add opencode-cache-coach
+```
+
+This adds the plugin to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-cache-coach"]
+}
+```
+
+The CLI part shows the indicator, tips, and expiry messages. The server part only keeps the expiry
+messages out of model requests.
+
+## Cache indicator
+
+The prompt footer shows the cache state of the session on screen:
+
+| Footer                                 | Meaning                                                                  |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| `● cache 3:42`                         | Warm. The next message reads the context from the cache.                 |
+| `◐ cache 0:45`                         | Warm, with less than a minute left.                                      |
+| `● cache`                              | A request is running and using the cache.                                |
+| `○ cache cold · rewrite ~180K ($0.90)` | Expired, or another model is selected. The next message writes it again. |
+| `○ cache cold · … · GPT-6.1 Sol $0.45` | As above, and compacting on your `compactionModel` costs less.           |
+| `● cache 3:42 · warming?`              | Warm, in a session that OpenCode warms. See [Warming](#warming).         |
+
+The footer stays empty until the session has a request whose provider reports cache tokens. Click
+the indicator, or run `/cache`, to see the last request's cache hit rate, what the next message
+costs, and the session's cost so far.
+
+The countdown starts when the last request started, and uses the cache lifetime from the model's
+or provider's `cache.ttl` setting, or 5 minutes. Providers can evict a cache earlier, so a warm
+indicator means the cache is likely warm.
+
+### Warming
+
+When OpenCode's [`warming`](https://opencode.ai/docs/warming/) option covers a session, OpenCode
+sends keep-alive requests while you're idle. Those requests add no messages, and the plugin can't
+see whether they renew the cache. With GitLab Duo models, requests after a keep-alive request still
+missed the cache in testing. So the countdown doesn't count on warming, and ends in `· warming?` to
+show that the cache might last longer.
+
+The plugin reads the `warming` setting from the top level of your configuration and from the
+model's or provider's `settings.cache.warming`, once per directory. Restart OpenCode after you
+change `warming`.
+
+## Expiry messages
+
+Shortly before the cache of a large context expires, the plugin adds a message to the session, so
+it's the last thing you see when you come back:
+
+```text
+◈ Prompt cache expires at 14:32. After that, the next message writes ~225K tokens to the cache
+  again (~$1.13 on Claude Opus 5.5). To compact, switch to GPT-6.1 Sol first (~$0.56), run
+  /compact, then switch back.
+```
+
+A compaction after the cache expires writes the whole context again, so compacting on a cheaper
+model saves most of that cost. Set `compactionModel` to name the model. Without it, the message
+only says that a cheaper model costs less.
+
+The message appears once each time the session goes idle, in top-level sessions whose last request
+the TUI saw finish, and only when the next message writes at least `minTokens` and costs at least
+`minCost`. The server part removes these messages from every model request, so the model never
+sees them and the cache isn't affected.
+
+## Tips
+
+The plugin shows a toast when it spots one of these patterns. Each tip appears at most once per
+session, except the model-switch tips, which appear for every switch away from a new request:
+
+- **Model switch on a warm cache.** Selecting another model for a large context means the next
+  message writes it to a new cache. The tip compares that with staying on the current model and
+  suggests compacting first.
+- **Model switch after the cache expired.** The next message writes the context again on any model,
+  so the tip says when the new model, or your `compactionModel`, can compact it for less.
+- **Close to the context ceiling.** At 80% of the ceiling (`contextRatio`), the tip suggests
+  compacting while the cache is warm, and shows what the same compaction costs after the cache
+  expires. The ceiling is 250K tokens by default. For a model that charges more above a prompt
+  size, such as Claude Haiku 5.5 above 100K tokens, the default ceiling is that size instead.
+- **Large tool output.** A tool result stays in every later request in the session. The tip
+  suggests asking for a narrower result next time.
+- **Warming didn't keep the cache.** When warming is on and a request within the warming window
+  still writes the context again, the tip says what that cost, and suggests turning warming off for
+  the model, because its keep-alive requests cost money too. A provider can also drop a cache early,
+  so one miss isn't proof that warming never works.
+
+Tips stay in the TUI and never enter the conversation, so they don't add tokens or change the
+cache. Subagent sessions don't get tips.
+
+## Options
+
+The options belong to the CLI part, which reads them from `cli.json`. Add the same package there
+with the object form. OpenCode still loads the plugin once:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "opencode-cache-coach",
+      "options": { "compactionModel": "gitlab/duo-chat-gpt-6-1-sol", "contextCeiling": 180000 }
+    }
+  ]
+}
+```
+
+| Option            | Default                                  | Description                                                                                                                                                                                                               |
+| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tips`            | `true`                                   | Set to `false` to keep only the indicator.                                                                                                                                                                                |
+| `notices`         | `true`                                   | Set to `false` to turn off the expiry messages.                                                                                                                                                                           |
+| `compactionModel` |                                          | Model to suggest for compacting after the cache expires, such as `"gitlab/duo-chat-gpt-6-1-sol"`, or a list in order of preference. The plugin suggests the first one that fits the context and saves at least `minCost`. |
+| `ttl`             |                                          | Cache lifetime, such as `"1h"`. Overrides the model and provider `cache.ttl`.                                                                                                                                             |
+| `contextCeiling`  | `250000`, or where a higher price starts | Context size the ceiling tip measures against. Setting it applies to every model, including tiered ones. Capped at the model's input limit.                                                                               |
+| `contextRatio`    | `0.8`                                    | Share of the ceiling at which the ceiling tip appears.                                                                                                                                                                    |
+| `minTokens`       | `50000`                                  | Smallest context that a model-switch tip or an expiry message covers.                                                                                                                                                     |
+| `minCost`         | `0.1`                                    | Smallest cost or cost difference, in USD, that a model-switch tip or an expiry message covers.                                                                                                                            |
+| `largeOutput`     | `20000`                                  | Estimated tokens in a tool result at which the large-output tip appears.                                                                                                                                                  |
+
+Costs come from the model prices OpenCode knows, including cache and long-context prices. Without
+them, the indicator and tips leave the amounts out.
+
+## Install a local build
+
+Run `mise run build cache-coach` from the repository root, then point the plugin entries in your
+`opencode.json` and `cli.json` at the package directory, such as
+`"package": "/path/to/opencode-plugins/packages/cache-coach"`, and restart OpenCode.

package/dist/index.js

@@ -0,0 +1,24 @@
+// @bun
+// packages/cache-coach/src/notice.ts
+var NOTICE_TEXT = "[cache-coach: a prompt cache notice for the user. Ignore it.]";
+var isNotice = (message) => {
+  if (message.role !== "user" || message.content.length !== 1)
+    return false;
+  const part = message.content[0];
+  return part?.type === "text" && part.text === NOTICE_TEXT;
+};
+var withoutNotices = (messages) => messages.filter((message) => !isNotice(message));
+
+// packages/cache-coach/src/index.ts
+var src_default = {
+  id: "opencode-cache-coach",
+  async setup(ctx) {
+    for (const kind of ["context", "generate", "compaction", "title"])
+      await ctx.session.hook(kind, (event) => {
+        event.messages = withoutNotices(event.messages);
+      });
+  }
+};
+export {
+  src_default as default
+};

package/dist/tui.js

@@ -0,0 +1,851 @@
+// @bun
+// packages/cache-coach/src/tui.tsx
+import { effect as _$effect } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+import { createComponent as _$createComponent } from "@opentui/solid";
+import { createEffect, createMemo, createSignal, Show, untrack } from "solid-js";
+// packages/_shared/src/location.ts
+function eventSessionID(event) {
+  const data = event.data;
+  if (typeof data?.sessionID === "string")
+    return data.sessionID;
+  const formSessionID = data?.form?.sessionID;
+  return typeof formSessionID === "string" ? formSessionID : undefined;
+}
+// packages/_shared/src/view.ts
+function createViewFilter(context, tracks) {
+  function visible(sessionID) {
+    const root = context.data.session.root(sessionID);
+    const route = context.ui.router.current();
+    if (route.type === "session" && context.data.session.root(route.sessionID) === root) {
+      return true;
+    }
+    return context.ui.tabs.enabled() && context.ui.tabs.list().some((tab) => tab.sessionID === root);
+  }
+  return function shows(event) {
+    const sessionID = eventSessionID(event);
+    return sessionID !== undefined && (tracks(sessionID) || visible(sessionID));
+  };
+}
+// packages/cache-coach/src/cache.ts
+var DEFAULT_TTL = 5 * 60000;
+var EXPIRING = 60000;
+var sameModel = (a, b) => !!a && !!b && a.providerID === b.providerID && a.id === b.id;
+var promptTokens = (tokens) => tokens.input + tokens.cache.read + tokens.cache.write;
+var contextTokens = (tokens) => promptTokens(tokens) + tokens.output;
+var reportsCache = (tokens) => tokens.cache.read + tokens.cache.write > 0;
+function lastStep(messages, started, skip) {
+  for (let index = messages.length - 1;index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.type === "compaction" && message.status === "completed")
+      return;
+    if (message.id === skip)
+      continue;
+    if (message.type !== "assistant" || !message.tokens || !message.model)
+      continue;
+    if (promptTokens(message.tokens) === 0)
+      continue;
+    const start = started?.(message.id) ?? message.time.created;
+    return {
+      id: message.id,
+      model: message.model,
+      started: start,
+      ...message.time.completed === undefined ? {} : { ended: Math.max(start, message.time.completed) },
+      tokens: message.tokens
+    };
+  }
+  return;
+}
+function priceFor(costs, prompt) {
+  let chosen;
+  for (const cost of costs ?? []) {
+    if (cost.tier && prompt <= cost.tier.size)
+      continue;
+    if (!chosen || (cost.tier?.size ?? 0) > (chosen.tier?.size ?? 0))
+      chosen = cost;
+  }
+  if (!chosen || chosen.input <= 0)
+    return;
+  return {
+    input: chosen.input,
+    output: chosen.output,
+    read: chosen.cache.read || chosen.input,
+    write: chosen.cache.write || chosen.input
+  };
+}
+var usd = (tokens, perMillion) => tokens * perMillion / 1e6;
+var DEFAULT_CEILING = 250000;
+function priceTier(costs) {
+  const sizes = (costs ?? []).flatMap((cost) => cost.tier?.type === "context" && cost.tier.size > 0 ? [cost.tier.size] : []);
+  return sizes.length ? Math.min(...sizes) : undefined;
+}
+function contextCeiling(input) {
+  const cap = (tokens) => input.modelLimit && input.modelLimit > 0 ? Math.min(tokens, input.modelLimit) : tokens;
+  if (input.configured)
+    return { tokens: cap(input.configured), reason: "limit" };
+  const tier = priceTier(input.costs);
+  if (tier && (!input.modelLimit || tier < input.modelLimit))
+    return { tokens: tier, reason: "price" };
+  return { tokens: cap(DEFAULT_CEILING), reason: "limit" };
+}
+var UNITS = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function parseTtl(value) {
+  if (typeof value !== "string")
+    return;
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(value.trim());
+  if (!match)
+    return;
+  const ttl = Number(match[1]) * UNITS[match[2]];
+  return ttl > 0 ? ttl : undefined;
+}
+function cacheState(input) {
+  const { step } = input;
+  if (!step || !reportsCache(step.tokens))
+    return { kind: "unknown" };
+  if (input.running)
+    return { kind: "running", step };
+  if (input.selected && !sameModel(input.selected, step.model))
+    return { kind: "cold", step, reason: "model" };
+  const remaining = step.started + input.ttl - input.now;
+  return remaining > 0 ? { kind: "warm", step, remaining, warming: !!input.warming } : { kind: "cold", step, reason: "expired" };
+}
+function formatTokens(count) {
+  if (count >= 1e6)
+    return `${Number((count / 1e6).toFixed(1))}M`;
+  if (count >= 1000)
+    return `${Math.round(count / 1000)}K`;
+  return String(Math.round(count));
+}
+var formatUsd = (amount) => amount < 0.005 ? "<$0.01" : `$${amount.toFixed(2)}`;
+var aboutUsd = (amount) => amount < 0.005 ? "under $0.01" : `~$${amount.toFixed(2)}`;
+function formatRemaining(ms) {
+  const seconds = Math.max(0, Math.ceil(ms / 1000));
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+function formatDuration(ms) {
+  if (ms >= 3600000 && ms % 3600000 === 0)
+    return `${ms / 3600000}h`;
+  const seconds = Math.round(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  if (minutes === 0)
+    return `${seconds}s`;
+  return seconds % 60 ? `${minutes}m${seconds % 60}s` : `${minutes}m`;
+}
+var shortName = (name) => /\(([^()]+)\)\s*$/.exec(name)?.[1] ?? name;
+function indicator(state, next, alternative) {
+  if (state.kind === "unknown")
+    return;
+  if (state.kind === "running")
+    return { text: "\u25CF cache", tone: "success" };
+  if (state.kind === "warm") {
+    const time = `${formatRemaining(state.remaining)}${state.warming ? " \xB7 warming?" : ""}`;
+    return state.remaining <= EXPIRING ? { text: `\u25D0 cache ${time}`, tone: "warning" } : { text: `\u25CF cache ${time}`, tone: "success" };
+  }
+  const rewrite = next ? ` \xB7 rewrite ~${formatTokens(next.tokens)}${next.cost === undefined ? "" : ` (${formatUsd(next.cost)})`}` : "";
+  const cheaper = alternative ? ` \xB7 ${shortName(alternative.name)} ${formatUsd(alternative.cost)}` : "";
+  return { text: `\u25CB cache cold${rewrite}${cheaper}`, tone: "warning" };
+}
+function nextCost(state, tokens, price) {
+  if (!price)
+    return { tokens };
+  const warm = state.kind === "warm" || state.kind === "running";
+  return { tokens, cost: usd(tokens, warm ? price.read : price.write) };
+}
+function details(input) {
+  const { state, warming } = input;
+  if (state.kind === "unknown")
+    return ["No cache data yet. The provider may not report cache tokens for this session."];
+  const lines = [];
+  if (state.kind === "running")
+    lines.push("Cache: in use by the running request");
+  else if (state.kind === "warm")
+    lines.push(`Cache: warm, about ${formatRemaining(state.remaining)} left`);
+  else if (state.reason === "expired")
+    lines.push("Cache: cold, it expired");
+  else
+    lines.push(`Cache: cold, ${input.selectedModel ?? "the selected model"} has no cache for this session`);
+  lines.push(`Cache lifetime: ${formatDuration(input.ttl)} after each request`);
+  lines.push(warming ? `Warming: every ${formatDuration(warming.interval)} while idle, until ${formatDuration(warming.duration)} after the last request. Warming requests may not renew the cache, so the countdown doesn't count on them.` : "Warming: off");
+  const { tokens } = state.step;
+  const prompt = promptTokens(tokens);
+  const hit = prompt ? Math.round(tokens.cache.read / prompt * 100) : 0;
+  lines.push("", `Last request${input.stepModel ? ` on ${input.stepModel}` : ""}: ${formatTokens(prompt)} prompt tokens, ${hit}% read from the cache`, `Read ${formatTokens(tokens.cache.read)} \xB7 written ${formatTokens(tokens.cache.write)} \xB7 uncached ${formatTokens(tokens.input)} \xB7 output ${formatTokens(tokens.output)}`);
+  const cost = input.next.cost === undefined ? "" : ` (${aboutUsd(input.next.cost)})`;
+  const warm = state.kind === "warm" || state.kind === "running";
+  lines.push(warm ? `Next message: reads ~${formatTokens(input.next.tokens)} tokens from the cache${cost}` : `Next message: writes ~${formatTokens(input.next.tokens)} tokens to a new cache${cost}`);
+  if (input.sessionCost !== undefined)
+    lines.push(`Session cost so far: ${formatUsd(input.sessionCost)}`);
+  return lines;
+}
+
+// packages/cache-coach/src/options.ts
+var DEFAULTS = {
+  tips: true,
+  notices: true,
+  compactionModels: [],
+  contextRatio: 0.8,
+  minTokens: 50000,
+  minCost: 0.1,
+  largeOutput: 20000
+};
+var isPositive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
+var positive = (value, fallback) => isPositive(value) ? value : fallback;
+function modelRef(value) {
+  if (typeof value !== "string")
+    return [];
+  const slash = value.indexOf("/");
+  if (slash <= 0 || slash === value.length - 1)
+    return [];
+  return [{ providerID: value.slice(0, slash), id: value.slice(slash + 1) }];
+}
+var modelRefs = (value) => (Array.isArray(value) ? value : [value]).flatMap((entry) => modelRef(entry));
+function parseOptions(options) {
+  const value = options ?? {};
+  const ratio = positive(value["contextRatio"], DEFAULTS.contextRatio);
+  return {
+    tips: value["tips"] !== false,
+    notices: value["notices"] !== false,
+    compactionModels: modelRefs(value["compactionModel"]),
+    ttl: parseTtl(value["ttl"]),
+    contextCeiling: isPositive(value["contextCeiling"]) ? value["contextCeiling"] : undefined,
+    contextRatio: ratio <= 1 ? ratio : DEFAULTS.contextRatio,
+    minTokens: positive(value["minTokens"], DEFAULTS.minTokens),
+    minCost: positive(value["minCost"], DEFAULTS.minCost),
+    largeOutput: positive(value["largeOutput"], DEFAULTS.largeOutput)
+  };
+}
+
+// packages/cache-coach/src/tips.ts
+function modelSwitchTip(input) {
+  const { tokens, from, to } = input;
+  if (tokens < input.minTokens)
+    return;
+  const size = `~${formatTokens(tokens)} tokens`;
+  const move = to.price && usd(tokens, to.price.write);
+  if (input.warm) {
+    const stay2 = from.price && usd(tokens, from.price.read);
+    if (move !== undefined && stay2 !== undefined && move - stay2 < input.minCost)
+      return;
+    const costs2 = move !== undefined && stay2 !== undefined ? ` (${aboutUsd(move)}). Staying on ${from.name} reads them from its cache (${aboutUsd(stay2)})` : `. Staying on ${from.name} reads them from its cache instead`;
+    return {
+      key: "model-switch",
+      title: "This model switch rewrites the cache",
+      variant: "warning",
+      message: `Your next message on ${to.name} writes ${size} to a new cache${costs2}. To compact, switch back, compact, and then switch.`
+    };
+  }
+  const stay = from.price && usd(tokens, from.price.write);
+  if (stay === undefined)
+    return;
+  const cheaper = input.compaction ?? (move !== undefined && stay - move >= input.minCost ? { name: to.name, cost: move } : undefined);
+  if (!cheaper)
+    return;
+  const costs = `${move === undefined ? "" : `${aboutUsd(move)} on ${to.name}, `}${aboutUsd(stay)} on ${from.name}`;
+  return {
+    key: "model-switch-cold",
+    title: "The cache already expired",
+    variant: "info",
+    message: `The next message rewrites ${size} on any model: ${costs}. If you plan to compact, compacting on ${cheaper.name} costs less (${aboutUsd(cheaper.cost)}).`
+  };
+}
+function contextCeilingTip(input) {
+  const { tokens, ceiling, price } = input;
+  if (ceiling.tokens <= 0 || tokens < ceiling.tokens * input.ratio)
+    return;
+  const costs = price ? ` reads the context from the cache for ${aboutUsd(usd(tokens, price.read))}. After the cache expires, the same compaction pays ${aboutUsd(usd(tokens, price.write))} to write it again.` : " reads the context from the cache instead of writing it again.";
+  const position = ceiling.reason === "price" ? `~${formatTokens(tokens)} tokens, and this model charges a higher price for prompts over ${formatTokens(ceiling.tokens)} tokens` : `~${formatTokens(tokens)} of ${formatTokens(ceiling.tokens)} tokens`;
+  return {
+    key: "context-limit",
+    title: ceiling.reason === "price" ? "Close to a higher price" : "Close to the context limit",
+    variant: "info",
+    message: `This session's context is at ${position}. Compacting now, while the cache is warm,${costs}`
+  };
+}
+function largeOutputTip(input) {
+  const { tool, tokens, price } = input;
+  if (tokens < input.threshold)
+    return;
+  const cost = price ? `, adding ${aboutUsd(usd(tokens, price.read))} to each request as cache reads` : "";
+  return {
+    key: `large-output:${tool}`,
+    title: "Large tool output",
+    variant: "info",
+    message: `${tool} returned ~${formatTokens(tokens)} tokens. They stay in every later request in this session${cost}. Next time, ask for a narrower result, for example with grep, head, or a line range.`
+  };
+}
+function warmingTip(input) {
+  const { gap, written, price } = input;
+  if (gap <= input.ttl || gap >= input.warming.duration)
+    return;
+  if (input.prompt < input.minTokens || written < input.prompt / 2)
+    return;
+  const rewrite = price && usd(written, price.write);
+  if (rewrite !== undefined && rewrite < input.minCost)
+    return;
+  const minutes = Math.round(gap / 60000);
+  const away = `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const cost = rewrite === undefined ? "" : ` (${aboutUsd(rewrite)})`;
+  return {
+    key: "warming",
+    title: "Warming didn't keep the cache",
+    variant: "warning",
+    message: `Warming didn't keep the cache this time: this request wrote ~${formatTokens(written)} tokens again${cost} after ${away} away. Warming requests also cost money, so consider turning warming off for ${input.model}.`
+  };
+}
+var estimateTokens = (text) => Math.ceil(text.length / 4);
+
+// packages/cache-coach/src/warming.ts
+var DEFAULT_WARMING = { interval: 4 * 60000, duration: 30 * 60000 };
+var UNITS2 = {
+  ms: 1,
+  millisecond: 1,
+  s: 1000,
+  sec: 1000,
+  second: 1000,
+  m: 60000,
+  min: 60000,
+  minute: 60000,
+  h: 3600000,
+  hr: 3600000,
+  hour: 3600000,
+  d: 86400000,
+  day: 86400000
+};
+function parseDuration(value) {
+  if (typeof value !== "string")
+    return;
+  const match = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(value.trim());
+  if (!match)
+    return;
+  const name = match[2].toLowerCase();
+  const unit = UNITS2[name] ?? UNITS2[name.replace(/s$/, "")];
+  const duration = unit === undefined ? undefined : Number(match[1]) * unit;
+  return duration && duration > 0 ? duration : undefined;
+}
+var fieldsOf = (value) => value === true ? {} : value && typeof value === "object" ? value : undefined;
+function schedule(fields, top, ttl) {
+  const rawInterval = fields.interval ?? top.interval;
+  const interval = rawInterval === "auto" ? ttl && ttl * 0.9 : rawInterval === undefined ? DEFAULT_WARMING.interval : parseDuration(rawInterval);
+  const rawDuration = fields.duration ?? top.duration;
+  const duration = rawDuration === undefined ? DEFAULT_WARMING.duration : parseDuration(rawDuration);
+  if (!interval || !duration || interval >= duration)
+    return;
+  return { interval, duration };
+}
+function resolveWarming(input) {
+  const top = fieldsOf(input.top);
+  const chosen = [input.model, input.provider, input.top].find((value) => value !== undefined);
+  if (chosen === undefined || chosen === false)
+    return;
+  const fields = fieldsOf(chosen);
+  if (fields) {
+    const resolved = schedule(fields, top ?? {}, input.ttl);
+    if (resolved || chosen === input.top)
+      return resolved;
+  }
+  return top ? schedule(top, {}, input.ttl) : undefined;
+}
+
+// packages/cache-coach/src/compaction.ts
+function compactionChoice(input) {
+  if (!input.price)
+    return;
+  const rewrite = usd(input.tokens, input.price.write);
+  for (const candidate of input.candidates) {
+    if (sameModel(candidate.ref, input.current))
+      continue;
+    if (candidate.limit && candidate.limit < input.tokens)
+      continue;
+    const price = priceFor(candidate.costs, input.tokens);
+    if (!price)
+      continue;
+    const cost = usd(input.tokens, price.write);
+    if (rewrite - cost >= input.minCost)
+      return { ref: candidate.ref, name: candidate.name, cost };
+  }
+  return;
+}
+function formatClock(ms) {
+  const date = new Date(ms);
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+function expiryNotice(input) {
+  const { tokens, from, choice } = input;
+  if (tokens < input.minTokens)
+    return;
+  const rewrite = from.price && usd(tokens, from.price.write);
+  if (rewrite !== undefined && rewrite < input.minCost)
+    return;
+  const cost = rewrite === undefined ? "" : ` (${aboutUsd(rewrite)} on ${from.name})`;
+  const advice = choice ? `To compact, switch to ${choice.name} first (${aboutUsd(choice.cost)}), run /compact, then switch back.` : "Compacting on a cheaper model costs less.";
+  return `Prompt cache expires at ${input.time}. After that, the next message writes ~${formatTokens(tokens)} tokens to the cache again${cost}. ${advice}`;
+}
+
+// packages/cache-coach/src/notice.ts
+var NOTICE_TEXT = "[cache-coach: a prompt cache notice for the user. Ignore it.]";
+
+// packages/cache-coach/src/tui.tsx
+var tui_default = {
+  id: "opencode-cache-coach",
+  async setup(context) {
+    const settings = parseOptions(context.options);
+    const [now, setNow] = createSignal(Date.now());
+    const clock = setInterval(() => {
+      const time = Date.now();
+      setNow(time);
+      checkNotices(time);
+    }, 1000);
+    const [starts, setStarts] = context.storage.memory("step-starts", {
+      initial: {}
+    });
+    const [shown, setShown] = context.storage.memory("tips-shown", {
+      initial: {}
+    });
+    const session = (sessionID) => context.data.session.get(sessionID);
+    const locationOf = (sessionID) => {
+      const directory = session(sessionID)?.location.directory;
+      return directory ? {
+        directory
+      } : undefined;
+    };
+    const synced = new Set;
+    function catalog(sessionID) {
+      const location = locationOf(sessionID);
+      const models = context.data.location.model.list(location);
+      const providers = context.data.location.provider.list(location);
+      const key = location?.directory ?? "";
+      if ((!models || !providers) && !synced.has(key)) {
+        synced.add(key);
+        context.data.location.model.sync(location).catch(() => {});
+        context.data.location.provider.sync(location).catch(() => {});
+      }
+      return {
+        models: models ?? [],
+        providers: providers ?? []
+      };
+    }
+    const findModel = (models, ref) => ref ? models.find((model) => model.providerID === ref.providerID && (model.id === ref.id || model.modelID === ref.id)) : undefined;
+    const ttlFor = (model, provider) => settings.ttl ?? parseTtl(model?.settings?.cache?.ttl) ?? parseTtl(provider?.settings?.cache?.ttl) ?? DEFAULT_TTL;
+    const nameOf = (model, ref) => model?.name ?? ref.id;
+    function compactionFor(models, current, tokens, price) {
+      const candidates = settings.compactionModels.flatMap((ref) => {
+        const model = findModel(models, ref);
+        if (!model)
+          return [];
+        const limit = model.limit.input ?? model.limit.context;
+        return [{
+          ref,
+          name: nameOf(model, ref),
+          costs: model.cost,
+          limit
+        }];
+      });
+      return compactionChoice({
+        candidates,
+        current,
+        tokens,
+        price,
+        minCost: settings.minCost
+      });
+    }
+    const [configured, setConfigured] = createSignal({});
+    const loading = new Set;
+    function topWarming(directory) {
+      const key = directory ?? "";
+      const loaded = configured()[key];
+      if (!loaded && !loading.has(key)) {
+        loading.add(key);
+        context.client.config.get(directory ? {
+          location: {
+            directory
+          }
+        } : undefined).then((entries) => {
+          const warming = [...entries].reverse().map((entry) => entry.type === "document" ? entry.info.warming : undefined).find((value) => value !== undefined);
+          setConfigured((current) => ({
+            ...current,
+            [key]: {
+              warming
+            }
+          }));
+        }).catch(() => loading.delete(key));
+      }
+      return loaded?.warming;
+    }
+    const cacheSettings = (settings2) => settings2?.cache;
+    function warmingFor(sessionID, model, provider) {
+      if (session(sessionID)?.parentID)
+        return;
+      const fromModel = cacheSettings(model?.settings);
+      const fromProvider = cacheSettings(provider?.settings);
+      return resolveWarming({
+        top: topWarming(locationOf(sessionID)?.directory),
+        provider: fromProvider?.warming,
+        model: fromModel?.warming,
+        ttl: parseTtl(fromModel?.ttl) ?? parseTtl(fromProvider?.ttl)
+      });
+    }
+    function selectedModel(sessionID) {
+      const route = context.ui.router.current();
+      if (route.type === "session" && route.sessionID === sessionID) {
+        const current = context.ui.model.current();
+        if (current)
+          return {
+            providerID: current.providerID,
+            id: current.modelID
+          };
+      }
+      return session(sessionID)?.model;
+    }
+    const startedAt = (sessionID) => (id) => {
+      const start = starts[sessionID];
+      return start?.id === id ? start.at : undefined;
+    };
+    const stepOf = (sessionID) => lastStep(context.data.session.message.list(sessionID), startedAt(sessionID));
+    function view(sessionID, time) {
+      const step = stepOf(sessionID);
+      const {
+        models,
+        providers
+      } = catalog(sessionID);
+      const selected = selectedModel(sessionID);
+      const stepModel = step && findModel(models, step.model);
+      const target = selected ? findModel(models, selected) : stepModel;
+      const provider = step && providers.find((entry) => entry.id === step.model.providerID);
+      const ttl = ttlFor(stepModel, provider);
+      const warming = warmingFor(sessionID, stepModel, provider);
+      const state = cacheState({
+        step,
+        now: time,
+        ttl,
+        running: context.data.session.status(sessionID) === "running",
+        selected,
+        warming
+      });
+      const tokens = step ? contextTokens(step.tokens) : 0;
+      const next = nextCost(state, tokens, target && priceFor(target.cost, tokens));
+      const alternative = state.kind === "cold" && step ? compactionFor(models, selected ?? step.model, tokens, target && priceFor(target.cost, tokens)) : undefined;
+      return {
+        state,
+        ttl,
+        warming,
+        next,
+        alternative,
+        stepModel: step && nameOf(stepModel, step.model),
+        selectedModel: selected && nameOf(target, selected)
+      };
+    }
+    const color = (tone) => {
+      if (tone === "success")
+        return context.theme.text.feedback.success.base;
+      if (tone === "warning")
+        return context.theme.text.feedback.warning.base;
+      return context.theme.text.muted;
+    };
+    function showDetails(sessionID) {
+      const route = context.ui.router.current();
+      const id = sessionID ?? (route.type === "session" ? route.sessionID : undefined);
+      if (!id) {
+        context.ui.toast.show({
+          message: "Open a session to see its cache",
+          variant: "info"
+        });
+        return;
+      }
+      const current = view(id, Date.now());
+      context.ui.dialog.alert({
+        title: "Prompt cache",
+        message: details({
+          ...current,
+          sessionCost: context.data.session.cost(id)
+        }).join(`
+`)
+      });
+    }
+    function showTip(sessionID, tip) {
+      if (!tip || !settings.tips)
+        return;
+      const key = `${sessionID}:${tip.key}`;
+      if (shown[key])
+        return;
+      setShown((draft) => {
+        draft[key] = true;
+      });
+      context.ui.toast.show({
+        title: tip.title,
+        message: tip.message,
+        variant: tip.variant,
+        duration: 12000,
+        sessionID
+      });
+    }
+    const pending = {};
+    function scheduleNotice(input) {
+      const {
+        sessionID,
+        ref,
+        model,
+        tokens
+      } = input;
+      delete pending[sessionID];
+      if (!settings.notices || !ref)
+        return;
+      const price = model && priceFor(model.cost, tokens);
+      const choice = compactionFor(input.models, ref, tokens, price);
+      const description = expiryNotice({
+        time: formatClock(input.expires),
+        tokens,
+        from: {
+          name: shortName(nameOf(model, ref)),
+          price
+        },
+        choice: choice && {
+          ...choice,
+          name: shortName(choice.name)
+        },
+        minTokens: settings.minTokens,
+        minCost: settings.minCost
+      });
+      if (!description)
+        return;
+      pending[sessionID] = {
+        stepID: input.stepID,
+        at: input.expires - EXPIRING,
+        expires: input.expires,
+        description
+      };
+    }
+    function checkNotices(time) {
+      for (const [sessionID, notice] of Object.entries(pending)) {
+        if (!notice || time < notice.at)
+          continue;
+        delete pending[sessionID];
+        if (time >= notice.expires || context.data.session.status(sessionID) === "running")
+          continue;
+        context.client.session.synthetic({
+          sessionID,
+          id: `${notice.stepID}-cache-coach`,
+          text: NOTICE_TEXT,
+          description: notice.description,
+          metadata: {
+            cacheCoach: "expiry"
+          },
+          resume: false
+        }).catch(() => {});
+      }
+    }
+    function checkSwitch(sessionID, selected) {
+      const step = stepOf(sessionID);
+      if (!step || !reportsCache(step.tokens) || sameModel(step.model, selected))
+        return;
+      const {
+        models,
+        providers
+      } = catalog(sessionID);
+      const from = findModel(models, step.model);
+      const to = findModel(models, selected);
+      const provider = providers.find((entry) => entry.id === step.model.providerID);
+      const tokens = contextTokens(step.tokens);
+      const price = from && priceFor(from.cost, tokens);
+      const tip = modelSwitchTip({
+        tokens,
+        warm: step.started + ttlFor(from, provider) > Date.now(),
+        from: {
+          name: nameOf(from, step.model),
+          price
+        },
+        to: {
+          name: nameOf(to, selected),
+          price: to && priceFor(to.cost, tokens)
+        },
+        compaction: compactionFor(models, step.model, tokens, price),
+        minTokens: settings.minTokens,
+        minCost: settings.minCost
+      });
+      showTip(sessionID, tip && {
+        ...tip,
+        key: `${tip.key}:${step.id}`
+      });
+    }
+    const shows = createViewFilter(context, () => false);
+    const coached = (sessionID) => !session(sessionID)?.parentID;
+    function onStepEnded(event) {
+      const {
+        sessionID,
+        assistantMessageID,
+        tokens
+      } = event.data;
+      if (!coached(sessionID) || !reportsCache(tokens))
+        return;
+      const message = context.data.session.message.get(sessionID, assistantMessageID);
+      const ref = message?.type === "assistant" ? message.model : session(sessionID)?.model ?? undefined;
+      const {
+        models,
+        providers
+      } = catalog(sessionID);
+      const model = findModel(models, ref);
+      const total = contextTokens(tokens);
+      const provider = ref && providers.find((entry) => entry.id === ref.providerID);
+      const start = starts[sessionID];
+      const started = start?.id === assistantMessageID ? start.at : message?.time.created ?? Date.now();
+      scheduleNotice({
+        sessionID,
+        stepID: assistantMessageID,
+        expires: started + ttlFor(model, provider),
+        tokens: total,
+        ref,
+        model,
+        models
+      });
+      if (!shows(event))
+        return;
+      const previous = lastStep(context.data.session.message.list(sessionID), startedAt(sessionID), assistantMessageID);
+      const warming = warmingFor(sessionID, model, provider);
+      if (previous && ref && warming && sameModel(previous.model, ref)) {
+        showTip(sessionID, warmingTip({
+          gap: started - (previous.ended ?? previous.started),
+          ttl: ttlFor(model, provider),
+          warming,
+          model: shortName(nameOf(model, ref)),
+          written: tokens.cache.write,
+          prompt: promptTokens(tokens),
+          minTokens: settings.minTokens,
+          minCost: settings.minCost,
+          price: model && priceFor(model.cost, total)
+        }));
+      }
+      showTip(sessionID, contextCeilingTip({
+        tokens: total,
+        ceiling: contextCeiling({
+          configured: settings.contextCeiling,
+          costs: model?.cost,
+          modelLimit: model ? model.limit.input ?? model.limit.context : undefined
+        }),
+        ratio: settings.contextRatio,
+        price: model && priceFor(model.cost, total)
+      }));
+    }
+    function onToolSuccess(event) {
+      const {
+        sessionID,
+        assistantMessageID,
+        id,
+        content
+      } = event.data;
+      if (!shows(event) || !coached(sessionID))
+        return;
+      const text = content.reduce((sum, part) => sum + (part.type === "text" ? part.text : ""), "");
+      const tokens = estimateTokens(text);
+      if (tokens < settings.largeOutput)
+        return;
+      const message = context.data.session.message.get(sessionID, assistantMessageID);
+      const assistant = message?.type === "assistant" ? message : undefined;
+      const tool = assistant?.content.find((part) => part.type === "tool" && part.id === id);
+      const model = findModel(catalog(sessionID).models, assistant?.model);
+      showTip(sessionID, largeOutputTip({
+        tool: tool?.type === "tool" ? tool.name : "A tool",
+        tokens,
+        threshold: settings.largeOutput,
+        price: model && priceFor(model.cost, tokens)
+      }));
+    }
+    function Indicator(props) {
+      const current = createMemo(() => {
+        if (!props.sessionID)
+          return;
+        const value = view(props.sessionID, now());
+        return indicator(value.state, value.next, value.alternative);
+      });
+      return _$createComponent(Show, {
+        get when() {
+          return current();
+        },
+        children: (value) => (() => {
+          var _el$ = _$createElement("text");
+          _$setProp(_el$, "wrapMode", "none");
+          _$setProp(_el$, "flexShrink", 0);
+          _$setProp(_el$, "onMouseUp", () => showDetails(props.sessionID));
+          _$insert(_el$, () => value().text);
+          _$effect((_$p) => _$setProp(_el$, "fg", color(value().tone), _$p));
+          return _el$;
+        })()
+      });
+    }
+    context.ui.slot({
+      append: "prompt.footer.status",
+      render: (input) => _$createComponent(Indicator, {
+        get sessionID() {
+          return input.sessionID;
+        }
+      })
+    });
+    context.ui.slot({
+      append: "app",
+      render: () => {
+        let previous;
+        createEffect(() => {
+          const route = context.ui.router.current();
+          const current = context.ui.model.current();
+          if (route.type !== "session" || !current) {
+            previous = undefined;
+            return;
+          }
+          const key = `${current.providerID}/${current.modelID}`;
+          const last = previous;
+          previous = {
+            sessionID: route.sessionID,
+            key
+          };
+          if (!last || last.sessionID !== route.sessionID || last.key === key)
+            return;
+          untrack(() => checkSwitch(route.sessionID, {
+            providerID: current.providerID,
+            id: current.modelID
+          }));
+        });
+        context.keymap.layer(() => ({
+          mode: "global",
+          commands: [{
+            id: "cache-coach.details",
+            title: "Show prompt cache status",
+            group: "Cache",
+            palette: true,
+            slash: {
+              name: "cache"
+            },
+            run: () => showDetails()
+          }]
+        }));
+        return null;
+      }
+    });
+    const stops = [context.data.on("session.step.started", (event) => {
+      const {
+        sessionID,
+        assistantMessageID
+      } = event.data;
+      delete pending[sessionID];
+      setStarts((draft) => {
+        draft[sessionID] = {
+          id: assistantMessageID,
+          at: Date.now()
+        };
+      });
+    }), context.data.on("session.step.ended", onStepEnded), context.data.on("session.tool.success", onToolSuccess), context.data.on("session.compaction.ended", (event) => {
+      const key = `${event.data.sessionID}:context-limit`;
+      setShown((draft) => {
+        delete draft[key];
+      });
+    })];
+    return () => {
+      clearInterval(clock);
+      for (const stop of stops)
+        stop();
+    };
+  }
+};
+export {
+  tui_default as default
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "opencode-cache-coach",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCode plugin that shows whether a session's prompt cache is still warm and suggests cheaper habits when a costly pattern shows up",
+  "author": {
+    "name": "Pedro Pombeiro",
+    "email": "pedropombeiro@users.noreply.github.com"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    },
+    "./tui": {
+      "default": "./dist/tui.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedropombeiro/opencode-plugins.git",
+    "directory": "packages/cache-coach"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "prompt-cache",
+    "cost",
+    "tokens"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode/plugin": "^2.2.0",
+    "@opentui/core": ">=0.7.0",
+    "@opentui/solid": ">=0.7.0",
+    "solid-js": ">=1.9.0"
+  }
+}