@vikrant82/opencode-cache-keepalive 0.1.5 → 0.2.0

package/lib/state.ts

@@ -1,204 +1,201 @@
-import { mkdir, rename, writeFile } from "node:fs/promises"
-import { dirname } from "node:path"
-import type { KeepaliveConfig } from "./config"
-import { stateFilePath } from "./paths"
-
-export type PingRecord = {
-    at: number
-    hit: boolean
-    input: number
-    cacheRead: number
-    cacheWrite: number
-    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
-    /** Whether the session's provider/model pair supports cache warming. */
-    eligible: boolean
-    modelLabel?: string
-    /** Epoch ms of the last real assistant response (excludes ping replies). */
-    lastResponseAt: number
-    /** Epoch ms the current idle stretch began. */
-    idleSince: number
-    /** Epoch ms after which warming stops and the cache is allowed to go cold. */
-    windowEndsAt: number
-    /** Epoch ms the next ping is due. */
-    nextPingAt: number
-    /** Number of scheduled ping requests attempted during this warm window. */
-    pingsSent: number
-    /** A real turn is currently running. */
-    busy: boolean
-    /** 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 the last sent ping finished; ignores its late events and marks the last cache touch. */
-    lastPingAt?: number
-    lastPing?: PingRecord
-}
-
-/** Lean projection persisted to disk for the TUI reader. */
-export type PersistedSession = {
-    eligible: boolean
-    modelLabel?: string
-    lastResponseAt: number
-    idleSince: number
-    windowEndsAt: number
-    nextPingAt: number
-    intervalMs: number
-    pingsSent: number
-    busy: boolean
-    warming: boolean
-    active: boolean
-    lastPing?: PingRecord
-}
-
-export type PersistedState = {
-    version: 1
+import { randomUUID } from "node:crypto"
+import { readdirSync, readFileSync, unlinkSync } from "node:fs"
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import type { Logger } from "./logger"
+import { instanceStateFilePath, stateDirectoryKey, stateDirectoryPath } from "./paths"
+import type { ProcessTotals, SessionWarmEntry, WarmStateSink } from "./types"
+
+const CLEANUP_INTERVAL_MS = 10 * 60_000
+const PERSIST_DEBOUNCE_MS = 250
+
+type StateFile = {
+    version: 2
+    pid: number
+    instanceId: string
     updatedAt: number
-    enabled: boolean
-    intervalMs: number
-    windowMs: number
-    sessions: Record<string, PersistedSession>
+    sessions: Record<string, SessionWarmEntry>
+    totals: ProcessTotals
 }
 
-export class KeepaliveStore {
-    private readonly sessions = new Map<string, SessionKeepalive>()
-    private writeQueue: Promise<void> = Promise.resolve()
-    private enabled: boolean
+export type StateStoreOptions = { logger?: Logger; now?: () => number }
 
-    constructor(
-        private readonly config: KeepaliveConfig,
-        private readonly directory: string,
-    ) {
-        this.enabled = config.enabled
+/**
+ * Create an isolated v2 snapshot writer. Mutations are debounced, dispose flushes
+ * the latest snapshot before removing it, and all filesystem failures stay
+ * best-effort so state reporting cannot disrupt replay execution.
+ */
+export function createStateStore(
+    directory: string,
+    options: StateStoreOptions = {},
+): WarmStateSink {
+    const now = options.now ?? Date.now
+    const instanceId = randomUUID()
+    const filePath = instanceStateFilePath(directory, process.pid, instanceId)
+    const sessions = new Map<string, SessionWarmEntry>()
+    let totals: ProcessTotals = {
+        replays: 0,
+        avoidedTokens: 0,
+        replayReadTokens: 0,
+        resumeHits: 0,
+        resumeMisses: 0,
     }
-
-    setEnabled(enabled: boolean): void {
-        this.enabled = enabled
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let cleanupTimer: ReturnType<typeof setInterval> | undefined
+    let writeQueue: Promise<void> = Promise.resolve()
+    let disposed = false
+
+    const flush = (): Promise<void> => {
+        if (timer) clearTimeout(timer)
+        timer = undefined
+        const snapshot: StateFile = {
+            version: 2,
+            pid: process.pid,
+            instanceId,
+            updatedAt: now(),
+            sessions: Object.fromEntries(sessions),
+            totals,
+        }
+        const write = () => atomicWrite(filePath, JSON.stringify(snapshot))
+        writeQueue = writeQueue.then(write, write)
+        return writeQueue
     }
 
-    get(sessionID: string): SessionKeepalive | undefined {
-        return this.sessions.get(sessionID)
+    const schedule = () => {
+        if (disposed || timer) return
+        timer = setTimeout(() => {
+            timer = undefined
+            void flush()
+        }, PERSIST_DEBOUNCE_MS)
     }
 
-    ensure(sessionID: string): SessionKeepalive {
-        const existing = this.sessions.get(sessionID)
-        if (existing) return existing
-        const created: SessionKeepalive = {
-            sessionID,
-            eligible: false,
-            lastResponseAt: 0,
-            idleSince: 0,
-            windowEndsAt: 0,
-            nextPingAt: 0,
-            pingsSent: 0,
-            busy: false,
-            warming: false,
-            active: false,
+    const onExit = () => {
+        try {
+            unlinkSync(filePath)
+        } catch {
+            // Exit cleanup is best-effort.
         }
-        this.sessions.set(sessionID, created)
-        return created
     }
 
-    remove(sessionID: string): void {
-        this.sessions.delete(sessionID)
+    cleanupStateFiles(directory, options.logger)
+    cleanupTimer = setInterval(
+        () => cleanupStateFiles(directory, options.logger),
+        CLEANUP_INTERVAL_MS,
+    )
+    process.on("exit", onExit)
+
+    return {
+        upsert(entry) {
+            if (disposed) return
+            sessions.set(entry.sessionID, { ...entry })
+            schedule()
+        },
+        remove(sessionID) {
+            if (disposed) return
+            sessions.delete(sessionID)
+            schedule()
+        },
+        setTotals(value) {
+            if (disposed) return
+            totals = { ...value }
+            schedule()
+        },
+        async dispose() {
+            if (disposed) return
+            disposed = true
+            if (timer) clearTimeout(timer)
+            timer = undefined
+            if (cleanupTimer) clearInterval(cleanupTimer)
+            cleanupTimer = undefined
+            process.off("exit", onExit)
+            await flush()
+            await unlink(filePath).catch(() => {})
+        },
     }
+}
 
-    all(): SessionKeepalive[] {
-        return [...this.sessions.values()]
+/** Return the newest self-contained entry for a session across matching v2 files. */
+export function readSessionEntry(
+    directory: string,
+    sessionID: string,
+): SessionWarmEntry | undefined {
+    let freshest: SessionWarmEntry | undefined
+    for (const snapshot of readSnapshots(directory)) {
+        const entry = snapshot.sessions[sessionID]
+        if (entry && (!freshest || entry.updatedAt > freshest.updatedAt)) freshest = entry
+    }
+    return freshest
+}
+
+/** Sum process-level totals from live snapshots for this directory. */
+export function readProcessTotals(directory: string): ProcessTotals {
+    const totals = {
+        replays: 0,
+        avoidedTokens: 0,
+        replayReadTokens: 0,
+        resumeHits: 0,
+        resumeMisses: 0,
+    }
+    for (const snapshot of readSnapshots(directory)) {
+        totals.replays += snapshot.totals.replays
+        totals.avoidedTokens += snapshot.totals.avoidedTokens
+        totals.replayReadTokens += snapshot.totals.replayReadTokens
+        totals.resumeHits += snapshot.totals.resumeHits
+        totals.resumeMisses += snapshot.totals.resumeMisses
     }
+    return totals
+}
 
-    /**
-     * 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,
-            windowMs: this.config.windowMs,
-            sessions: Object.fromEntries(
-                this.all().map((s) => [
-                    s.sessionID,
-                    {
-                        eligible: s.eligible,
-                        modelLabel: s.modelLabel,
-                        lastResponseAt: s.lastResponseAt,
-                        idleSince: s.idleSince,
-                        windowEndsAt: s.windowEndsAt,
-                        nextPingAt: s.nextPingAt,
-                        intervalMs: this.config.intervalMs,
-                        pingsSent: s.pingsSent,
-                        busy: s.busy,
-                        warming: s.warming,
-                        active: s.active,
-                        lastPing: s.lastPing,
-                    } satisfies PersistedSession,
-                ]),
-            ),
+/** Remove only v2 snapshots whose owner PID is confirmed dead. */
+export function cleanupStateFiles(directory: string, logger?: Logger): void {
+    try {
+        const prefix = `state-v2-${stateDirectoryKey(directory)}-`
+        for (const name of readdirSync(stateDirectoryPath())) {
+            const match = name.match(new RegExp(`^${prefix}(\\d+)-[^/]+\\.json$`))
+            if (!match) continue
+            const pid = Number(match[1])
+            try {
+                process.kill(pid, 0)
+            } catch (error) {
+                if ((error as NodeJS.ErrnoException).code === "ESRCH") {
+                    unlinkSync(join(stateDirectoryPath(), name))
+                    logger?.dbg("Removed stale state snapshot", { pid })
+                }
+            }
         }
+    } catch {
+        // Storage can be unavailable during startup/shutdown; cleanup is optional.
+    }
+}
 
-        const write = () => atomicWrite(stateFilePath(this.directory), JSON.stringify(snapshot))
-        this.writeQueue = this.writeQueue.then(write, write)
-        return this.writeQueue
+function readSnapshots(directory: string): StateFile[] {
+    const prefix = `state-v2-${stateDirectoryKey(directory)}-`
+    try {
+        return readdirSync(stateDirectoryPath())
+            .filter((name) => name.startsWith(prefix) && name.endsWith(".json"))
+            .map((name) => {
+                try {
+                    const value = JSON.parse(
+                        readFileSync(join(stateDirectoryPath(), name), "utf8"),
+                    ) as StateFile
+                    return value.version === 2 && value.sessions && value.totals ? value : undefined
+                } catch {
+                    return undefined
+                }
+            })
+            .filter((value): value is StateFile => value !== undefined)
+    } catch {
+        return []
     }
 }
 
 async function atomicWrite(path: string, contents: string): Promise<void> {
     try {
-        const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+        const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
         await mkdir(dirname(path), { recursive: true })
         await writeFile(tmp, `${contents}\n`, "utf8")
         await rename(tmp, path)
     } catch {
-        // Persistence is best-effort; the TUI readout simply falls behind.
+        // Best-effort persistence; stale display data is safer than disrupting replay.
     }
 }

package/lib/tui/commands.tsx

@@ -0,0 +1,76 @@
+/** @jsxImportSource @opentui/solid */
+
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+import { readSessionControl, setSessionEnabled } from "../control"
+
+/** Register runtime enable/disable commands for the current session only. */
+export function registerKeepaliveCommands(api: TuiPluginApi): void {
+    const directory = () => api.state.path.directory
+    const sessionID = () => {
+        const route = api.route.current
+        return route.name === "session" && route.params && "sessionID" in route.params
+            ? String(route.params.sessionID)
+            : undefined
+    }
+    const setEnabled = async (enabled: boolean, id: string) => {
+        try {
+            await setSessionEnabled(directory(), id, enabled)
+            api.ui.toast({
+                variant: enabled ? "success" : "warning",
+                title: "Keepalive",
+                message: enabled
+                    ? "Keepalive on for this session"
+                    : "Keepalive off for this session",
+            })
+        } catch (error) {
+            api.ui.toast({
+                variant: "error",
+                title: "Keepalive",
+                message: error instanceof Error ? error.message : String(error),
+            })
+        }
+    }
+    const run = (operation: (id: string) => void | Promise<void>) => () => {
+        const id = sessionID()
+        if (!id) {
+            api.ui.toast({
+                variant: "warning",
+                title: "Keepalive",
+                message: "Open a session to toggle keepalive",
+            })
+            return
+        }
+        return operation(id)
+    }
+
+    api.keymap.registerLayer({
+        commands: [
+            {
+                name: "keepalive.toggle",
+                title: "Toggle replay cache warmer",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-toggle",
+                run: run((id) =>
+                    setEnabled(!(readSessionControl(directory(), id)?.enabled ?? true), id),
+                ),
+            },
+            {
+                name: "keepalive.on",
+                title: "Enable replay cache warmer",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-on",
+                run: run((id) => setEnabled(true, id)),
+            },
+            {
+                name: "keepalive.off",
+                title: "Disable replay cache warmer",
+                category: "Keepalive",
+                namespace: "palette",
+                slashName: "keepalive-off",
+                run: run((id) => setEnabled(false, id)),
+            },
+        ],
+    })
+}

package/lib/tui/footer.tsx

@@ -2,51 +2,19 @@
 
 import { TextAttributes } from "@opentui/core"
 import { createSignal, onCleanup, Show } from "solid-js"
-import { readdirSync, readFileSync } from "node:fs"
-import { join } from "node:path"
-import { stateDirectoryPath, stateFilePath } from "../paths"
-import type { PersistedSession, PersistedState, PingRecord } from "../state"
+import type { SessionWarmEntry, WarmState } from "../types"
+import { readSessionEntry } from "../state"
 import { kfmt, mmss } from "./format"
 
 type Theme = Record<string, any>
-type Status = "waiting" | "off" | "warming" | "busy" | "armed" | "cold"
-type Derived = {
-    idleMs: number
-    sent: number
-    left: number
-    status: Status
-    lastPing?: PingRecord
-}
 
-/**
- * Persistent readout mounted in the `sidebar_footer` slot. Shows time since the
- * last real agent response plus keepalive pings sent / left. Data comes from the
- * server plugin's state file; the idle timer ticks locally every second.
- */
+/** Display the persisted replay-warming state for the current session only. */
 export function KeepaliveFooter(props: { theme: Theme; directory: string; sessionID?: string }) {
     const [now, setNow] = createSignal(Date.now())
-    const [state, setState] = createSignal<PersistedState | undefined>(undefined)
+    const [entry, setEntry] = createSignal<SessionWarmEntry | undefined>()
 
     const load = () => {
-        const sessionID = props.sessionID
-        if (!sessionID) return setState(undefined)
-
-        const expected = readState(stateFilePath(props.directory))
-        if (expected?.sessions?.[sessionID]) return setState(expected)
-
-        try {
-            const match = readdirSync(stateDirectoryPath())
-                .filter((name) => name.startsWith("state-") && name.endsWith(".json"))
-                .map((name) => readState(join(stateDirectoryPath(), name)))
-                .filter(
-                    (snapshot): snapshot is PersistedState =>
-                        snapshot?.sessions?.[sessionID] !== undefined,
-                )
-                .sort((a, b) => b.updatedAt - a.updatedAt)[0]
-            setState(match)
-        } catch {
-            setState(undefined)
-        }
+        setEntry(props.sessionID ? readSessionEntry(props.directory, props.sessionID) : undefined)
     }
 
     load()
@@ -56,108 +24,65 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
     }, 1000)
     onCleanup(() => clearInterval(timer))
 
-    const derived = (): Derived | undefined => {
-        const snapshot = state()
-        const sessionID = props.sessionID
-        if (!snapshot || !sessionID) {
-            return { idleMs: 0, sent: 0, left: 0, status: "waiting" }
-        }
-        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
-        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.
-        const nextPingAt = Math.max(session.nextPingAt || now(), now())
-        const left = session.active
-            ? Math.max(0, Math.ceil((session.windowEndsAt - nextPingAt) / interval))
-            : 0
-        const status: Status =
-            !snapshot.enabled || !session.eligible
-                ? "off"
-                : session.warming
-                  ? "warming"
-                  : session.busy
-                    ? "busy"
-                    : session.active
-                      ? "armed"
-                      : "cold"
-
-        return { idleMs, sent: session.pingsSent || 0, left, status, lastPing: session.lastPing }
-    }
-
-    const theme = props.theme
-
     return (
-        <Show when={derived()}>
-            {(data: () => Derived) => (
-                <box flexDirection="column" paddingLeft={1} paddingRight={1} paddingTop={1} gap={0}>
-                    <box flexDirection="row" gap={1}>
-                        <text fg={theme.primary} attributes={TextAttributes.BOLD}>
-                            keepalive
-                        </text>
-                        <text fg={statusColor(theme, data().status)}>
-                            {statusLabel(data().status)}
+        <Show when={entry()}>
+            {(data: () => SessionWarmEntry) => {
+                const firstLine = () => {
+                    const value = data()
+                    const remaining =
+                        value.nextReplayAt === null ? 0 : Math.max(0, value.nextReplayAt - now())
+                    return formatStatusLine(value, remaining)
+                }
+                const secondLine = () => formatDetails(data(), now())
+
+                return (
+                    <box
+                        flexDirection="column"
+                        paddingLeft={1}
+                        paddingRight={1}
+                        paddingTop={1}
+                        gap={0}
+                    >
+                        <text
+                            fg={stateColor(props.theme, data().state)}
+                            attributes={TextAttributes.BOLD}
+                        >
+                            {firstLine()}
                         </text>
+                        <Show when={secondLine()}>
+                            {(line: () => string) => (
+                                <text fg={props.theme.textMuted}>{line()}</text>
+                            )}
+                        </Show>
                     </box>
-
-                    <box flexDirection="row" gap={1}>
-                        <text fg={theme.textMuted}>idle</text>
-                        <text fg={theme.text} attributes={TextAttributes.BOLD}>
-                            {mmss(data().idleMs)}
-                        </text>
-                        <text fg={theme.textMuted}>· sent</text>
-                        <text fg={theme.text} attributes={TextAttributes.BOLD}>
-                            {String(data().sent)}
-                        </text>
-                        <text fg={theme.textMuted}>· left</text>
-                        <text fg={theme.text} attributes={TextAttributes.BOLD}>
-                            {String(data().left)}
-                        </text>
-                    </box>
-
-                    <Show when={data().lastPing}>
-                        {(ping: () => PingRecord) => (
-                            <box flexDirection="row" gap={1}>
-                                <text fg={ping().hit ? theme.success : theme.warning}>
-                                    {ping().hit ? "✓ hit" : "✗ miss"}
-                                </text>
-                                <text fg={theme.textMuted}>
-                                    input {kfmt(ping().input)} · read {kfmt(ping().cacheRead)} ·
-                                    write {kfmt(ping().cacheWrite)}
-                                </text>
-                            </box>
-                        )}
-                    </Show>
-                </box>
-            )}
+                )
+            }}
         </Show>
     )
 }
 
-function statusLabel(status: Status): string {
-    if (status === "waiting") return "waiting"
-    if (status === "warming") return "warming…"
-    if (status === "busy") return "busy"
-    if (status === "armed") return "armed"
-    if (status === "cold") return "cold"
-    return "off"
+/** Pure formatter for the two-line footer's optional telemetry. */
+export function formatDetails(entry: SessionWarmEntry, now = Date.now()): string | undefined {
+    return `refreshes ${entry.sessionReplays} · hits ${entry.resumeHits}/${entry.resumeCount} · saved ~${kfmt(entry.avoidedTokens)} tok`
 }
 
-function statusColor(theme: Theme, status: Status): any {
-    if (status === "waiting") return theme.textMuted
-    if (status === "warming") return theme.accent
-    if (status === "busy") return theme.info
-    if (status === "armed") return theme.success
-    if (status === "cold") return theme.warning
-    return theme.textMuted
+export function formatStatusLine(entry: SessionWarmEntry, remainingMs: number): string {
+    if (entry.state === "off") return "keepalive off"
+    if (entry.state === "active") return "keepalive standby · model working"
+    if (entry.state === "stopped") {
+        if (entry.stopReason === "cap") return `keepalive stopped · refresh cap (${entry.cap})`
+        if (entry.stopReason === "lapsed") return "keepalive stopped · cache expired"
+        if (entry.stopReason === "rejected-4xx")
+            return `keepalive stopped · refresh rejected ${entry.stopStatus ?? "unknown"}`
+        return "keepalive off"
+    }
+    const state = entry.state
+    return `keepalive ${state} · ${entry.gapReplays}/${entry.cap}${entry.nextReplayAt === null ? "" : ` · next ${mmss(remainingMs)}`}`
 }
 
-function readState(path: string): PersistedState | undefined {
-    try {
-        return JSON.parse(readFileSync(path, "utf8")) as PersistedState
-    } catch {
-        return undefined
-    }
+function stateColor(theme: Theme, state: WarmState): any {
+    if (state === "busy" || state === "active") return theme.info
+    if (state === "idle") return theme.success
+    if (state === "stopped") return theme.warning
+    return theme.textMuted
 }