@vikrant82/opencode-cache-keepalive 0.1.6 → 0.2.0

package/lib/config.ts

@@ -1,101 +1,133 @@
 export type KeepaliveConfig = {
-    /** Master switch. When false the plugin registers no timers or hooks. */
     enabled: boolean
-    /** Milliseconds between pings. Must stay under the shortest supported provider TTL. */
-    intervalMs: number
-    /**
-     * How long to keep warming after the last real response before giving up and
-     * letting the cache go cold. The default follows the Copilot Claude
-     * write/read break-even; providers with automatic caching may be cheaper.
-     */
-    windowMs: number
-    /**
-     * Append a stable keepalive instruction to the system prompt so the model
-     * answers a `~` ping with a single `~` token and never calls tools. The
-     * instruction is added to real turns too, so the cached prefix stays identical.
-     */
-    injectSystemInstruction: boolean
-    /** The single character/token used as the keepalive suffix. */
-    pingToken: string
-    /** Remove synthetic ping turns after measuring their cache usage. */
-    revertPing: boolean
-    /** Warm subagent/child sessions too. Off by default to avoid wasted pings. */
+    intervals: Record<string, number>
+    hosts: string[]
+    cacheReadFactor: number
+    missFactor: number
+    maxReplaysPerGap: "auto" | number
     includeChildSessions: boolean
+    replayTimeoutMs: number
+    maxStoredBytes: number
     debug: boolean
-    /** providerID substrings eligible for warming (cache-controlled providers). */
-    providerAllowlist: string[]
-    /** modelID substrings eligible for warming. */
-    modelAllowlist: string[]
 }
 
 const DEFAULTS: KeepaliveConfig = {
     enabled: true,
-    intervalMs: 270_000, // 4.5 min — below the shortest supported cache TTL
-    windowMs: 3_300_000, // 55 min — the Copilot Claude write/read break-even
-    injectSystemInstruction: true,
-    pingToken: "~",
-    revertPing: true,
+    intervals: { claude: 285_000, gpt: 1_680_000 },
+    hosts: ["githubcopilot.com"],
+    cacheReadFactor: 0.1,
+    missFactor: 1,
+    maxReplaysPerGap: "auto",
     includeChildSessions: false,
+    replayTimeoutMs: 60_000,
+    maxStoredBytes: 67_108_864,
     debug: false,
-    providerAllowlist: ["copilot"],
-    modelAllowlist: ["claude", "anthropic", "sonnet", "opus", "haiku", "gpt"],
 }
 
-export function getConfig(options: Record<string, unknown> | undefined): KeepaliveConfig {
-    const o = options ?? {}
-    const env = process.env
+const DEPRECATED = [
+    "intervalMs",
+    "intervalSeconds",
+    "windowMs",
+    "windowMinutes",
+    "revertPing",
+    "pingToken",
+    "injectSystemInstruction",
+    "providerAllowlist",
+    "modelAllowlist",
+    "claudeBusyWarm",
+    "claudeBusyWarmIntervalMs",
+    "claudeBusyWarmWindowMs",
+]
+const warnedDeprecated = new Set<string>()
 
+export function getConfig(
+    options: Record<string, unknown> | undefined,
+    warn: (message: string) => void = () => {},
+): KeepaliveConfig {
+    const option = options ?? {}
+    const env = process.env
+    for (const key of DEPRECATED) {
+        if (key in option && !warnedDeprecated.has(key)) {
+            warnedDeprecated.add(key)
+            warn(`deprecated option ${key} is ignored`)
+        }
+    }
+    const parseJson = (raw: string | undefined): unknown => {
+        if (!raw) return undefined
+        try {
+            return JSON.parse(raw)
+        } catch {
+            return undefined
+        }
+    }
+    const intervals = objectOption(
+        option.intervals ?? parseJson(env.OPENCODE_KEEPALIVE_INTERVALS),
+        DEFAULTS.intervals,
+    )
+    const hosts = listOption(
+        option.hosts ?? parseJson(env.OPENCODE_KEEPALIVE_HOSTS),
+        DEFAULTS.hosts,
+    )
+    const maxRaw = option.maxReplaysPerGap ?? env.OPENCODE_KEEPALIVE_MAX_REPLAYS_PER_GAP
+    const maxReplaysPerGap =
+        maxRaw === "auto"
+            ? "auto"
+            : positiveNumber(maxRaw) !== undefined
+              ? positiveNumber(maxRaw)!
+              : DEFAULTS.maxReplaysPerGap
     return {
-        enabled: boolOpt(o.enabled, env.OPENCODE_KEEPALIVE_ENABLED !== "false" && DEFAULTS.enabled),
-        intervalMs: durationOpt(
-            o.intervalMs,
-            o.intervalSeconds,
-            numEnv(env.OPENCODE_KEEPALIVE_INTERVAL_MS, DEFAULTS.intervalMs),
+        enabled: boolOption(
+            option.enabled,
+            env.OPENCODE_KEEPALIVE_ENABLED === undefined
+                ? DEFAULTS.enabled
+                : env.OPENCODE_KEEPALIVE_ENABLED !== "false",
         ),
-        windowMs: durationOpt(
-            o.windowMs,
-            o.windowMinutes ? Number(o.windowMinutes) * 60 : undefined,
-            numEnv(env.OPENCODE_KEEPALIVE_WINDOW_MS, DEFAULTS.windowMs),
+        intervals,
+        hosts,
+        cacheReadFactor:
+            positiveNumber(option.cacheReadFactor ?? env.OPENCODE_KEEPALIVE_CACHE_READ_FACTOR) ??
+            DEFAULTS.cacheReadFactor,
+        missFactor:
+            positiveNumber(option.missFactor ?? env.OPENCODE_KEEPALIVE_MISS_FACTOR) ??
+            DEFAULTS.missFactor,
+        maxReplaysPerGap,
+        includeChildSessions: boolOption(
+            option.includeChildSessions,
+            env.OPENCODE_KEEPALIVE_INCLUDE_CHILD_SESSIONS === "true" ||
+                DEFAULTS.includeChildSessions,
         ),
-        injectSystemInstruction: boolOpt(
-            o.injectSystemInstruction,
-            DEFAULTS.injectSystemInstruction,
-        ),
-        pingToken:
-            typeof o.pingToken === "string" && o.pingToken.length > 0
-                ? o.pingToken
-                : DEFAULTS.pingToken,
-        revertPing: boolOpt(
-            o.revertPing,
-            env.OPENCODE_KEEPALIVE_REVERT_PING !== "false" && DEFAULTS.revertPing,
-        ),
-        includeChildSessions: boolOpt(o.includeChildSessions, DEFAULTS.includeChildSessions),
-        debug: boolOpt(o.debug, env.OPENCODE_KEEPALIVE_DEBUG === "true"),
-        providerAllowlist: listOpt(o.providerAllowlist, DEFAULTS.providerAllowlist),
-        modelAllowlist: listOpt(o.modelAllowlist, DEFAULTS.modelAllowlist),
+        replayTimeoutMs:
+            positiveNumber(option.replayTimeoutMs ?? env.OPENCODE_KEEPALIVE_REPLAY_TIMEOUT_MS) ??
+            DEFAULTS.replayTimeoutMs,
+        maxStoredBytes:
+            positiveNumber(option.maxStoredBytes ?? env.OPENCODE_KEEPALIVE_MAX_STORED_BYTES) ??
+            DEFAULTS.maxStoredBytes,
+        debug: boolOption(option.debug, env.OPENCODE_KEEPALIVE_DEBUG === "true"),
     }
 }
 
-function boolOpt(value: unknown, fallback: boolean): boolean {
+function boolOption(value: unknown, fallback: boolean): boolean {
     return typeof value === "boolean" ? value : fallback
 }
 
-function listOpt(value: unknown, fallback: string[]): string[] {
-    if (!Array.isArray(value)) return fallback
-    const filtered = value.filter((item): item is string => typeof item === "string")
-    return filtered.length > 0 ? filtered : fallback
+function positiveNumber(value: unknown): number | undefined {
+    const parsed = typeof value === "string" ? Number(value) : value
+    return typeof parsed === "number" && Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
 }
 
-/** Accept an explicit `*Ms` option, a `*Seconds` option, or fall back. */
-function durationOpt(ms: unknown, seconds: unknown, fallback: number): number {
-    if (typeof ms === "number" && Number.isFinite(ms) && ms > 0) return ms
-    if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0)
-        return seconds * 1000
-    return fallback
+function objectOption(value: unknown, fallback: Record<string, number>): Record<string, number> {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return fallback
+    const entries = Object.entries(value).flatMap(([key, interval]) => {
+        const parsed = positiveNumber(interval)
+        return parsed === undefined ? [] : [[key.toLowerCase(), parsed] as const]
+    })
+    return entries.length ? Object.fromEntries(entries) : fallback
 }
 
-function numEnv(raw: string | undefined, fallback: number): number {
-    if (!raw) return fallback
-    const value = Number(raw)
-    return Number.isFinite(value) && value > 0 ? value : fallback
+function listOption(value: unknown, fallback: string[]): string[] {
+    if (!Array.isArray(value)) return fallback
+    const values = value.filter(
+        (item): item is string => typeof item === "string" && item.length > 0,
+    )
+    return values.length ? values : fallback
 }

package/lib/control.ts

@@ -4,90 +4,57 @@ import { mkdir, rename, writeFile } from "node:fs/promises"
 import { dirname } from "node:path"
 import { controlFilePath } from "./paths"
 
-/** Smallest accepted runtime ping interval; below this the 15 s scheduler tick dominates. */
-export const MIN_INTERVAL_MS = 60_000
-/** Largest accepted runtime ping interval (sanity bound; no provider cache outlives it). */
-export const MAX_INTERVAL_MS = 24 * 3_600_000
+const VERSION = 2
+const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000
 
-/**
- * Per-project runtime overrides written by the TUI and polled by the server plugin.
- * Absent fields mean "use the plugin configuration". Readers ignore unknown fields,
- * so older servers still honour `enabled` and ignore `intervalMs`.
- */
-export type KeepaliveControl = {
-    version: 1
-    /** Runtime on/off override. */
-    enabled?: boolean
-    /** Runtime ping interval override in milliseconds. */
-    intervalMs?: number
-    /** Epoch ms of the last write; strictly increasing so every write is observed. */
-    updatedAt: number
-}
-
-/** Changes to apply to the control file; `intervalMs: null` clears the override. */
-export type ControlPatch = {
-    enabled?: boolean
-    intervalMs?: number | null
-}
+export type SessionControl = { enabled: boolean; updatedAt: number }
+export type SessionControlFile = { version: 2; sessions: Record<string, SessionControl> }
 
-export function isValidInterval(ms: unknown): ms is number {
-    return (
-        typeof ms === "number" &&
-        Number.isFinite(ms) &&
-        ms >= MIN_INTERVAL_MS &&
-        ms <= MAX_INTERVAL_MS
-    )
-}
-
-/**
- * Read the directory's control file. Returns undefined when it is missing or
- * malformed; an out-of-range interval override is dropped rather than rejecting
- * the whole file. Never throws.
- */
-export function readControl(directory: string): KeepaliveControl | undefined {
+/** Read current session overrides; old folder-level controls are intentionally ignored. */
+export function readSessionControls(directory: string, now = Date.now()): SessionControlFile {
     try {
         const value = JSON.parse(readFileSync(controlFilePath(directory), "utf8")) as Record<
             string,
             unknown
         >
-        if (value?.version !== 1 || typeof value.updatedAt !== "number") return undefined
-        if (value.enabled !== undefined && typeof value.enabled !== "boolean") return undefined
-        return {
-            version: 1,
-            updatedAt: value.updatedAt,
-            ...(typeof value.enabled === "boolean" ? { enabled: value.enabled } : {}),
-            ...(isValidInterval(value.intervalMs) ? { intervalMs: value.intervalMs } : {}),
+        if (value.version !== VERSION || !value.sessions || typeof value.sessions !== "object")
+            return { version: VERSION, sessions: {} }
+        const sessions: Record<string, SessionControl> = {}
+        for (const [id, raw] of Object.entries(value.sessions)) {
+            if (
+                !raw ||
+                typeof raw !== "object" ||
+                typeof (raw as SessionControl).enabled !== "boolean" ||
+                typeof (raw as SessionControl).updatedAt !== "number" ||
+                (raw as SessionControl).updatedAt < now - MAX_AGE_MS
+            )
+                continue
+            sessions[id] = {
+                enabled: (raw as SessionControl).enabled,
+                updatedAt: (raw as SessionControl).updatedAt,
+            }
         }
+        return { version: VERSION, sessions }
     } catch {
-        return undefined
+        return { version: VERSION, sessions: {} }
     }
 }
 
-/**
- * Merge `patch` into the directory's control file and write it atomically. Fields
- * not in the patch keep their current value.
- *
- * @throws RangeError when `patch.intervalMs` is outside
- *   [MIN_INTERVAL_MS, MAX_INTERVAL_MS]; filesystem errors propagate.
- */
-export async function updateControl(
+export function readSessionControl(
     directory: string,
-    patch: ControlPatch,
-): Promise<KeepaliveControl> {
-    if (
-        patch.intervalMs !== undefined &&
-        patch.intervalMs !== null &&
-        !isValidInterval(patch.intervalMs)
-    ) {
-        throw new RangeError(
-            `Ping interval must be between ${MIN_INTERVAL_MS / 1000}s and ${MAX_INTERVAL_MS / 3_600_000}h`,
-        )
-    }
+    sessionID: string,
+): SessionControl | undefined {
+    return readSessionControls(directory).sessions[sessionID]
+}
 
-    // Serialize read-merge-write within this process so concurrent updates cannot
-    // drop each other's fields. Across processes the atomic rename keeps the file
-    // valid; the last writer wins.
-    const run = updateQueue.then(() => writeMerged(directory, patch))
+/** Atomically update only this session key and prune expired overrides. */
+export async function setSessionEnabled(
+    directory: string,
+    sessionID: string,
+    enabled: boolean,
+    now = Date.now(),
+): Promise<SessionControlFile> {
+    const run = updateQueue.then(() => writeSessionControl(directory, sessionID, enabled, now))
     updateQueue = run.then(
         () => undefined,
         () => undefined,
@@ -97,17 +64,19 @@ export async function updateControl(
 
 let updateQueue: Promise<void> = Promise.resolve()
 
-async function writeMerged(directory: string, patch: ControlPatch): Promise<KeepaliveControl> {
-    const current = readControl(directory)
-    const enabled = patch.enabled ?? current?.enabled
-    const intervalMs =
-        patch.intervalMs === null ? undefined : (patch.intervalMs ?? current?.intervalMs)
-    const value: KeepaliveControl = {
-        version: 1,
-        ...(enabled !== undefined ? { enabled } : {}),
-        ...(intervalMs !== undefined ? { intervalMs } : {}),
-        updatedAt: Math.max(Date.now(), (current?.updatedAt ?? 0) + 1),
-    }
+async function writeSessionControl(
+    directory: string,
+    sessionID: string,
+    enabled: boolean,
+    now: number,
+): Promise<SessionControlFile> {
+    const current = readSessionControls(directory, now)
+    const cutoff = now - MAX_AGE_MS
+    const sessions = Object.fromEntries(
+        Object.entries(current.sessions).filter(([, value]) => value.updatedAt >= cutoff),
+    )
+    sessions[sessionID] = { enabled, updatedAt: now }
+    const value: SessionControlFile = { version: VERSION, sessions }
     const path = controlFilePath(directory)
     const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
     await mkdir(dirname(path), { recursive: true })
@@ -115,8 +84,3 @@ async function writeMerged(directory: string, patch: ControlPatch): Promise<Keep
     await rename(tmp, path)
     return value
 }
-
-/** Set the runtime on/off override, preserving any interval override. */
-export function writeControl(enabled: boolean, directory: string): Promise<KeepaliveControl> {
-    return updateControl(directory, { enabled })
-}

package/lib/paths.ts

@@ -2,17 +2,17 @@ import { createHash } from "node:crypto"
 import { homedir } from "node:os"
 import { join } from "node:path"
 
-/**
- * Absolute path to the JSON state file shared between the server plugin (writer)
- * and the TUI plugin (reader). Both processes run on the same machine, so a file
- * under opencode's plugin storage dir is the simplest cross-process channel.
- *
- * Mirrors the storage layout used by other opencode plugins:
- *   <XDG_DATA_HOME | ~/.local/share>/opencode/storage/plugin/keepalive/state.json
- */
-export function stateFilePath(directory: string): string {
-    const key = createHash("sha256").update(directory).digest("hex").slice(0, 16)
-    return join(stateDirectoryPath(), `state-${key}.json`)
+/** Stable short directory key shared by that directory's state-file readers/writers. */
+export function stateDirectoryKey(directory: string): string {
+    return createHash("sha256").update(directory).digest("hex").slice(0, 16)
+}
+
+/** Filename for one process/plugin-instance state snapshot. */
+export function instanceStateFilePath(directory: string, pid: number, instanceId: string): string {
+    return join(
+        stateDirectoryPath(),
+        `state-v2-${stateDirectoryKey(directory)}-${pid}-${instanceId}.json`,
+    )
 }
 
 export function stateDirectoryPath(): string {
@@ -26,9 +26,7 @@ export function stateDirectoryPath(): string {
 }
 
 /**
- * Runtime on/off control written by the TUI and read by the server plugin.
- * Scoped per directory (like the state file) so toggling keepalive in one
- * project does not affect every other open opencode session.
+ * Session runtime controls are stored by directory, with entries keyed by session ID.
  */
 export function controlFilePath(directory: string): string {
     const key = createHash("sha256").update(directory).digest("hex").slice(0, 16)