@vikrant82/opencode-cache-keepalive 0.1.0 → 0.1.2

package/dist/lib/state.d.ts

@@ -21,14 +21,18 @@ export type SessionKeepalive = {
     windowEndsAt: number;
     /** Epoch ms the next ping is due. */
     nextPingAt: number;
-    /** Pings sent during the current idle stretch. */
+    /** Number of scheduled ping requests attempted during this warm window. */
     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;
     /** 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. */
     lastPingAt?: number;
     lastPing?: PingRecord;

package/dist/lib/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../lib/state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG/C,MAAM,MAAM,UAAU,GAAG;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,IAAI,EAAE,OAAO,CAAA;IACb,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,MAAM,EAAE,OAAO,CAAA;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,UAAU,CAAA;CACxB,CAAA;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG;IAC3B,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,UAAU,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,CAAC,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAC7C,CAAA;AAED,qBAAa,cAAc;IAMnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,OAAO,CAAS;gBAGH,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM;IAKtC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIpD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAmB3C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B,GAAG,IAAI,gBAAgB,EAAE;IAIzB,+EAA+E;IAC/E,OAAO,IAAI,IAAI;CA+BlB"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../lib/state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG/C,MAAM,MAAM,UAAU,GAAG;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,OAAO,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,8DAA8D;AAC9D,MAAM,MAAM,gBAAgB,GAAG;IAC3B,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAA;IACtB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAA;IACpB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,IAAI,EAAE,OAAO,CAAA;IACb,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,MAAM,EAAE,OAAO,CAAA;IACf,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,UAAU,CAAA;CACxB,CAAA;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG;IAC3B,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,UAAU,CAAA;CACxB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,OAAO,EAAE,CAAC,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;CAC7C,CAAA;AAED,qBAAa,cAAc;IAMnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAN9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,OAAO,CAAS;gBAGH,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM;IAKtC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAIpD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB;IAmB3C,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI/B,GAAG,IAAI,gBAAgB,EAAE;IAIzB,+EAA+E;IAC/E,OAAO,IAAI,IAAI;CA+BlB"}

package/dist/lib/tui/footer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"footer.d.ts","sourceRoot":"","sources":["../../../lib/tui/footer.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AAUtC,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAUhC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,OAwG7F"}
+{"version":3,"file":"footer.d.ts","sourceRoot":"","sources":["../../../lib/tui/footer.tsx"],"names":[],"mappings":"AAAA,sCAAsC;AAUtC,KAAK,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAUhC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,OA+G7F"}

package/lib/keepalive.ts

@@ -8,6 +8,9 @@ const TICK_MS = 15_000
 const JITTER_MS = 15_000
 const CONTROL_POLL_MS = 1_000
 const STATUS_POLL_MS = 2_000
+const PING_STATUS_GRACE_MS = 5_000
+/** Backstop: clear a stuck `busy` flag after this long without an idle event. */
+const BUSY_TIMEOUT_MS = 300_000
 
 /**
  * The keepalive engine.
@@ -97,6 +100,7 @@ export class KeepaliveEngine {
             if (info?.role === "user") {
                 const s = this.store.ensure(sessionID)
                 s.busy = true
+                s.busySince = Date.now()
                 s.active = false
                 this.store.persist()
                 return
@@ -115,8 +119,17 @@ export class KeepaliveEngine {
             const status: string | undefined = event.properties?.status?.type
             if (!sessionID || !status) return
 
-            // The ping's own status transitions must not restart its idle window.
-            if (this.store.get(sessionID)?.warming) return
+            // The ping and its optional revert emit status transitions after their
+            // requests resolve. Ignore them briefly so they cannot re-arm/reset the
+            // active warm window. Real user-message events still stop warming now.
+            const current = this.store.get(sessionID)
+            if (
+                current?.warming ||
+                (status !== "idle" &&
+                    current?.lastPingAt &&
+                    Date.now() - current.lastPingAt < PING_STATUS_GRACE_MS)
+            )
+                return
 
             if (status === "idle") {
                 await this.armWindow(sessionID)
@@ -125,6 +138,7 @@ export class KeepaliveEngine {
 
             const s = this.store.ensure(sessionID)
             s.busy = true
+            s.busySince = Date.now()
             s.active = false
             this.store.persist()
             return
@@ -144,32 +158,52 @@ export class KeepaliveEngine {
         // Duplicate idle events (including late events from a ping) must not reset the
         // current idle stretch or extend its warm window.
         if (s.active && !s.busy) return
-        s.busy = false
-        await this.resolveSession(s)
+        // Serialize: only one armWindow may resolve metadata at a time per session.
+        // This prevents the session.status + session.idle double-event race from
+        // producing two concurrent resolveSession calls that can clobber each other.
+        if (s.arming) return
+        s.arming = true
+        try {
+            s.busy = false
+            s.busySince = undefined
+            await this.resolveSession(s)
 
-        // A new turn may have started while session metadata was being resolved.
-        if (s.busy || !this.enabled || !s.eligible) {
-            s.active = false
+            // A new turn may have started while session metadata was being resolved.
+            if (s.busy || !this.enabled || !s.eligible) {
+                s.active = false
+                this.store.persist()
+                return
+            }
+
+            const now = Date.now()
+            if (!s.lastResponseAt) s.lastResponseAt = now
+            s.idleSince = now
+            s.windowEndsAt = now + this.config.windowMs
+            s.nextPingAt = now + this.config.intervalMs
+            s.pingsSent = 0
+            s.lastPing = undefined
+            s.active = true
             this.store.persist()
-            return
+            this.logger.dbg(`armed ${short(sessionID)} model=${s.modelLabel}`)
+        } finally {
+            s.arming = false
         }
-
-        const now = Date.now()
-        if (!s.lastResponseAt) s.lastResponseAt = now
-        s.idleSince = now
-        s.windowEndsAt = now + this.config.windowMs
-        s.nextPingAt = now + this.config.intervalMs
-        s.pingsSent = 0
-        s.lastPing = undefined
-        s.active = true
-        this.store.persist()
-        this.logger.dbg(`armed ${short(sessionID)} model=${s.modelLabel}`)
     }
 
     private async tick(): Promise<void> {
         if (!this.enabled) return
         const now = Date.now()
         for (const s of this.store.all()) {
+            // Backstop: if busy is stuck (missed idle event + reconcile failure),
+            // clear it after BUSY_TIMEOUT_MS so the session can re-arm.
+            if (s.busy && s.busySince && now - s.busySince > BUSY_TIMEOUT_MS) {
+                this.logger.dbg(`busy timeout ${short(s.sessionID)} — clearing stuck flag`)
+                s.busy = false
+                s.busySince = undefined
+                void this.armWindow(s.sessionID)
+                continue
+            }
+
             if (!s.eligible || !s.active || s.busy || s.warming) continue
 
             if (now >= s.windowEndsAt) {
@@ -190,6 +224,9 @@ export class KeepaliveEngine {
         if (!s || s.warming || s.busy) return
 
         s.warming = true
+        // Count every request attempt. A transport/provider failure still consumed a
+        // scheduled ping slot and must remain visible in the footer.
+        s.pingsSent += 1
         this.store.persist()
         const startAt = Date.now()
 
@@ -210,9 +247,7 @@ export class KeepaliveEngine {
                 output: Number(info?.tokens?.output ?? 0),
             }
             s.lastPing = record
-            s.lastPingAt = record.at
-            s.pingsSent += 1
-            this.logger.info(
+            this.logger.dbg(
                 `ping ${short(sessionID)} ${record.hit ? "HIT" : "MISS"} ` +
                     `in=${record.input} read=${record.cacheRead} write=${record.cacheWrite} out=${record.output}`,
             )
@@ -222,7 +257,14 @@ export class KeepaliveEngine {
             this.logger.warn(`ping ${short(sessionID)} failed`, errText(err))
         } finally {
             s.warming = false
-            s.nextPingAt = Date.now() + jitter(this.config.intervalMs)
+            s.lastPingAt = Date.now()
+            // Schedule relative to the intended time so ping duration doesn't
+            // compound drift. Floor at now+1s to avoid immediate re-fire if the
+            // ping took longer than the interval.
+            s.nextPingAt = Math.max(
+                Date.now() + 1_000,
+                s.nextPingAt + jitter(this.config.intervalMs),
+            )
             this.store.persist()
         }
     }
@@ -297,8 +339,10 @@ export class KeepaliveEngine {
                 session.active = false
                 continue
             }
+            // Only re-arm sessions that have had a real turn (cache to warm) and
+            // are not currently occupied.
             if (!session.eligible || session.busy || session.warming) continue
-            if (!session.lastResponseAt) session.lastResponseAt = now
+            if (!session.lastResponseAt) continue
             session.idleSince = now
             session.windowEndsAt = now + this.config.windowMs
             session.nextPingAt = now + this.config.intervalMs

package/lib/logger.ts

@@ -1,21 +1,47 @@
+import { appendFileSync, mkdirSync } from "node:fs"
+import { dirname } from "node:path"
+
 const PREFIX = "[cache-keepalive]"
 
 export class Logger {
-    constructor(private readonly debug: boolean) {}
+    private readonly logPath: string
+    private readonly debug: boolean
+    private initialized = false
+
+    constructor(debug: boolean, logPath: string) {
+        this.debug = debug
+        this.logPath = logPath
+    }
 
     info(message: string, data?: unknown) {
-        if (this.debug) console.log(`${PREFIX} ${message}`, data ?? "")
+        this.write("INFO", message, data)
     }
 
     warn(message: string, data?: unknown) {
-        console.warn(`${PREFIX} ${message}`, data ?? "")
+        this.write("WARN", message, data)
     }
 
     error(message: string, data?: unknown) {
-        console.error(`${PREFIX} ${message}`, data ?? "")
+        this.write("ERROR", message, data)
     }
 
     dbg(message: string, data?: unknown) {
-        if (this.debug) console.log(`${PREFIX}:debug ${message}`, data ?? "")
+        if (this.debug) this.write("DEBUG", message, data)
+    }
+
+    private write(level: string, message: string, data?: unknown): void {
+        const ts = new Date().toISOString()
+        const extra =
+            data !== undefined ? ` ${typeof data === "string" ? data : JSON.stringify(data)}` : ""
+        const line = `${ts} ${level} ${PREFIX} ${message}${extra}\n`
+        try {
+            if (!this.initialized) {
+                mkdirSync(dirname(this.logPath), { recursive: true })
+                this.initialized = true
+            }
+            appendFileSync(this.logPath, line, "utf8")
+        } catch {
+            // Best-effort logging — never crash the plugin.
+        }
     }
 }

package/lib/paths.ts

@@ -29,3 +29,8 @@ export function stateDirectoryPath(): string {
 export function controlFilePath(): string {
     return join(stateDirectoryPath(), "control.json")
 }
+
+/** Append-only log file for the server plugin — never stdout, which corrupts the TUI. */
+export function logFilePath(): string {
+    return join(stateDirectoryPath(), "server.log")
+}

package/lib/state.ts

@@ -26,14 +26,18 @@ export type SessionKeepalive = {
     windowEndsAt: number
     /** Epoch ms the next ping is due. */
     nextPingAt: number
-    /** Pings sent during the current idle stretch. */
+    /** Number of scheduled ping requests attempted during this warm window. */
     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
     /** 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. */
     lastPingAt?: number
     lastPing?: PingRecord

package/lib/tui/footer.tsx

@@ -38,7 +38,11 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
             const match = readdirSync(stateDirectoryPath())
                 .filter((name) => name.startsWith("state-") && name.endsWith(".json"))
                 .map((name) => readState(join(stateDirectoryPath(), name)))
-                .find((snapshot) => snapshot?.sessions?.[sessionID])
+                .filter(
+                    (snapshot): snapshot is PersistedState =>
+                        snapshot?.sessions?.[sessionID] !== undefined,
+                )
+                .sort((a, b) => b.updatedAt - a.updatedAt)[0]
             setState(match)
         } catch {
             setState(undefined)
@@ -63,8 +67,11 @@ export function KeepaliveFooter(props: { theme: Theme; directory: string; sessio
 
         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.floor((session.windowEndsAt - now()) / interval))
+            ? Math.max(0, Math.ceil((session.windowEndsAt - nextPingAt) / interval))
             : 0
         const status: Status =
             !snapshot.enabled || !session.eligible

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "@vikrant82/opencode-cache-keepalive",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "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",