cache-timer 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `cache-timer` are documented here. The format is
+loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-26
+
+Initial public release.
+
+### Added
+- **Visual cache countdown** rendered in `session_prompt_right`. Shows time
+  remaining until the prompt cache goes cold, with `HOT`, near-expiry warning,
+  and `COLD` states. Per-model duration based on substring-matched provider
+  family.
+- **Opt-in pre-emptive auto-summary.** When `enableAutoPrompt: true` is set in
+  the sidecar config, the plugin fires a tiny "Summarize our progress and next
+  steps. Be brief." prompt 15 seconds before the cache expires. The summary
+  reads from the hot cache (cheap), giving you an artifact to paste into a
+  fresh session and skip the cold-write tax of resuming the bloated original.
+  Off by default — the plugin never spends tokens without explicit consent.
+- **Sidecar config** at `~/.config/opencode/cache-timer.json` (global) and
+  `./.opencode/cache-timer.json` (project). Project values win per-field over
+  global. Supports `enableAutoPrompt`, `durations` (per-family seconds), and
+  `defaultDuration`.
+- **Family-key duration map** with substring matching. A single `"claude": 300`
+  entry covers `claude-opus-4-7`, `claude-haiku-4-5`, `claude-3-5-sonnet`, etc.
+- **Race-safe auto-prompt detection.** The plugin tracks pending auto-prompts
+  via a synchronous user-message-count snapshot
+  (`pendingAutoPromptUserCount: Map<sessionId, number>`) taken at trigger
+  time, then ledgers the next user message whose index exceeds the snapshot
+  as automated. The ledgering branch runs on every tick — including busy
+  ticks — so the auto-prompt cannot mistakenly re-arm itself and re-fire.
+- **File-based debug log** at `/tmp/cache-timer-debug.log` capturing `tui()`
+  init and config-resolution events. Per-tick writes intentionally omitted
+  to keep the log near-free.
+
+### Notes
+- Configuration is intentionally a sidecar JSON file rather than inline in
+  `opencode.json`. Released opencode (v1.15.x) does not forward the second
+  tuple element of `["file://path", { ...options }]` plugin entries to TUI
+  plugins' `tui()` entrypoint, and `opencode.json` itself rejects unknown
+  top-level keys. An empirical survey of nine ecosystem plugins
+  (`opencode-dcp`, `opencode-vibeguard`, `opencode-sentry-monitor`,
+  `opencode-notificator`, `opencode-wakatime`, `opencode-morph-fast-apply`,
+  `opencode-helicone-session`, `opencode-md-table-formatter`, and the
+  official plugin template) found zero using the tuple-options mechanism;
+  the four config-heavy plugins all use sidecar JSON files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Cejda
+
+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,130 @@
+<div align="center">
+  <h1 align="center">cache-timer ⚡🕒</h1>
+
+  <p align="center">
+    <strong>Live prompt-cache countdown and pre-emptive cache-saving for <a href="https://opencode.ai">OpenCode</a></strong>
+  </p>
+
+  <p align="center">
+    <a href="https://www.npmjs.com/package/cache-timer">
+      <img src="https://img.shields.io/npm/v/cache-timer?color=9b59b6" alt="npm" />
+    </a>
+    <a href="./CHANGELOG.md">
+      <img src="https://img.shields.io/badge/changelog-Latest%20Changes-blue" alt="Changelog" />
+    </a>
+    <a href="./LICENSE">
+      <img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
+    </a>
+  </p>
+
+  <p align="center">
+    <a href="#what-is-it">What is it?</a> •
+    <a href="#-quick-start">Quick Start</a> •
+    <a href="#configuration">Configuration</a> •
+    <a href="./CHANGELOG.md">Changelog</a>
+  </p>
+</div>
+
+---
+
+## What is it?
+
+A TUI plugin that shows a live countdown to your prompt-cache expiry in the OpenCode session bar.
+
+The countdown indicator on the right side of your prompt:
+
+- 🔥 **Cache: HOT (05:00)** — healthy, time remaining
+- ⚠️ **Cache: HOT (00:59)** — under one minute, about to expire
+- ❄️ **Cache: COLD** — expired or model changed
+
+<p align="center">
+  <img src="docs/assets/hot_cache.png" alt="Hot cache, time remaining" width="420" />
+</p>
+<p align="center">
+  <img src="docs/assets/less_than_one_min.png" alt="Less than one minute remaining" width="420" />
+</p>
+<p align="center">
+  <img src="docs/assets/cold.png" alt="Cache cold" width="420" />
+</p>
+
+When your session is COLD, you have three choices:
+
+1. **Pay the cold-start tax** to continue your session, or
+2. **Start a new session** and rebuild context.
+3. **Drop the session entirely**. Move on. Might not be worth continuing this session at all.
+
+* On **cost**, starting fresh almost always wins — especially over 100k input tokens (see chart).
+* On **latency**, resuming wins — one up-front cold-write hit beats several `Read` round-trips in a fresh session. Worth paying if you're coming back to do one quick thing and don't need to maximize savings.
+
+The plugin also **optionally** helps make it easier to start a fresh session (off by default — see [Configuration](#configuration) to enable). If enabled, it fires a tiny "summarize progress" prompt 15 seconds before the cache goes cold, capturing a hot-read summary you can paste into a fresh session to skip the cold-start write tax of resuming the bloated original.
+
+## Why this exists
+
+When a 500k-token session goes cold, just *resuming* it costs **$3.12** in cold-write fees before you've done any new work. The auto-summary path — hot-read the existing context to produce a summary, paste it into a fresh session — costs **$0.69** under realistic assumptions (50k startup tokens, 1k summary paste, 5 file re-reads at 1000 LOC each). **Savings of ~$2.43 per timeout you would have otherwise resumed,** scaling linearly with session size:
+
+<p align="center">
+  <img src="docs/assets/cost-comparison.svg" alt="Cost of resuming a cold session vs. summary + fresh session — under realistic fresh-session assumptions the summary path saves ~$2.43 at 500k tokens and the gap widens with larger originals" width="700" />
+</p>
+
+> **When resume actually wins:** rarely on cost — you'd need to re-read essentially the entire original session in the fresh one for the math to flip, which almost never happens. The real argument for resuming is **latency**: a cold-write is a single up-front wall-clock hit, while a fresh session can spend the first several turns making `Read` calls to rebuild context the original already had. If you're coming back to do one quick thing and want to start immediately, just pay the tax if you can afford the extra cost.
+
+> **The auto-summary is OFF by default.** It requires explicit opt-in so the plugin never spends your tokens without permission. See [Configuration](#configuration) to enable it.
+
+## 🚀 Quick Start
+
+Add the package to the `plugin` array in your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["cache-timer"]
+}
+```
+
+OpenCode auto-installs npm plugins via Bun at startup. Restart OpenCode and you should see a green "Cache Timer loaded" toast.
+
+## Configuration
+
+The visual countdown works out of the box with no configuration. To enable the auto-summary, create `~/.config/opencode/cache-timer.json`:
+
+```json
+{
+  "enableAutoPrompt": true,
+  "durations": {
+    "claude": 300,
+    "gemini": 300,
+    "gpt": 300
+  }
+}
+```
+
+| Field              | Type    | Default                                       | Notes                                                                  |
+| ------------------ | ------- | --------------------------------------------- | ---------------------------------------------------------------------- |
+| `enableAutoPrompt` | boolean | `false`                                       | **Off by default.** Set `true` to send the auto-summary 15s pre-expiry |
+| `durations`        | object  | `{ claude: 300, gemini: 300, gpt: 300 }`      | Seconds, keyed by provider family (substring-matched against model id) |
+| `defaultDuration`  | number  | `300`                                         | Fallback when the model doesn't match any family                       |
+
+Per-project overrides live at `./.opencode/cache-timer.json` and win field-by-field over the global file. `"claude": 300` covers `claude-opus-4-7`, `claude-haiku-4-5`, `claude-3-5-sonnet`, etc.
+
+<details>
+<summary><b>Why a sidecar file instead of <code>opencode.json</code>?</b></summary>
+
+Opencode's `opencode.json` validates against a strict JSON schema with `additionalProperties: false` at the top level, so an inline `cacheTimer: { ... }` block would prevent opencode from starting. The documented `["file://path", { ...options }]` plugin-tuple form does not forward options to TUI plugins in released opencode (verified against v1.15.x; an empirical survey of nine ecosystem plugins found that zero of them use that mechanism). Sidecar JSON files are the de-facto idiomatic pattern, used by `opencode-dcp`, `opencode-vibeguard`, `opencode-sentry-monitor`, and `opencode-notificator`.
+
+</details>
+
+## 🛠️ Building from Source
+
+```bash
+npm install
+npm run build   # compiles cache-timer.tsx -> tui.js
+```
+
+---
+
+<div align="center">
+  <p>
+    <a href="https://github.com/ncejda-g2/opencode-cache-timer/issues">Report Bug</a> •
+    <a href="https://github.com/ncejda-g2/opencode-cache-timer/issues">Request Feature</a>
+  </p>
+</div>

package/cache-timer.tsx

@@ -0,0 +1,335 @@
+/** @jsxImportSource @opentui/solid */
+import { type JSX } from "@opentui/solid"
+import { createSignal, onCleanup } from "solid-js"
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { appendFileSync, readFileSync, existsSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+// DEBUG: file-based logger. Useful when toast stacking obscures init details
+// and as a permanent troubleshooting aid for the cache-timer config loader.
+// Safe to leave in; never throws (writes silently to /tmp).
+const DEBUG_LOG_PATH = "/tmp/cache-timer-debug.log";
+function debugLog(line: string): void {
+  try {
+    appendFileSync(DEBUG_LOG_PATH, `[${new Date().toISOString()}] ${line}\n`);
+  } catch {
+    // Intentionally swallow; debug instrumentation must never break the plugin.
+  }
+}
+
+// Shape of the optional sidecar config file users can drop next to opencode.json.
+interface CacheTimerConfig {
+  enableAutoPrompt?: boolean;
+  defaultDuration?: number;
+  durations?: Record<string, number>;
+}
+
+// Read cache-timer config from a sidecar JSON file. Surveys of real opencode
+// plugins (opencode-dcp, opencode-vibeguard, opencode-sentry-monitor,
+// opencode-notificator, etc.) confirm that the inline `["file://path", {...}]`
+// tuple form in opencode.json's `plugin` array does NOT actually forward the
+// options object to TUI plugins in released opencode (1.15.x). Every config-
+// heavy plugin in the ecosystem instead reads its own sidecar file with the
+// plugin's slug as the filename. We follow that established pattern.
+//
+// Search order matches opencode's own project-then-global precedence:
+//   1. ./.opencode/cache-timer.json   (project override)
+//   2. ~/.config/opencode/cache-timer.json  (global)
+function loadCacheTimerConfig(): CacheTimerConfig {
+  const candidatePaths = [
+    join(process.cwd(), ".opencode", "cache-timer.json"),
+    join(homedir(), ".config", "opencode", "cache-timer.json"),
+  ];
+
+  const merged: CacheTimerConfig = {};
+  for (const path of candidatePaths) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readFileSync(path, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        debugLog(`loaded cache-timer config from ${path}: ${JSON.stringify(parsed)}`);
+        // Project-level (encountered first) wins over global for scalar fields.
+        if (merged.enableAutoPrompt === undefined && typeof parsed.enableAutoPrompt === "boolean") {
+          merged.enableAutoPrompt = parsed.enableAutoPrompt;
+        }
+        if (merged.defaultDuration === undefined && typeof parsed.defaultDuration === "number") {
+          merged.defaultDuration = parsed.defaultDuration;
+        }
+        // For the durations map, project values win per-key.
+        if (parsed.durations && typeof parsed.durations === "object") {
+          merged.durations = { ...parsed.durations, ...(merged.durations ?? {}) };
+        }
+      }
+    } catch (err) {
+      debugLog(`failed to read/parse ${path}: ${String(err)}`);
+    }
+  }
+  return merged;
+}
+
+// Default model cache durations in seconds, keyed by *provider family*.
+// The matcher in getCacheDuration() does a case-insensitive substring match
+// against the model id, so a single family key (e.g. "claude") covers every
+// variant of that family (claude-3-5-sonnet, claude-opus-4-7, claude-haiku-4-5,
+// etc.). Users override per-family via opencode.json `options.durations`.
+let cacheDurations: Record<string, number> = {
+  "claude": 300,
+  "gemini": 300,
+  "gpt": 300,
+};
+let defaultDuration = 300; // Fallback to 5 minutes (300s)
+
+// Helper to determine cache duration for a specific model ID
+function getCacheDuration(modelId: string | undefined): number {
+  if (!modelId) return defaultDuration;
+  
+  const normalizedId = modelId.toLowerCase();
+  for (const [key, duration] of Object.entries(cacheDurations)) {
+    if (normalizedId.includes(key)) {
+      return duration;
+    }
+  }
+  return defaultDuration;
+}
+
+// Helper to format remaining seconds as MM:SS
+function formatTimeText(totalSeconds: number): string {
+  const minutes = Math.floor(totalSeconds / 60)
+  const calculatedSeconds = Math.floor(totalSeconds % 60)
+  return `${String(minutes).padStart(2, "0")}:${String(calculatedSeconds).padStart(2, "0")}`
+}
+
+// Module-level session-keyed states to ensure absolute isolation across multiple sessions
+const triggeredSessions = new Set<string>();
+const healthySessions = new Set<string>();
+const lastUserMsgIds = new Map<string, string>();
+const autoPromptIds = new Set<string>(); // Immutable ledger of all generated auto-prompt message IDs
+
+// When we fire an auto-summary, we record the user-message count of the session
+// AT trigger time. The next user message that appears beyond this count is
+// definitionally the auto-prompt itself, so we ledger it as auto regardless of
+// whether the session was "busy" during ledgering or whether the prompt API
+// promise has already resolved. This eliminates the race where the auto-prompt's
+// user-message id was never ledgered (because ticks during busy state were
+// skipped) and was then incorrectly treated as a human input on the next tick,
+// causing the trigger to re-arm and the summary to fire again in an infinite loop.
+const pendingAutoPromptUserCount = new Map<string, number>();
+
+const tui: TuiPlugin = async (api, _options, _meta) => {
+  // Auto-prompt is opt-in. Defaults stay safe.
+  let enableAutoPrompt = false;
+
+  debugLog("=== tui() invoked ===");
+  const userConfig = loadCacheTimerConfig();
+  debugLog(`resolved userConfig=${JSON.stringify(userConfig)}`);
+
+  if (typeof userConfig.defaultDuration === "number") {
+    defaultDuration = userConfig.defaultDuration;
+  }
+  if (userConfig.durations) {
+    cacheDurations = { ...cacheDurations, ...userConfig.durations };
+  }
+  if (typeof userConfig.enableAutoPrompt === "boolean") {
+    enableAutoPrompt = userConfig.enableAutoPrompt;
+  }
+
+  debugLog(`post-merge cacheDurations=${JSON.stringify(cacheDurations)} enableAutoPrompt=${enableAutoPrompt} defaultDuration=${defaultDuration}`);
+
+  api.ui.toast({
+    variant: "success",
+    title: "Cache Timer loaded",
+    duration: 3000,
+  });
+
+  api.slots.register({
+    slots: {
+      session_prompt_right(ctx, value) {
+        // Resolve initial active model duration
+        const session_id = value?.session_id;
+        const messagesOnMount = api.state.session.messages(session_id);
+        let initialDuration = defaultDuration;
+        if (messagesOnMount && messagesOnMount.length > 0) {
+          const lastMsg = messagesOnMount[messagesOnMount.length - 1];
+          const modelId = lastMsg.role === "user" ? lastMsg.model?.modelID : lastMsg.modelID;
+          initialDuration = getCacheDuration(modelId);
+        }
+
+        const [timeText, setTimeText] = createSignal(`Cache: HOT (${formatTimeText(initialDuration)})`)
+        const [color, setColor] = createSignal("#EF4444") // Red (HOT)
+
+        // Local interval ticker that directly updates this component's reactive signals.
+        // This guarantees the UI text updates flawlessly and never freezes.
+        const interval = setInterval(() => {
+          if (!session_id) return
+
+          try {
+            const sessionStatus = api.state.session.status(session_id);
+            const messages = api.state.session.messages(session_id);
+
+            // User-message ledgering MUST run every tick, including while the session
+            // is busy. If we skip it during busy, the auto-prompt's user-message id
+            // never gets recorded as "auto", and the next non-busy tick sees a "new"
+            // user message it treats as human, clearing the trigger lock and causing
+            // the auto-summary to fire again on the next cycle (infinite loop).
+            if (messages && messages.length > 0) {
+              const userMessages = messages.filter(m => m.role === "user");
+              if (userMessages.length > 0) {
+                const lastUserMsg = userMessages[userMessages.length - 1];
+                const prevUserMsgId = lastUserMsgIds.get(session_id);
+                if (lastUserMsg.id && prevUserMsgId !== lastUserMsg.id) {
+                  lastUserMsgIds.set(session_id, lastUserMsg.id);
+
+                  // Is this new user message ours (the auto-prompt) or a human's?
+                  // It's ours iff:
+                  //   (a) we have a pending auto-prompt snapshot for this session, AND
+                  //   (b) the current user-message count exceeds that snapshot.
+                  const expectedAutoCount = pendingAutoPromptUserCount.get(session_id);
+                  const isAutoPrompt =
+                    expectedAutoCount !== undefined &&
+                    userMessages.length > expectedAutoCount;
+
+                  if (isAutoPrompt) {
+                    autoPromptIds.add(lastUserMsg.id);
+                    // Consume the pending snapshot; further user messages beyond
+                    // this point are real humans and should re-arm the trigger.
+                    pendingAutoPromptUserCount.delete(session_id);
+                  } else if (prevUserMsgId && !autoPromptIds.has(lastUserMsg.id)) {
+                    // A human sent a fresh prompt: re-arm the auto-summary trigger.
+                    triggeredSessions.delete(session_id);
+                  }
+                }
+              }
+            }
+
+            // If the session is actively processing or streaming, freeze visual countdown and display "Busy"
+            if (sessionStatus?.type === "busy") {
+              setTimeText("Cache: HOT (Busy)")
+              setColor("#EF4444") // Red (HOT)
+              return
+            }
+
+            if (!messages || messages.length === 0) {
+              setTimeText("Cache: COLD")
+              setColor("#3B82F6") // Blue (COLD)
+              return
+            }
+
+            const lastMsg = messages[messages.length - 1]
+            const currentModelId = lastMsg.role === "user" ? lastMsg.model?.modelID : lastMsg.modelID;
+            const totalDurationSec = getCacheDuration(currentModelId);
+
+            // Robustly resolve the most recent valid timestamp in the session history (handles active streaming)
+            let lastTime: number | undefined;
+            for (let i = messages.length - 1; i >= 0; i--) {
+              const msg = messages[i];
+              const t = msg.time?.completed ?? msg.time?.created;
+              if (t) {
+                lastTime = t;
+                break;
+              }
+            }
+
+            if (!lastTime) {
+              setTimeText(`Cache: HOT (${formatTimeText(totalDurationSec)})`)
+              setColor("#EF4444") // Red (HOT)
+              return
+            }
+
+            const elapsedMs = Date.now() - lastTime
+            const remainingMs = totalDurationSec * 1000 - elapsedMs
+
+            if (remainingMs <= 0) {
+              setTimeText("Cache: COLD")
+              setColor("#3B82F6") // Blue (COLD)
+            } else {
+              const minutes = Math.floor(remainingMs / 1000 / 60)
+              const seconds = Math.floor((remainingMs / 1000) % 60)
+              const formattedTime = `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`
+              setTimeText(`Cache: HOT (${formattedTime})`)
+              
+              // Dynamic color feedback: yellow when under 1 minute (almost cold)
+              if (remainingMs < 60 * 1000) {
+                setColor("#FBBF24") // Yellow (WARNING - almost cold)
+              } else {
+                setColor("#EF4444") // Red (HOT)
+              }
+
+              // Arm the trigger when the timer is healthy (above trigger zone)
+              if (remainingMs > 15 * 1000) {
+                healthySessions.add(session_id);
+              }
+
+              // Trigger auto-compaction 15 seconds before cache expires to utilize HOT cache.
+              // Only triggers if explicitly opted-in AND we have seen a healthy state this cycle (no stale triggers).
+              if (enableAutoPrompt && healthySessions.has(session_id) && remainingMs <= 15 * 1000 && remainingMs > 0 && !triggeredSessions.has(session_id)) {
+                triggeredSessions.add(session_id);
+                healthySessions.delete(session_id); // Require a new healthy cycle reset before triggering again
+
+                // Snapshot the user-message count BEFORE the auto-prompt lands.
+                // The next user message that appears beyond this count is
+                // definitionally our auto-prompt and will be ledgered as auto by
+                // the user-message branch above (which now runs every tick,
+                // including during the busy state that follows this call).
+                const userMsgCountAtTrigger = messages.filter(m => m.role === "user").length;
+                pendingAutoPromptUserCount.set(session_id, userMsgCountAtTrigger);
+
+                api.ui.toast({
+                  variant: "warning",
+                  title: "Cache Expiring",
+                  message: "Cache expiring in 15s! Automatically generating summary to preserve hot cache.",
+                  duration: 5000,
+                });
+
+                api.client.session.prompt({
+                  sessionID: session_id,
+                  parts: [{
+                    type: "text",
+                    text: "Summarize our progress and next steps. Be brief."
+                  }]
+                }).then(() => {
+                  api.ui.toast({
+                    variant: "success",
+                    title: "Summary Triggered",
+                    message: "Successfully requested auto-summary to preserve prompt cache.",
+                    duration: 5000,
+                  });
+                }).catch((err) => {
+                  // Roll back the snapshot if the prompt was rejected outright;
+                  // no auto-prompt user message will ever land for this trigger.
+                  pendingAutoPromptUserCount.delete(session_id);
+                  api.ui.toast({
+                    variant: "error",
+                    title: "Summary Request Failed",
+                    message: String(err?.message || err),
+                    duration: 10000,
+                  });
+                });
+              }
+            }
+          } catch (err) {
+            console.error("[Cache-Timer Error]", err);
+          }
+        }, 1000)
+
+        onCleanup(() => {
+          clearInterval(interval)
+        })
+
+        return (
+          <box paddingLeft={1} paddingRight={1}>
+            <text fg={color()}><b>{timeText()}</b></text>
+          </box>
+        )
+      }
+    }
+  })
+}
+
+const plugin: TuiPluginModule & { id: string } = {
+  id: "cache-timer",
+  tui,
+}
+
+export default plugin

package/index.js

@@ -0,0 +1,12 @@
+const server = async (api, options) => {
+  // Return an empty hooks object to satisfy the backend loader constraint
+  return {};
+};
+
+const plugin = {
+  id: "cache-timer",
+  server,
+};
+
+export default plugin;
+export { server };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cache-timer",
+  "version": "1.0.0",
+  "description": "Pre-emptive prompt-cache saving extension for OpenCode",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./tui": "./tui.js"
+  },
+  "files": [
+    "index.js",
+    "tui.js",
+    "cache-timer.tsx",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node compile_plugin.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ncejda-g2/opencode-cache-timer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ncejda-g2/opencode-cache-timer/issues"
+  },
+  "homepage": "https://github.com/ncejda-g2/opencode-cache-timer#readme",
+  "author": "Nicholas Cejda <ncejda@g2.com>",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "cache",
+    "claude",
+    "gemini",
+    "gpt",
+    "prompt-cache",
+    "tui"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "babel-preset-solid": "^1.8.0"
+  }
+}

package/tui.js

@@ -0,0 +1,320 @@
+import { effect as _$effect } from "@opentui/solid";
+import { insertNode as _$insertNode } from "@opentui/solid";
+import { insert as _$insert } from "@opentui/solid";
+import { setProp as _$setProp } from "@opentui/solid";
+import { createElement as _$createElement } from "@opentui/solid";
+/** @jsxImportSource @opentui/solid */
+
+import { createSignal, onCleanup } from "solid-js";
+import { appendFileSync, readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// DEBUG: file-based logger. Useful when toast stacking obscures init details
+// and as a permanent troubleshooting aid for the cache-timer config loader.
+// Safe to leave in; never throws (writes silently to /tmp).
+const DEBUG_LOG_PATH = "/tmp/cache-timer-debug.log";
+function debugLog(line) {
+  try {
+    appendFileSync(DEBUG_LOG_PATH, `[${new Date().toISOString()}] ${line}\n`);
+  } catch {
+    // Intentionally swallow; debug instrumentation must never break the plugin.
+  }
+}
+
+// Shape of the optional sidecar config file users can drop next to opencode.json.
+
+// Read cache-timer config from a sidecar JSON file. Surveys of real opencode
+// plugins (opencode-dcp, opencode-vibeguard, opencode-sentry-monitor,
+// opencode-notificator, etc.) confirm that the inline `["file://path", {...}]`
+// tuple form in opencode.json's `plugin` array does NOT actually forward the
+// options object to TUI plugins in released opencode (1.15.x). Every config-
+// heavy plugin in the ecosystem instead reads its own sidecar file with the
+// plugin's slug as the filename. We follow that established pattern.
+//
+// Search order matches opencode's own project-then-global precedence:
+//   1. ./.opencode/cache-timer.json   (project override)
+//   2. ~/.config/opencode/cache-timer.json  (global)
+function loadCacheTimerConfig() {
+  const candidatePaths = [join(process.cwd(), ".opencode", "cache-timer.json"), join(homedir(), ".config", "opencode", "cache-timer.json")];
+  const merged = {};
+  for (const path of candidatePaths) {
+    if (!existsSync(path)) continue;
+    try {
+      const raw = readFileSync(path, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        debugLog(`loaded cache-timer config from ${path}: ${JSON.stringify(parsed)}`);
+        // Project-level (encountered first) wins over global for scalar fields.
+        if (merged.enableAutoPrompt === undefined && typeof parsed.enableAutoPrompt === "boolean") {
+          merged.enableAutoPrompt = parsed.enableAutoPrompt;
+        }
+        if (merged.defaultDuration === undefined && typeof parsed.defaultDuration === "number") {
+          merged.defaultDuration = parsed.defaultDuration;
+        }
+        // For the durations map, project values win per-key.
+        if (parsed.durations && typeof parsed.durations === "object") {
+          merged.durations = {
+            ...parsed.durations,
+            ...(merged.durations ?? {})
+          };
+        }
+      }
+    } catch (err) {
+      debugLog(`failed to read/parse ${path}: ${String(err)}`);
+    }
+  }
+  return merged;
+}
+
+// Default model cache durations in seconds, keyed by *provider family*.
+// The matcher in getCacheDuration() does a case-insensitive substring match
+// against the model id, so a single family key (e.g. "claude") covers every
+// variant of that family (claude-3-5-sonnet, claude-opus-4-7, claude-haiku-4-5,
+// etc.). Users override per-family via opencode.json `options.durations`.
+let cacheDurations = {
+  "claude": 300,
+  "gemini": 300,
+  "gpt": 300
+};
+let defaultDuration = 300; // Fallback to 5 minutes (300s)
+
+// Helper to determine cache duration for a specific model ID
+function getCacheDuration(modelId) {
+  if (!modelId) return defaultDuration;
+  const normalizedId = modelId.toLowerCase();
+  for (const [key, duration] of Object.entries(cacheDurations)) {
+    if (normalizedId.includes(key)) {
+      return duration;
+    }
+  }
+  return defaultDuration;
+}
+
+// Helper to format remaining seconds as MM:SS
+function formatTimeText(totalSeconds) {
+  const minutes = Math.floor(totalSeconds / 60);
+  const calculatedSeconds = Math.floor(totalSeconds % 60);
+  return `${String(minutes).padStart(2, "0")}:${String(calculatedSeconds).padStart(2, "0")}`;
+}
+
+// Module-level session-keyed states to ensure absolute isolation across multiple sessions
+const triggeredSessions = new Set();
+const healthySessions = new Set();
+const lastUserMsgIds = new Map();
+const autoPromptIds = new Set(); // Immutable ledger of all generated auto-prompt message IDs
+
+// When we fire an auto-summary, we record the user-message count of the session
+// AT trigger time. The next user message that appears beyond this count is
+// definitionally the auto-prompt itself, so we ledger it as auto regardless of
+// whether the session was "busy" during ledgering or whether the prompt API
+// promise has already resolved. This eliminates the race where the auto-prompt's
+// user-message id was never ledgered (because ticks during busy state were
+// skipped) and was then incorrectly treated as a human input on the next tick,
+// causing the trigger to re-arm and the summary to fire again in an infinite loop.
+const pendingAutoPromptUserCount = new Map();
+const tui = async (api, _options, _meta) => {
+  // Auto-prompt is opt-in. Defaults stay safe.
+  let enableAutoPrompt = false;
+  debugLog("=== tui() invoked ===");
+  const userConfig = loadCacheTimerConfig();
+  debugLog(`resolved userConfig=${JSON.stringify(userConfig)}`);
+  if (typeof userConfig.defaultDuration === "number") {
+    defaultDuration = userConfig.defaultDuration;
+  }
+  if (userConfig.durations) {
+    cacheDurations = {
+      ...cacheDurations,
+      ...userConfig.durations
+    };
+  }
+  if (typeof userConfig.enableAutoPrompt === "boolean") {
+    enableAutoPrompt = userConfig.enableAutoPrompt;
+  }
+  debugLog(`post-merge cacheDurations=${JSON.stringify(cacheDurations)} enableAutoPrompt=${enableAutoPrompt} defaultDuration=${defaultDuration}`);
+  api.ui.toast({
+    variant: "success",
+    title: "Cache Timer loaded",
+    duration: 3000
+  });
+  api.slots.register({
+    slots: {
+      session_prompt_right(ctx, value) {
+        // Resolve initial active model duration
+        const session_id = value?.session_id;
+        const messagesOnMount = api.state.session.messages(session_id);
+        let initialDuration = defaultDuration;
+        if (messagesOnMount && messagesOnMount.length > 0) {
+          const lastMsg = messagesOnMount[messagesOnMount.length - 1];
+          const modelId = lastMsg.role === "user" ? lastMsg.model?.modelID : lastMsg.modelID;
+          initialDuration = getCacheDuration(modelId);
+        }
+        const [timeText, setTimeText] = createSignal(`Cache: HOT (${formatTimeText(initialDuration)})`);
+        const [color, setColor] = createSignal("#EF4444"); // Red (HOT)
+
+        // Local interval ticker that directly updates this component's reactive signals.
+        // This guarantees the UI text updates flawlessly and never freezes.
+        const interval = setInterval(() => {
+          if (!session_id) return;
+          try {
+            const sessionStatus = api.state.session.status(session_id);
+            const messages = api.state.session.messages(session_id);
+
+            // User-message ledgering MUST run every tick, including while the session
+            // is busy. If we skip it during busy, the auto-prompt's user-message id
+            // never gets recorded as "auto", and the next non-busy tick sees a "new"
+            // user message it treats as human, clearing the trigger lock and causing
+            // the auto-summary to fire again on the next cycle (infinite loop).
+            if (messages && messages.length > 0) {
+              const userMessages = messages.filter(m => m.role === "user");
+              if (userMessages.length > 0) {
+                const lastUserMsg = userMessages[userMessages.length - 1];
+                const prevUserMsgId = lastUserMsgIds.get(session_id);
+                if (lastUserMsg.id && prevUserMsgId !== lastUserMsg.id) {
+                  lastUserMsgIds.set(session_id, lastUserMsg.id);
+
+                  // Is this new user message ours (the auto-prompt) or a human's?
+                  // It's ours iff:
+                  //   (a) we have a pending auto-prompt snapshot for this session, AND
+                  //   (b) the current user-message count exceeds that snapshot.
+                  const expectedAutoCount = pendingAutoPromptUserCount.get(session_id);
+                  const isAutoPrompt = expectedAutoCount !== undefined && userMessages.length > expectedAutoCount;
+                  if (isAutoPrompt) {
+                    autoPromptIds.add(lastUserMsg.id);
+                    // Consume the pending snapshot; further user messages beyond
+                    // this point are real humans and should re-arm the trigger.
+                    pendingAutoPromptUserCount.delete(session_id);
+                  } else if (prevUserMsgId && !autoPromptIds.has(lastUserMsg.id)) {
+                    // A human sent a fresh prompt: re-arm the auto-summary trigger.
+                    triggeredSessions.delete(session_id);
+                  }
+                }
+              }
+            }
+
+            // If the session is actively processing or streaming, freeze visual countdown and display "Busy"
+            if (sessionStatus?.type === "busy") {
+              setTimeText("Cache: HOT (Busy)");
+              setColor("#EF4444"); // Red (HOT)
+              return;
+            }
+            if (!messages || messages.length === 0) {
+              setTimeText("Cache: COLD");
+              setColor("#3B82F6"); // Blue (COLD)
+              return;
+            }
+            const lastMsg = messages[messages.length - 1];
+            const currentModelId = lastMsg.role === "user" ? lastMsg.model?.modelID : lastMsg.modelID;
+            const totalDurationSec = getCacheDuration(currentModelId);
+
+            // Robustly resolve the most recent valid timestamp in the session history (handles active streaming)
+            let lastTime;
+            for (let i = messages.length - 1; i >= 0; i--) {
+              const msg = messages[i];
+              const t = msg.time?.completed ?? msg.time?.created;
+              if (t) {
+                lastTime = t;
+                break;
+              }
+            }
+            if (!lastTime) {
+              setTimeText(`Cache: HOT (${formatTimeText(totalDurationSec)})`);
+              setColor("#EF4444"); // Red (HOT)
+              return;
+            }
+            const elapsedMs = Date.now() - lastTime;
+            const remainingMs = totalDurationSec * 1000 - elapsedMs;
+            if (remainingMs <= 0) {
+              setTimeText("Cache: COLD");
+              setColor("#3B82F6"); // Blue (COLD)
+            } else {
+              const minutes = Math.floor(remainingMs / 1000 / 60);
+              const seconds = Math.floor(remainingMs / 1000 % 60);
+              const formattedTime = `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+              setTimeText(`Cache: HOT (${formattedTime})`);
+
+              // Dynamic color feedback: yellow when under 1 minute (almost cold)
+              if (remainingMs < 60 * 1000) {
+                setColor("#FBBF24"); // Yellow (WARNING - almost cold)
+              } else {
+                setColor("#EF4444"); // Red (HOT)
+              }
+
+              // Arm the trigger when the timer is healthy (above trigger zone)
+              if (remainingMs > 15 * 1000) {
+                healthySessions.add(session_id);
+              }
+
+              // Trigger auto-compaction 15 seconds before cache expires to utilize HOT cache.
+              // Only triggers if explicitly opted-in AND we have seen a healthy state this cycle (no stale triggers).
+              if (enableAutoPrompt && healthySessions.has(session_id) && remainingMs <= 15 * 1000 && remainingMs > 0 && !triggeredSessions.has(session_id)) {
+                triggeredSessions.add(session_id);
+                healthySessions.delete(session_id); // Require a new healthy cycle reset before triggering again
+
+                // Snapshot the user-message count BEFORE the auto-prompt lands.
+                // The next user message that appears beyond this count is
+                // definitionally our auto-prompt and will be ledgered as auto by
+                // the user-message branch above (which now runs every tick,
+                // including during the busy state that follows this call).
+                const userMsgCountAtTrigger = messages.filter(m => m.role === "user").length;
+                pendingAutoPromptUserCount.set(session_id, userMsgCountAtTrigger);
+                api.ui.toast({
+                  variant: "warning",
+                  title: "Cache Expiring",
+                  message: "Cache expiring in 15s! Automatically generating summary to preserve hot cache.",
+                  duration: 5000
+                });
+                api.client.session.prompt({
+                  sessionID: session_id,
+                  parts: [{
+                    type: "text",
+                    text: "Summarize our progress and next steps. Be brief."
+                  }]
+                }).then(() => {
+                  api.ui.toast({
+                    variant: "success",
+                    title: "Summary Triggered",
+                    message: "Successfully requested auto-summary to preserve prompt cache.",
+                    duration: 5000
+                  });
+                }).catch(err => {
+                  // Roll back the snapshot if the prompt was rejected outright;
+                  // no auto-prompt user message will ever land for this trigger.
+                  pendingAutoPromptUserCount.delete(session_id);
+                  api.ui.toast({
+                    variant: "error",
+                    title: "Summary Request Failed",
+                    message: String(err?.message || err),
+                    duration: 10000
+                  });
+                });
+              }
+            }
+          } catch (err) {
+            console.error("[Cache-Timer Error]", err);
+          }
+        }, 1000);
+        onCleanup(() => {
+          clearInterval(interval);
+        });
+        return (() => {
+          var _el$ = _$createElement("box"),
+            _el$2 = _$createElement("text"),
+            _el$3 = _$createElement("b");
+          _$insertNode(_el$, _el$2);
+          _$setProp(_el$, "paddingLeft", 1);
+          _$setProp(_el$, "paddingRight", 1);
+          _$insertNode(_el$2, _el$3);
+          _$insert(_el$3, timeText);
+          _$effect(_$p => _$setProp(_el$2, "fg", color(), _$p));
+          return _el$;
+        })();
+      }
+    }
+  });
+};
+const plugin = {
+  id: "cache-timer",
+  tui
+};
+export default plugin;