@vikrant82/opencode-cache-keepalive 0.1.4 → 0.1.6

package/lib/state.ts

@@ -12,6 +12,40 @@ export type PingRecord = {
     output: number
 }
 
+/**
+ * Request settings of the last real user turn. A ping must replay them exactly:
+ * a prompt without explicit settings runs as opencode's default agent with no
+ * variant, which changes the request shape (missing the cache) and overwrites
+ * the session's persisted agent/model/variant.
+ */
+export type PingRequest = {
+    agent?: string
+    providerID: string
+    modelID: string
+    variant?: string
+}
+
+/** Bookkeeping for the ping request currently in flight. */
+export type InflightPing = {
+    /** Epoch ms the ping attempt began (before the pre-flight status check). */
+    startedAt: number
+    /** The prompt request has been issued. */
+    sent: boolean
+    /** The ping's own user message, identified by its ping-token text part. */
+    messageID?: string
+    /**
+     * New user messages seen during the ping whose text has not yet been observed.
+     * Each is classified by its first text part: the ping token marks our own
+     * message, anything else a real turn.
+     */
+    pending: Map<string, unknown>
+    /**
+     * A real user message appeared while the ping was in flight. opencode joins such
+     * a prompt to the running ping loop, so the rest of the run is real work.
+     */
+    interrupted: boolean
+}
+
 /** Live per-session bookkeeping held by the server plugin. */
 export type SessionKeepalive = {
     sessionID: string
@@ -30,15 +64,20 @@ export type SessionKeepalive = {
     pingsSent: number
     /** A real turn is currently running. */
     busy: boolean
-    /** Epoch ms when `busy` was last set; used as a stuck-busy timeout backstop. */
-    busySince?: number
     /** A keepalive ping is currently in flight. */
     warming: boolean
+    /** The in-flight ping; set exactly while `warming` is true. */
+    ping?: InflightPing
+    /** ID and creation time of the newest user message seen, to tell new turns from re-emitted old messages. */
+    lastUserID?: string
+    lastUserAt?: number
+    /** Settings of the last real user turn, replayed by pings. */
+    request?: PingRequest
     /** Within the warm window and actively scheduling pings. */
     active: boolean
     /** True while `armWindow` is resolving session metadata (async guard). */
     arming?: boolean
-    /** Epoch ms of the last ping; retained only to ignore its late events. */
+    /** Epoch ms the last sent ping finished; ignores its late events and marks the last cache touch. */
     lastPingAt?: number
     lastPing?: PingRecord
 }
@@ -72,18 +111,25 @@ export class KeepaliveStore {
     private readonly sessions = new Map<string, SessionKeepalive>()
     private writeQueue: Promise<void> = Promise.resolve()
     private enabled: boolean
+    private intervalMs: number
 
     constructor(
         private readonly config: KeepaliveConfig,
         private readonly directory: string,
     ) {
         this.enabled = config.enabled
+        this.intervalMs = config.intervalMs
     }
 
     setEnabled(enabled: boolean): void {
         this.enabled = enabled
     }
 
+    /** Effective ping interval (runtime override or config) reported to the TUI. */
+    setIntervalMs(intervalMs: number): void {
+        this.intervalMs = intervalMs
+    }
+
     get(sessionID: string): SessionKeepalive | undefined {
         return this.sessions.get(sessionID)
     }
@@ -115,13 +161,16 @@ export class KeepaliveStore {
         return [...this.sessions.values()]
     }
 
-    /** Atomically persist a lean snapshot for the TUI. Never throws to callers. */
-    persist(): void {
+    /**
+     * Atomically persist a lean snapshot for the TUI. Never throws or rejects; the
+     * returned promise resolves once this snapshot and every earlier one are written.
+     */
+    persist(): Promise<void> {
         const snapshot: PersistedState = {
             version: 1,
             updatedAt: Date.now(),
             enabled: this.enabled,
-            intervalMs: this.config.intervalMs,
+            intervalMs: this.intervalMs,
             windowMs: this.config.windowMs,
             sessions: Object.fromEntries(
                 this.all().map((s) => [
@@ -133,7 +182,7 @@ export class KeepaliveStore {
                         idleSince: s.idleSince,
                         windowEndsAt: s.windowEndsAt,
                         nextPingAt: s.nextPingAt,
-                        intervalMs: this.config.intervalMs,
+                        intervalMs: this.intervalMs,
                         pingsSent: s.pingsSent,
                         busy: s.busy,
                         warming: s.warming,
@@ -146,6 +195,7 @@ export class KeepaliveStore {
 
         const write = () => atomicWrite(stateFilePath(this.directory), JSON.stringify(snapshot))
         this.writeQueue = this.writeQueue.then(write, write)
+        return this.writeQueue
     }
 }
 

package/lib/tui/commands.tsx

@@ -0,0 +1,184 @@
+/** @jsxImportSource @opentui/solid */
+
+import type { TuiDialogSelectOption, TuiPluginApi } from "@opencode-ai/plugin/tui"
+import { readFileSync } from "node:fs"
+import {
+    type ControlPatch,
+    isValidInterval,
+    MAX_INTERVAL_MS,
+    MIN_INTERVAL_MS,
+    readControl,
+    updateControl,
+} from "../control"
+import { stateFilePath } from "../paths"
+import { formatDuration, parseDuration } from "./format"
+
+/** Interval presets matched to common provider prompt-cache lifetimes. */
+const INTERVAL_PRESETS: { ms: number; description: string }[] = [
+    { ms: 270_000, description: "5-minute caches (Claude / Anthropic)" },
+    { ms: 1_700_000, description: "30-minute caches (GPT / OpenAI)" },
+]
+
+type IntervalChoice = number | "config" | "custom"
+
+/**
+ * Register the keepalive commands. The control file is scoped per directory, so
+ * toggling keepalive or changing its interval here only affects this project's
+ * server plugin — not other open opencode sessions. The server polls the file
+ * every second, so changes apply without a restart.
+ */
+export function registerKeepaliveCommands(api: TuiPluginApi): void {
+    // Read lazily: state paths may not be populated at registration time.
+    const directory = () => api.state.path.directory
+
+    const apply = async (
+        patch: ControlPatch,
+        message: string,
+        variant: "success" | "warning" | "info",
+    ) => {
+        try {
+            await updateControl(directory(), patch)
+            api.ui.toast({ variant, title: "Cache keepalive", message })
+        } catch (error) {
+            api.ui.toast({
+                variant: "error",
+                title: "Cache keepalive",
+                message: error instanceof Error ? error.message : String(error),
+            })
+        }
+    }
+
+    const setEnabled = (enabled: boolean) =>
+        apply({ enabled }, enabled ? "Enabled" : "Disabled", enabled ? "success" : "warning")
+
+    const setPingInterval = (intervalMs: number | null) =>
+        apply(
+            { intervalMs },
+            intervalMs === null
+                ? "Ping interval reset to the plugin default"
+                : `Ping interval ${formatDuration(intervalMs)}`,
+            "info",
+        )
+
+    const showCustomInterval = (current: number | undefined) => {
+        api.ui.dialog.replace(() => (
+            <api.ui.DialogPrompt
+                title="Custom ping interval"
+                placeholder="e.g. 4m30s, 270s, 12m (a bare number means minutes)"
+                value={current ? formatDuration(current).replace(/ /g, "") : undefined}
+                onConfirm={(raw) => {
+                    const ms = parseDuration(raw)
+                    if (ms === undefined || !isValidInterval(ms)) {
+                        api.ui.toast({
+                            variant: "error",
+                            title: "Cache keepalive",
+                            message: `Enter a duration between ${formatDuration(MIN_INTERVAL_MS)} and ${formatDuration(MAX_INTERVAL_MS)}, e.g. 4m30s`,
+                        })
+                        return
+                    }
+                    api.ui.dialog.clear()
+                    void setPingInterval(ms)
+                }}
+                onCancel={() => api.ui.dialog.clear()}
+            />
+        ))
+    }
+
+    const showInterval = () => {
+        const override = readControl(directory())?.intervalMs
+        const options: TuiDialogSelectOption<IntervalChoice>[] = INTERVAL_PRESETS.map((preset) => ({
+            title: formatDuration(preset.ms),
+            value: preset.ms,
+            description: preset.description,
+        }))
+        if (override !== undefined && !INTERVAL_PRESETS.some((preset) => preset.ms === override)) {
+            options.push({
+                title: formatDuration(override),
+                value: override,
+                description: "Current custom interval",
+            })
+        }
+        options.push(
+            {
+                title: "Custom…",
+                value: "custom",
+                description: "Enter a duration, e.g. 4m30s or 12m",
+            },
+            {
+                title: "Plugin default",
+                value: "config",
+                description: "Clear the override and use the configured intervalMs",
+            },
+        )
+
+        api.ui.dialog.replace(() => (
+            <api.ui.DialogSelect
+                title="Keepalive ping interval"
+                options={options}
+                current={override ?? "config"}
+                onSelect={(option) => {
+                    const choice = option.value as IntervalChoice
+                    if (choice === "custom") {
+                        showCustomInterval(override)
+                        return
+                    }
+                    api.ui.dialog.clear()
+                    void setPingInterval(choice === "config" ? null : choice)
+                }}
+            />
+        ))
+    }
+
+    api.keymap.registerLayer({
+        commands: [
+            {
+                name: "keepalive.toggle",
+                title: "Toggle cache keepalive",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-toggle",
+                run: () => setEnabled(!currentEnabled(directory())),
+            },
+            {
+                name: "keepalive.on",
+                title: "Enable cache keepalive",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-on",
+                run: () => setEnabled(true),
+            },
+            {
+                name: "keepalive.off",
+                title: "Disable cache keepalive",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-off",
+                run: () => setEnabled(false),
+            },
+            {
+                name: "keepalive.interval",
+                title: "Set cache keepalive ping interval",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-interval",
+                run: showInterval,
+            },
+        ],
+    })
+}
+
+/**
+ * Effective on/off state: the runtime override if set, else what this project's
+ * server last reported (its configured default), else on.
+ */
+function currentEnabled(directory: string): boolean {
+    const override = readControl(directory)?.enabled
+    if (override !== undefined) return override
+    try {
+        const state = JSON.parse(readFileSync(stateFilePath(directory), "utf8"))
+        if (typeof state?.enabled === "boolean") return state.enabled
+    } catch {
+        // No server snapshot yet.
+    }
+    return true
+}

package/lib/tui/footer.tsx

@@ -6,7 +6,7 @@ import { readdirSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import { stateDirectoryPath, stateFilePath } from "../paths"
 import type { PersistedSession, PersistedState, PingRecord } from "../state"
-import { kfmt, mmss } from "./format"
+import { formatDuration, kfmt, mmss } from "./format"
 
 type Theme = Record<string, any>
 type Status = "waiting" | "off" | "warming" | "busy" | "armed" | "cold"
@@ -16,6 +16,8 @@ type Derived = {
     left: number
     status: Status
     lastPing?: PingRecord
+    /** Effective ping interval for this project, when the server has reported it. */
+    intervalMs?: number
 }
 
 /**
@@ -60,12 +62,25 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
         const snapshot = state()
         const sessionID = props.sessionID
         if (!snapshot || !sessionID) {
-            return { idleMs: 0, sent: 0, left: 0, status: "waiting" }
+            return {
+                idleMs: 0,
+                sent: 0,
+                left: 0,
+                status: "waiting",
+                intervalMs: snapshot?.intervalMs,
+            }
         }
         const session: PersistedSession | undefined = snapshot.sessions?.[sessionID]
-        if (!session) return { idleMs: 0, sent: 0, left: 0, status: "waiting" }
-
-        const interval = session.intervalMs || snapshot.intervalMs || 270_000
+        if (!session)
+            return {
+                idleMs: 0,
+                sent: 0,
+                left: 0,
+                status: "waiting",
+                intervalMs: snapshot.intervalMs,
+            }
+
+        const interval = snapshot.intervalMs || session.intervalMs || 270_000
         const idleMs = Math.max(0, now() - (session.lastResponseAt || now()))
         // `nextPingAt` is the scheduler's source of truth and includes the
         // per-ping jitter. Counting from it keeps the two counters in step.
@@ -84,7 +99,14 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
                       ? "armed"
                       : "cold"
 
-        return { idleMs, sent: session.pingsSent || 0, left, status, lastPing: session.lastPing }
+        return {
+            idleMs,
+            sent: session.pingsSent || 0,
+            left,
+            status,
+            lastPing: session.lastPing,
+            intervalMs: interval,
+        }
     }
 
     const theme = props.theme
@@ -100,6 +122,11 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
                         <text fg={statusColor(theme, data().status)}>
                             {statusLabel(data().status)}
                         </text>
+                        <Show when={data().intervalMs}>
+                            {(interval: () => number) => (
+                                <text fg={theme.textMuted}>every {formatDuration(interval())}</text>
+                            )}
+                        </Show>
                     </box>
 
                     <box flexDirection="row" gap={1}>

package/lib/tui/format.ts

@@ -11,3 +11,39 @@ export function kfmt(n: number): string {
     const k = n / 1000
     return `${k >= 10 ? Math.round(k) : k.toFixed(1)}k`
 }
+
+const UNIT_MS: Record<string, number> = { h: 3_600_000, m: 60_000, s: 1_000 }
+
+/**
+ * Parse a human duration such as "4m30s", "4.5m", "270s", "1h" or "28m 20s".
+ * A bare number means minutes. Returns undefined for anything unparseable;
+ * range checks are the caller's concern.
+ */
+export function parseDuration(input: string): number | undefined {
+    const text = input.trim().toLowerCase()
+    if (!text) return undefined
+    if (/^\d+(?:\.\d+)?$/.test(text)) return Math.round(Number(text) * UNIT_MS.m)
+
+    const segment = /(\d+(?:\.\d+)?)\s*(hours?|hrs?|h|minutes?|mins?|m|seconds?|secs?|s)\s*/y
+    let total = 0
+    while (segment.lastIndex < text.length) {
+        const match = segment.exec(text)
+        if (!match) return undefined
+        total += Number(match[1]) * UNIT_MS[match[2][0]]
+    }
+    return Math.round(total)
+}
+
+/** Compact duration label, e.g. 270000 -> "4m 30s", 3600000 -> "1h". */
+export function formatDuration(ms: number): string {
+    const total = Math.max(0, Math.round(ms / 1000))
+    const hours = Math.floor(total / 3600)
+    const minutes = Math.floor((total % 3600) / 60)
+    const seconds = total % 60
+    const parts = [
+        hours ? `${hours}h` : "",
+        minutes ? `${minutes}m` : "",
+        seconds ? `${seconds}s` : "",
+    ].filter(Boolean)
+    return parts.length ? parts.join(" ") : "0s"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "@vikrant82/opencode-cache-keepalive",
-    "version": "0.1.4",
+    "version": "0.1.6",
     "type": "module",
     "description": "OpenCode plugin that keeps provider prompt caches warm by sending invisible keepalive pings, with a live TUI readout",
     "main": "./dist/index.js",
@@ -24,6 +24,7 @@
         "clean": "rm -rf dist",
         "build": "npm run clean && tsup && tsc --emitDeclarationOnly",
         "dev": "opencode plugin dev",
+        "test": "node --import tsx --test test/*.test.ts",
         "typecheck": "tsc --noEmit",
         "format": "prettier --write .",
         "format:check": "prettier --check ."
@@ -59,6 +60,7 @@
         "prettier": "^3.4.0",
         "solid-js": "^1.9.12",
         "tsup": "^8.5.1",
+        "tsx": "^4.23.15",
         "typescript": "^5.7.0"
     },
     "files": [

package/lib/tui/commands.ts

@@ -1,59 +0,0 @@
-import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
-import { readControl, writeControl } from "../control"
-
-export function registerKeepaliveCommands(api: TuiPluginApi): void {
-    // The control file is scoped per directory, so toggling keepalive here only
-    // affects this project's server plugin — not other open opencode sessions.
-    // Read lazily: state paths may not be populated at registration time.
-    const directory = () => api.state.path.directory
-
-    const setEnabled = async (enabled: boolean) => {
-        try {
-            await writeControl(enabled, directory())
-            api.ui.toast({
-                variant: enabled ? "success" : "warning",
-                title: "Cache keepalive",
-                message: enabled ? "Enabled" : "Disabled",
-            })
-        } catch (error) {
-            api.ui.toast({
-                variant: "error",
-                title: "Cache keepalive",
-                message: error instanceof Error ? error.message : String(error),
-            })
-        }
-    }
-
-    api.keymap.registerLayer({
-        commands: [
-            {
-                name: "keepalive.toggle",
-                title: "Toggle cache keepalive",
-                category: "Keepalive",
-                namespace: "palette",
-                slashName: "keepalive-toggle",
-                run: () => setEnabled(!currentEnabled(directory())),
-            },
-            {
-                name: "keepalive.on",
-                title: "Enable cache keepalive",
-                category: "Keepalive",
-                namespace: "palette",
-                slashName: "keepalive-on",
-                run: () => setEnabled(true),
-            },
-            {
-                name: "keepalive.off",
-                title: "Disable cache keepalive",
-                category: "Keepalive",
-                namespace: "palette",
-                slashName: "keepalive-off",
-                run: () => setEnabled(false),
-            },
-        ],
-    })
-}
-
-function currentEnabled(directory: string): boolean {
-    return readControl(directory)?.enabled ?? true
-}