@vikrant82/opencode-cache-keepalive 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const server: Plugin;
+export default server;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAWjD,QAAA,MAAM,MAAM,EAAE,MA8Cb,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/index.js

@@ -0,0 +1,582 @@
+// lib/auth.ts
+function isSecureMode() {
+  return !!process.env.OPENCODE_SERVER_PASSWORD;
+}
+function getAuthorizationHeader() {
+  const password = process.env.OPENCODE_SERVER_PASSWORD;
+  if (!password) return void 0;
+  const username = process.env.OPENCODE_SERVER_USERNAME ?? "opencode";
+  const credentials = Buffer.from(`${username}:${password}`).toString("base64");
+  return `Basic ${credentials}`;
+}
+function configureClientAuth(client) {
+  const header = getAuthorizationHeader();
+  if (!header) return;
+  const inner = client?._client ?? client?.client;
+  if (!inner?.interceptors?.request) return;
+  inner.interceptors.request.use((request) => {
+    if (!request.headers.has("Authorization")) {
+      request.headers.set("Authorization", header);
+    }
+    return request;
+  });
+}
+
+// lib/config.ts
+var DEFAULTS = {
+  enabled: true,
+  intervalMs: 27e4,
+  // 4.5 min — below the shortest supported cache TTL
+  windowMs: 33e5,
+  // 55 min — the Copilot Claude write/read break-even
+  injectSystemInstruction: true,
+  pingToken: "~",
+  revertPing: true,
+  includeChildSessions: false,
+  debug: false,
+  providerAllowlist: ["copilot"],
+  modelAllowlist: ["claude", "anthropic", "sonnet", "opus", "haiku", "gpt"]
+};
+function getConfig(options) {
+  const o = options ?? {};
+  const env = process.env;
+  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)
+    ),
+    windowMs: durationOpt(
+      o.windowMs,
+      o.windowMinutes ? Number(o.windowMinutes) * 60 : void 0,
+      numEnv(env.OPENCODE_KEEPALIVE_WINDOW_MS, DEFAULTS.windowMs)
+    ),
+    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)
+  };
+}
+function boolOpt(value, fallback) {
+  return typeof value === "boolean" ? value : fallback;
+}
+function listOpt(value, fallback) {
+  if (!Array.isArray(value)) return fallback;
+  const filtered = value.filter((item) => typeof item === "string");
+  return filtered.length > 0 ? filtered : fallback;
+}
+function durationOpt(ms, seconds, fallback) {
+  if (typeof ms === "number" && Number.isFinite(ms) && ms > 0) return ms;
+  if (typeof seconds === "number" && Number.isFinite(seconds) && seconds > 0)
+    return seconds * 1e3;
+  return fallback;
+}
+function numEnv(raw, fallback) {
+  if (!raw) return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+// lib/control.ts
+import { readFileSync } from "fs";
+import { mkdir, rename, writeFile } from "fs/promises";
+import { dirname } from "path";
+
+// lib/paths.ts
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
+function stateFilePath(directory) {
+  const key = createHash("sha256").update(directory).digest("hex").slice(0, 16);
+  return join(stateDirectoryPath(), `state-${key}.json`);
+}
+function stateDirectoryPath() {
+  return join(
+    process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"),
+    "opencode",
+    "storage",
+    "plugin",
+    "keepalive"
+  );
+}
+function controlFilePath() {
+  return join(stateDirectoryPath(), "control.json");
+}
+
+// lib/control.ts
+function readControl() {
+  try {
+    const value = JSON.parse(
+      readFileSync(controlFilePath(), "utf8")
+    );
+    if (value.version !== 1 || typeof value.enabled !== "boolean") return void 0;
+    if (typeof value.updatedAt !== "number") return void 0;
+    return value;
+  } catch {
+    return void 0;
+  }
+}
+
+// lib/model.ts
+function isEligibleModel(config, providerID, modelID) {
+  if (!providerID || !modelID) return false;
+  const provider = providerID.toLowerCase();
+  const model = modelID.toLowerCase();
+  const providerOk = config.providerAllowlist.some((needle) => provider.includes(needle));
+  const modelOk = config.modelAllowlist.some((needle) => model.includes(needle));
+  return providerOk && modelOk;
+}
+
+// lib/keepalive.ts
+var TICK_MS = 15e3;
+var JITTER_MS = 15e3;
+var CONTROL_POLL_MS = 1e3;
+var STATUS_POLL_MS = 2e3;
+var KeepaliveEngine = class {
+  constructor(client, config, store, logger) {
+    this.client = client;
+    this.config = config;
+    this.store = store;
+    this.logger = logger;
+    const control = readControl();
+    this.enabled = control?.enabled ?? config.enabled;
+    this.controlUpdatedAt = control?.updatedAt ?? 0;
+    this.store.setEnabled(this.enabled);
+  }
+  client;
+  config;
+  store;
+  logger;
+  timer;
+  controlTimer;
+  statusTimer;
+  controlUpdatedAt = 0;
+  reconcilingStatus = false;
+  enabled;
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.tick(), TICK_MS);
+    this.controlTimer = setInterval(() => this.pollControl(), CONTROL_POLL_MS);
+    this.statusTimer = setInterval(() => void this.reconcileStatus(), STATUS_POLL_MS);
+    this.store.persist();
+    this.logger.info(
+      `started (${this.enabled ? "enabled" : "disabled"}, interval=${Math.round(this.config.intervalMs / 1e3)}s, window=${Math.round(this.config.windowMs / 6e4)}m)`
+    );
+  }
+  stop() {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = void 0;
+    if (this.controlTimer) clearInterval(this.controlTimer);
+    this.controlTimer = void 0;
+    if (this.statusTimer) clearInterval(this.statusTimer);
+    this.statusTimer = void 0;
+  }
+  /** True while a ping is in flight — used to block tool calls during a ping. */
+  isWarming(sessionID) {
+    return !!this.store.get(sessionID)?.warming;
+  }
+  async onEvent(event) {
+    const type = event?.type;
+    if (!type) return;
+    if (type === "session.deleted") {
+      const id = event.properties?.sessionID ?? event.properties?.info?.id;
+      if (id) {
+        this.store.remove(id);
+        this.store.persist();
+      }
+      return;
+    }
+    if (type === "message.updated") {
+      const info = event.properties?.info;
+      const sessionID = info?.sessionID ?? event.properties?.sessionID;
+      if (!sessionID) return;
+      const session = this.store.get(sessionID);
+      if (session?.warming) return;
+      const eventAt = info?.time?.completed ?? info?.time?.created;
+      if (session?.lastPingAt && typeof eventAt === "number" && eventAt <= session.lastPingAt)
+        return;
+      if (info?.role === "user") {
+        const s = this.store.ensure(sessionID);
+        s.busy = true;
+        s.active = false;
+        this.store.persist();
+        return;
+      }
+      if (info?.role === "assistant" && typeof info?.time?.completed === "number") {
+        const s = this.store.ensure(sessionID);
+        s.lastResponseAt = info.time.completed;
+        this.store.persist();
+      }
+      return;
+    }
+    if (type === "session.status") {
+      const sessionID = event.properties?.sessionID;
+      const status = event.properties?.status?.type;
+      if (!sessionID || !status) return;
+      if (this.store.get(sessionID)?.warming) return;
+      if (status === "idle") {
+        await this.armWindow(sessionID);
+        return;
+      }
+      const s = this.store.ensure(sessionID);
+      s.busy = true;
+      s.active = false;
+      this.store.persist();
+      return;
+    }
+    if (type === "session.idle") {
+      const sessionID = event.properties?.sessionID;
+      if (!sessionID) return;
+      if (this.store.get(sessionID)?.warming) return;
+      await this.armWindow(sessionID);
+    }
+  }
+  async armWindow(sessionID) {
+    const s = this.store.ensure(sessionID);
+    if (s.active && !s.busy) return;
+    s.busy = false;
+    await this.resolveSession(s);
+    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 = void 0;
+    s.active = true;
+    this.store.persist();
+    this.logger.dbg(`armed ${short(sessionID)} model=${s.modelLabel}`);
+  }
+  async tick() {
+    if (!this.enabled) return;
+    const now = Date.now();
+    for (const s of this.store.all()) {
+      if (!s.eligible || !s.active || s.busy || s.warming) continue;
+      if (now >= s.windowEndsAt) {
+        s.active = false;
+        this.store.persist();
+        this.logger.dbg(
+          `window closed ${short(s.sessionID)} after ${s.pingsSent} ping(s) \u2014 cache may cool`
+        );
+        continue;
+      }
+      if (now >= s.nextPingAt) void this.firePing(s.sessionID);
+    }
+  }
+  async firePing(sessionID) {
+    const s = this.store.get(sessionID);
+    if (!s || s.warming || s.busy) return;
+    s.warming = true;
+    this.store.persist();
+    const startAt = Date.now();
+    try {
+      const res = await this.client.session.prompt({
+        path: { id: sessionID },
+        body: { parts: [{ type: "text", text: this.config.pingToken }] }
+      });
+      const info = res?.data?.info ?? res?.info;
+      const cache = info?.tokens?.cache ?? {};
+      const record = {
+        at: Date.now(),
+        hit: Number(cache.read ?? 0) > 0,
+        input: Number(info?.tokens?.input ?? 0),
+        cacheRead: Number(cache.read ?? 0),
+        cacheWrite: Number(cache.write ?? 0),
+        output: Number(info?.tokens?.output ?? 0)
+      };
+      s.lastPing = record;
+      s.lastPingAt = record.at;
+      s.pingsSent += 1;
+      this.logger.info(
+        `ping ${short(sessionID)} ${record.hit ? "HIT" : "MISS"} in=${record.input} read=${record.cacheRead} write=${record.cacheWrite} out=${record.output}`
+      );
+      if (this.config.revertPing) await this.revertPing(sessionID, startAt);
+    } catch (err) {
+      this.logger.warn(`ping ${short(sessionID)} failed`, errText(err));
+    } finally {
+      s.warming = false;
+      s.nextPingAt = Date.now() + jitter(this.config.intervalMs);
+      this.store.persist();
+    }
+  }
+  /** Remove the `~` user + `~` assistant turn so it never enters real context. */
+  async revertPing(sessionID, startAt) {
+    let messages;
+    try {
+      const res = await this.client.session.messages({ path: { id: sessionID } });
+      messages = res?.data ?? res ?? [];
+    } catch (err) {
+      this.logger.warn(`ping ${short(sessionID)} revert: list failed`, errText(err));
+      return;
+    }
+    let target;
+    for (const m of messages) {
+      if (m?.info?.role !== "user") continue;
+      if (Number(m.info?.time?.created ?? 0) < startAt - 2e3) continue;
+      const text = (m.parts ?? []).filter((p) => p?.type === "text").map((p) => p?.text ?? "").join("").trim();
+      if (text === this.config.pingToken) target = m.info.id;
+    }
+    if (!target) {
+      this.logger.dbg(`ping ${short(sessionID)} revert: ping message not found`);
+      return;
+    }
+    try {
+      await this.client.session.revert({
+        path: { id: sessionID },
+        body: { messageID: target }
+      });
+    } catch (err) {
+      this.logger.warn(`ping ${short(sessionID)} revert failed`, errText(err));
+    }
+  }
+  async resolveSession(s) {
+    try {
+      const res = await this.client.session.get({ path: { id: s.sessionID } });
+      const info = res?.data ?? res;
+      if (info?.parentID && !this.config.includeChildSessions) {
+        s.eligible = false;
+        s.modelLabel = info?.model?.id ?? "child";
+        return;
+      }
+      s.modelLabel = info?.model?.id ?? "unknown";
+      s.eligible = isEligibleModel(this.config, info?.model?.providerID, info?.model?.id);
+    } catch (err) {
+      s.eligible = false;
+      this.logger.dbg(`resolve ${short(s.sessionID)} failed`, errText(err));
+    }
+  }
+  pollControl() {
+    const control = readControl();
+    if (!control || control.updatedAt <= this.controlUpdatedAt) return;
+    this.controlUpdatedAt = control.updatedAt;
+    if (control.enabled === this.enabled) return;
+    this.enabled = control.enabled;
+    this.store.setEnabled(control.enabled);
+    const now = Date.now();
+    for (const session of this.store.all()) {
+      if (!control.enabled) {
+        session.active = false;
+        continue;
+      }
+      if (!session.eligible || session.busy || session.warming) continue;
+      if (!session.lastResponseAt) session.lastResponseAt = now;
+      session.idleSince = now;
+      session.windowEndsAt = now + this.config.windowMs;
+      session.nextPingAt = now + this.config.intervalMs;
+      session.pingsSent = 0;
+      session.lastPing = void 0;
+      session.active = true;
+    }
+    this.store.persist();
+    this.logger.info(`runtime ${control.enabled ? "enabled" : "disabled"}`);
+  }
+  /** Recover when a session.status idle event is missed by reconciling with the API. */
+  async reconcileStatus() {
+    if (this.reconcilingStatus) return;
+    const busy = this.store.all().filter((session) => session.busy && !session.warming);
+    if (busy.length === 0) return;
+    this.reconcilingStatus = true;
+    try {
+      const res = await this.client.session.status();
+      const statuses = res?.data ?? res ?? {};
+      for (const session of busy) {
+        const status = statuses?.[session.sessionID]?.type ?? "idle";
+        if (status === "idle") await this.armWindow(session.sessionID);
+      }
+    } catch (err) {
+      this.logger.dbg("status reconciliation failed", errText(err));
+    } finally {
+      this.reconcilingStatus = false;
+    }
+  }
+};
+function short(sessionID) {
+  return sessionID.slice(-6);
+}
+function jitter(base) {
+  return Math.max(1e3, base + Math.floor((Math.random() * 2 - 1) * JITTER_MS));
+}
+function errText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// lib/logger.ts
+var PREFIX = "[cache-keepalive]";
+var Logger = class {
+  constructor(debug) {
+    this.debug = debug;
+  }
+  debug;
+  info(message, data) {
+    if (this.debug) console.log(`${PREFIX} ${message}`, data ?? "");
+  }
+  warn(message, data) {
+    console.warn(`${PREFIX} ${message}`, data ?? "");
+  }
+  error(message, data) {
+    console.error(`${PREFIX} ${message}`, data ?? "");
+  }
+  dbg(message, data) {
+    if (this.debug) console.log(`${PREFIX}:debug ${message}`, data ?? "");
+  }
+};
+
+// lib/state.ts
+import { mkdir as mkdir2, rename as rename2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2 } from "path";
+var KeepaliveStore = class {
+  constructor(config, directory) {
+    this.config = config;
+    this.directory = directory;
+    this.enabled = config.enabled;
+  }
+  config;
+  directory;
+  sessions = /* @__PURE__ */ new Map();
+  writeQueue = Promise.resolve();
+  enabled;
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  get(sessionID) {
+    return this.sessions.get(sessionID);
+  }
+  ensure(sessionID) {
+    const existing = this.sessions.get(sessionID);
+    if (existing) return existing;
+    const created = {
+      sessionID,
+      eligible: false,
+      lastResponseAt: 0,
+      idleSince: 0,
+      windowEndsAt: 0,
+      nextPingAt: 0,
+      pingsSent: 0,
+      busy: false,
+      warming: false,
+      active: false
+    };
+    this.sessions.set(sessionID, created);
+    return created;
+  }
+  remove(sessionID) {
+    this.sessions.delete(sessionID);
+  }
+  all() {
+    return [...this.sessions.values()];
+  }
+  /** Atomically persist a lean snapshot for the TUI. Never throws to callers. */
+  persist() {
+    const snapshot = {
+      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
+          }
+        ])
+      )
+    };
+    const write = () => atomicWrite(stateFilePath(this.directory), JSON.stringify(snapshot));
+    this.writeQueue = this.writeQueue.then(write, write);
+  }
+};
+async function atomicWrite(path, contents) {
+  try {
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await mkdir2(dirname2(path), { recursive: true });
+    await writeFile2(tmp, `${contents}
+`, "utf8");
+    await rename2(tmp, path);
+  } catch {
+  }
+}
+
+// lib/system.ts
+function keepaliveInstruction(pingToken) {
+  return [
+    "<cache_keepalive>",
+    `A user message consisting of exactly the single token "${pingToken}" is an`,
+    "automated cache-keepalive ping, not a real request. When you receive it,",
+    `reply with exactly "${pingToken}" and nothing else. Do not call any tools,`,
+    "do not explain, and do not take any action.",
+    "</cache_keepalive>"
+  ].join("\n");
+}
+
+// index.ts
+var server = async (ctx, options) => {
+  const config = getConfig(options);
+  const logger = new Logger(config.debug);
+  if (!config.enabled) {
+    logger.info("disabled via config");
+    return {};
+  }
+  if (isSecureMode()) configureClientAuth(ctx.client);
+  const store = new KeepaliveStore(config, ctx.directory);
+  const engine = new KeepaliveEngine(ctx.client, config, store, logger);
+  engine.start();
+  const version = true ? "0.1.0" : "dev";
+  logger.info(`v${version} ready`);
+  const instruction = keepaliveInstruction(config.pingToken);
+  return {
+    event: async ({ event }) => {
+      await engine.onEvent(event);
+    },
+    // Keep the system prefix identical between real turns and pings, and make
+    // the model answer a ping with a single token.
+    "experimental.chat.system.transform": async (input, output) => {
+      if (!config.injectSystemInstruction) return;
+      const model = input.model;
+      if (!isEligibleModel(config, model?.providerID, model?.id ?? model?.modelID)) return;
+      output.system.push(instruction);
+    },
+    // Backstop: if the model ignores the instruction and tries a tool during a
+    // ping, block it — the ping turn is going to be reverted anyway.
+    "tool.execute.before": async (input) => {
+      if (engine.isWarming(input.sessionID)) {
+        throw new Error("cache-keepalive: tools are disabled during a keepalive ping");
+      }
+    },
+    dispose: async () => {
+      engine.stop();
+    }
+  };
+};
+var index_default = server;
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map