@vikrant82/opencode-cache-keepalive 0.1.5 → 0.2.0

package/lib/tui/format.ts

@@ -7,7 +7,47 @@ export function mmss(ms: number): string {
 
 export function kfmt(n: number): string {
     if (!Number.isFinite(n) || n <= 0) return "0"
+    if (n >= 1_000_000) {
+        const m = n / 1_000_000
+        return `${m >= 10 ? Math.round(m) : m.toFixed(1)}M`
+    }
     if (n < 1000) return `${Math.round(n)}`
     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/lib/types.ts

@@ -0,0 +1,130 @@
+/**
+ * Shared contracts between the server-side replay engine and the state/TUI layer.
+ *
+ * The engine produces one self-contained {@link SessionWarmEntry} per tracked root
+ * session and hands it to a {@link WarmStateSink}; the TUI reads persisted entries
+ * back per session. Entries never contain request URLs with queries, headers,
+ * bodies, credentials, or conversation text.
+ */
+
+/** Wire API family of a recorded request, derived from the request pathname. */
+export type WarmApi = "messages" | "responses" | "chat"
+
+/**
+ * Display/lifecycle state of a session's cache warming.
+ * - `active`: a real model request/step is in flight; no replay is sent.
+ * - `busy`: the session is blocked on a running tool; replays are scheduled.
+ * - `idle`: the session is idle between turns; replays are scheduled.
+ * - `stopped`: warming ended for the current gap; see {@link StopReason}.
+ * - `off`: warming is disabled by config or runtime control.
+ */
+export type WarmState = "active" | "busy" | "idle" | "stopped" | "off"
+
+/**
+ * Why warming stopped for the current gap.
+ * - `cap`: the per-gap replay cap was reached.
+ * - `lapsed`: the cache is believed expired (failed retry, or a replay reported a cache write instead of a read).
+ * - `rejected-4xx`: the provider rejected the replay with 400/401/403.
+ * - `disabled`: runtime control or config turned warming off.
+ */
+export type StopReason = "cap" | "lapsed" | "rejected-4xx" | "disabled"
+
+/** Outcome of the most recent replay attempt. */
+export interface ReplayResult {
+    /** Replay send time, epoch ms. */
+    at: number
+    /** HTTP status; 0 for network error or timeout. */
+    status: number
+    /** Milliseconds from issuing the replay fetch to the API-specific abort point. */
+    latencyMs: number
+    /** Cached prompt tokens reported by the provider, when parseable before abort (messages API). */
+    cacheRead?: number
+    /** Cache-write prompt tokens reported by the provider, when parseable before abort (messages API). */
+    cacheWrite?: number
+}
+
+/** Result of the first real model call after a gap that had at least one successful replay. */
+export interface ResumeResult {
+    /** step-finish time, epoch ms. */
+    at: number
+    /** cache.read tokens of that call. */
+    read: number
+    /** Prompt tokens (input + cache.read + cache.write) of the last call before the gap. */
+    promptPrev: number
+    /** True when read >= 0.9 * promptPrev. */
+    hit: boolean
+    /** Successful replays spent in the gap. */
+    replays: number
+    /**
+     * Cache-write tokens avoided for the gap: `promptPrev` on a hit, 0 on a miss.
+     * Gross figure shown to users as "saved"; replay cost is reported separately.
+     */
+    avoidedTokens: number
+    /**
+     * Cached-read tokens spent by the gap's successful replays (sum of each replay's
+     * reported cacheRead, falling back to promptPrev when not parsed). Logged only.
+     */
+    replayReadTokens: number
+}
+
+/**
+ * Complete, self-contained display state for one root session. Every field the TUI
+ * needs is here so readers never depend on file-level or process-level fields.
+ */
+export interface SessionWarmEntry {
+    sessionID: string
+    /** Last time this entry changed, epoch ms; readers pick the freshest entry per session. */
+    updatedAt: number
+    /** Effective enablement (config AND runtime control). */
+    enabled: boolean
+    /** Model id from the recorded request body. */
+    model: string
+    api: WarmApi
+    state: WarmState
+    stopReason?: StopReason
+    /** HTTP status that caused `rejected-4xx`. */
+    stopStatus?: number
+    /** Monotonic per-session gap counter; a gap starts at each real request send. */
+    gapId: number
+    /** Successful replays in the current gap. */
+    gapReplays: number
+    /** Per-gap replay cap in effect. */
+    cap: number
+    /** Next scheduled replay time, epoch ms; null when none is scheduled. */
+    nextReplayAt: number | null
+    /** Successful replays across the session's lifetime in this process. */
+    sessionReplays: number
+    /** Sum of ResumeResult.avoidedTokens across the session's gaps in this process. */
+    avoidedTokens: number
+    /** Resumes (first call after a gap with ≥1 successful replay) that hit, in this process. */
+    resumeHits: number
+    /** All resumes (hits + misses) in this process. */
+    resumeCount: number
+    lastReplay?: ReplayResult
+    resume?: ResumeResult
+}
+
+/** Process-wide aggregates, informational only (never used to gate display). */
+export interface ProcessTotals {
+    replays: number
+    avoidedTokens: number
+    replayReadTokens: number
+    resumeHits: number
+    resumeMisses: number
+}
+
+/**
+ * Destination for engine state. Implementations persist sanitized entries for the
+ * TUI. Calls are synchronous and must never throw; persistence may be debounced.
+ * Single-threaded use from the plugin's event loop is assumed.
+ */
+export interface WarmStateSink {
+    /** Replace the entry for `entry.sessionID`. */
+    upsert(entry: SessionWarmEntry): void
+    /** Forget a session (e.g. deleted). */
+    remove(sessionID: string): void
+    /** Replace process totals. */
+    setTotals(totals: ProcessTotals): void
+    /** Flush pending writes and remove this instance's persisted file. Never rejects. */
+    dispose(): Promise<void>
+}

package/package.json

@@ -1,9 +1,9 @@
 {
     "$schema": "https://json.schemastore.org/package.json",
     "name": "@vikrant82/opencode-cache-keepalive",
-    "version": "0.1.5",
+    "version": "0.2.0",
     "type": "module",
-    "description": "OpenCode plugin that keeps provider prompt caches warm by sending invisible keepalive pings, with a live TUI readout",
+    "description": "OpenCode plugin that uses bounded provider-request replay to keep prompt caches warm, with a live TUI readout",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "exports": {
@@ -68,6 +68,7 @@
         "lib/",
         "tui.tsx",
         "README.md",
+        "MIGRATION.md",
         "LICENSE"
     ]
 }

package/tui.tsx

@@ -3,9 +3,49 @@
 import type { TuiPluginModule } from "@opencode-ai/plugin/tui"
 import { registerKeepaliveCommands } from "./lib/tui/commands"
 import { KeepaliveFooter } from "./lib/tui/footer"
+import { readSessionEntry } from "./lib/state"
+import type { SessionWarmEntry } from "./lib/types"
+
+/** Route-level owner for deduplicating rejected replay notifications. */
+export function notifyRejectedReplayOnce(
+    notified: Set<string>,
+    sessionID: string,
+    entry: SessionWarmEntry,
+    toast: (message: string) => void,
+): void {
+    if (
+        entry.state !== "stopped" ||
+        entry.stopReason !== "rejected-4xx" ||
+        entry.stopStatus === undefined
+    )
+        return
+    const key = `${sessionID}:${entry.gapId}`
+    if (notified.has(key)) return
+    notified.add(key)
+    toast(`Keepalive refresh rejected (${entry.stopStatus}) — stopped for this session`)
+}
 
 const tui: TuiPluginModule["tui"] = async (api) => {
     registerKeepaliveCommands(api)
+    const notified = new Set<string>()
+    const toastTimer = setInterval(() => {
+        const route = api.route.current
+        const sessionID =
+            route.name === "session" && typeof route.params?.sessionID === "string"
+                ? route.params.sessionID
+                : undefined
+        if (!sessionID) return
+        const entry = readSessionEntry(api.state.path.directory, sessionID)
+        if (!entry) return
+        notifyRejectedReplayOnce(notified, sessionID, entry, (message) =>
+            api.ui.toast({
+                variant: "error",
+                title: "Keepalive refresh rejected",
+                message,
+            }),
+        )
+    }, 1000)
+    api.lifecycle.onDispose(() => clearInterval(toastTimer))
     api.slots.register({
         // The built-in sidebar footer uses order 100. This slot is single-winner,
         // so a lower order makes the keepalive readout the visible footer.

package/dist/lib/keepalive.d.ts

@@ -1,85 +0,0 @@
-import type { KeepaliveConfig } from "./config";
-import type { KeepaliveStore } from "./state";
-import type { Logger } from "./logger";
-/**
- * The keepalive engine.
- *
- * Lifecycle per session:
- *   1. A real turn finishes -> `session.status` idle -> arm a warm window anchored on
- *      the real response and schedule pings.
- *   2. On each tick past `nextPingAt` (and within the window) -> `firePing`.
- *   3. `firePing` confirms with the server that the session is idle, sends a `~`
- *      prompt with the last real turn's agent/model/variant (exact cached prefix),
- *      reads `usage` to confirm a cache hit, then optionally reverts the `~`/`~` turn.
- *   4. A new real user turn, the window closing, or the cache presumed cold stops warming.
- *
- * Threading: all state is mutated on the single plugin event loop. opencode invokes
- * the `event` hook without awaiting it, so async handlers interleave; per-session
- * `arming` / `warming` flags serialize the async sections.
- *
- * Errors: network/API failures are logged and never thrown to opencode.
- */
-export declare class KeepaliveEngine {
-    private readonly client;
-    private readonly config;
-    private readonly store;
-    private readonly logger;
-    private readonly directory;
-    private timer;
-    private controlTimer;
-    private statusTimer;
-    private controlUpdatedAt;
-    private reconcilingStatus;
-    private enabled;
-    constructor(client: any, config: KeepaliveConfig, store: KeepaliveStore, logger: Logger, directory: string);
-    start(): void;
-    stop(): void;
-    /**
-     * True while a ping turn owns the session, so tool calls must be blocked. Becomes
-     * false as soon as a real user message joins the in-flight ping run: the rest of
-     * that run is real work and needs its tools.
-     */
-    shouldBlockTools(sessionID: string): boolean;
-    onEvent(event: any): Promise<void>;
-    /**
-     * Track a new user message observed while a ping is in flight. Event order alone
-     * cannot tell the ping's own message from a real prompt racing it, so messages are
-     * held until their text part arrives (see `notePingRunPart`). Any message seen
-     * before the ping is sent, or a second new message, is necessarily a real turn.
-     */
-    private notePingRunUser;
-    /**
-     * Classify a pending user message by its first text part: the ping token marks
-     * the ping's own message; any other text is a real turn joining the ping run.
-     * opencode publishes a user message's parts right after the message itself, before
-     * the run reaches any tool call.
-     */
-    private notePingRunPart;
-    /** A real turn joined the in-flight ping: unblock tools and treat the session as busy. */
-    private interruptPing;
-    private armWindow;
-    /** Start a warm window anchored on the last real response and the last cache touch. */
-    private openWindow;
-    /** False once the cache has gone too long without a request to still be trusted warm. */
-    private cacheMayBeWarm;
-    private tick;
-    private firePing;
-    /** True only when the server positively reports the session idle. */
-    private isIdleOnServer;
-    /** Recover the last real turn's request settings when no user event was observed. */
-    private lookupRequest;
-    private recentMessages;
-    private isPingMessage;
-    /**
-     * Remove the `~` user + `~` assistant turn so it never enters real context.
-     * Revert drops the target and everything after it (and rolls back file
-     * snapshots), so it is skipped unless only the ping's own replies follow.
-     */
-    private revertPing;
-    private isRecentPing;
-    private resolveSession;
-    private pollControl;
-    /** Recover when a session.status idle event is missed by reconciling with the API. */
-    private reconcileStatus;
-}
-//# sourceMappingURL=keepalive.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"keepalive.d.ts","sourceRoot":"","sources":["../../lib/keepalive.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAG/C,OAAO,KAAK,EAAgB,cAAc,EAAiC,MAAM,SAAS,CAAA;AAC1F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAgBtC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe;IASpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAZ9B,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,WAAW,CAA4C;IAC/D,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,OAAO,CAAS;gBAGH,MAAM,EAAE,GAAG,EACX,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM;IAQtC,KAAK,IAAI,IAAI;IAab,IAAI,IAAI,IAAI;IAUZ;;;;OAIG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAKtC,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAiGxC;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAcvB;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAcvB,0FAA0F;IAC1F,OAAO,CAAC,aAAa;YAWP,SAAS;IAuCvB,uFAAuF;IACvF,OAAO,CAAC,UAAU;IASlB,yFAAyF;IACzF,OAAO,CAAC,cAAc;YAKR,IAAI;YAgCJ,QAAQ;IAsGtB,qEAAqE;YACvD,cAAc;IAW5B,qFAAqF;YACvE,aAAa;YAeb,cAAc;IAc5B,OAAO,CAAC,aAAa;IASrB;;;;OAIG;YACW,UAAU;IAoCxB,OAAO,CAAC,YAAY;YAMN,cAAc;IAiB5B,OAAO,CAAC,WAAW;IAwBnB,sFAAsF;YACxE,eAAe;CAmBhC"}

package/dist/lib/model.d.ts

@@ -1,8 +0,0 @@
-import type { KeepaliveConfig } from "./config";
-/**
- * Warming only helps on providers that do prefix caching we can refresh by
- * replaying the prefix. Supported defaults include Claude and GPT models served
- * through GitHub Copilot. Everything else is skipped.
- */
-export declare function isEligibleModel(config: KeepaliveConfig, providerID: string | undefined, modelID: string | undefined): boolean;
-//# sourceMappingURL=model.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../lib/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,GAC5B,OAAO,CAOT"}

package/dist/lib/system.d.ts

@@ -1,11 +0,0 @@
-/**
- * Stable keepalive instruction appended to the system prompt.
- *
- * IMPORTANT: this text must be byte-stable and applied to *every* request for an
- * eligible model (real turns and pings alike). If it were only added on pings, the
- * system prefix would differ from real turns and the ping would miss the cache.
- * Adding it consistently keeps the cached prefix identical and lets the model
- * answer a ping with a single token instead of a paragraph or a tool call.
- */
-export declare function keepaliveInstruction(pingToken: string): string;
-//# sourceMappingURL=system.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"system.d.ts","sourceRoot":"","sources":["../../lib/system.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS9D"}