claude-cache-keepalive 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,9 @@
 # claude-cache-keepalive (`cwarm`)
 
+[![CI](https://github.com/fifthadj/claude-cache-keepalive/actions/workflows/test.yml/badge.svg)](https://github.com/fifthadj/claude-cache-keepalive/actions/workflows/test.yml)
+[![npm version](https://img.shields.io/npm/v/claude-cache-keepalive.svg)](https://www.npmjs.com/package/claude-cache-keepalive)
+[![license: MIT](https://img.shields.io/npm/l/claude-cache-keepalive.svg)](./LICENSE)
+
 Keep [Claude Code](https://claude.com/claude-code)'s **prompt cache warm while you're idle**, so coming back to a session you stepped away from doesn't pay a full cache‑miss.
 
 It runs `claude` inside a PTY it controls (via [node-pty](https://github.com/microsoft/node-pty)) and, when you've been idle past your plan's cache TTL, injects a tiny keepalive so the cache stays warm. Because injection is an in‑process PTY write, **it keeps working when the window is unfocused, minimized, or in the background** — only closing the window stops it.
@@ -35,7 +39,7 @@ It's transparent — type and use claude exactly as normal (no `Ctrl-b` prefix,
 ## How it works
 
 - **PTY host** — `cwarm` spawns `claude` inside a pseudo‑terminal it owns and transparently pipes your keyboard ↔ claude ↔ screen (and window resizes). This is the same approach tmux / expect / VS Code's terminal use, and the only robust way to inject input into a terminal program.
-- **Idle detection** — idle = time since your last keystroke. Self‑contained, no external files. When you step away, idle grows; when you type, it resets.
+- **Idle detection** — idle = time since your last **message**, measured from the newest transcript file under `~/.claude/projects/`. This is what actually governs cache age: scrolling, arrow‑key reading, or a half‑typed prompt are terminal input but don't refresh the cache, so they must *not* count as activity. (Earlier versions timed keystrokes, which let the cache go cold while you were reading.)
 - **Plan‑aware** — reads your plan from `~/.claude/.credentials.json`:
   - **Max** → cache TTL 1 h → inject after ~58 min idle, cooldown 1 h.
   - **Pro** → cache TTL 5 min → inject after ~4 min idle, cooldown 5 min.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cache-keepalive",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Keep Claude Code's prompt cache warm while idle, by running claude inside a PTY host and injecting a tiny keepalive when you step away. Cross-platform, no tmux required.",
   "type": "module",
   "bin": {

package/src/host.mjs

@@ -5,7 +5,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { defaultClaudeDir, planParams, detectPlan, decideInject } from './keepalive.mjs';
+import { defaultClaudeDir, planParams, detectPlan, decideInject, transcriptIdleMs } from './keepalive.mjs';
 
 const require = createRequire(import.meta.url);
 const isWin = process.platform === 'win32';
@@ -48,10 +48,11 @@ export function startHost(opts = {}) {
 
   // ---- 透明 I/O 多工 ----
   // 直接寫 Buffer（純位元組轉送）：UTF-8 多位元組（中文等）才不會被重編碼弄壞。
-  let lastInput = Date.now();
+  // 注意：閒置判斷改看 transcript mtime（距上次「訊息」多久），不再用 stdin 計時——
+  // 終端輸入（捲動／讀回覆／打到一半沒送出）不會刷新 cache，拿來計時會誤判成「使用者還在忙」。
   if (process.stdin.isTTY) { try { process.stdin.setRawMode(true); } catch {} }
   process.stdin.resume();
-  process.stdin.on('data', (d) => { lastInput = Date.now(); ptyProc.write(d); });
+  process.stdin.on('data', (d) => { ptyProc.write(d); });
   ptyProc.onData((d) => process.stdout.write(d));
   process.stdout.on('resize', () => {
     try { ptyProc.resize(process.stdout.columns || 80, process.stdout.rows || 24); } catch {}
@@ -71,10 +72,11 @@ export function startHost(opts = {}) {
     const plan = detectPlan(claudeDir);
     const { ttl, idleThreshold } = planParams(plan, overrides);
     const now = Date.now();
-    if (decideInject({ now, lastInput, lastFire, idleThreshold, ttl, disabled: fs.existsSync(DISABLE) })) {
+    const idleMs = transcriptIdleMs(claudeDir, process.cwd(), now);
+    if (decideInject({ now, idleMs, lastFire, idleThreshold, ttl, disabled: fs.existsSync(DISABLE) })) {
       ptyProc.write(msg + '\r');
       lastFire = now;
-      const idle = Math.round((now - lastInput) / 1000);
+      const idle = idleMs == null ? -1 : Math.round(idleMs / 1000);
       try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" plan=${plan} idle=${idle}s\n`); } catch {}
     }
   }, tickMs);

package/src/keepalive.mjs

@@ -1,4 +1,4 @@
-// keepalive.mjs — 純決策邏輯 + plan 偵測（無 PTY、無副作用，便於單元測試）。
+// keepalive.mjs — 決策邏輯 + plan / 閒置偵測（無 PTY，便於單元測試）。
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -31,11 +31,57 @@ export function detectPlan(claudeDir = defaultClaudeDir()) {
   }
 }
 
-// 純決策：現在該不該注入 keepalive？
-//   idle = now - lastInput（使用者最後一次按鍵到現在）。自包含、跨平台、不依賴外部檔。
-export function decideInject({ now, lastInput, lastFire, idleThreshold, ttl, disabled }) {
-  if (disabled) return false;                              // 暫停開關
-  if (now - lastInput < idleThreshold * 1000) return false; // 使用者最近還在操作
-  if (now - lastFire < ttl * 1000) return false;            // 冷卻未滿一個 TTL
+// Claude Code 把 transcript 存在 ~/.claude/projects/<編碼後的 cwd>/<uuid>.jsonl，
+// 編碼規則為「非英數字元一律換成 '-'」（例：C:\temp\scripts\cwarm → C--temp-scripts-cwarm）。
+export function encodeProjectDir(cwd) {
+  return String(cwd).replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+// 某資料夾內所有 *.jsonl 的最新 mtime（毫秒）；沒有則 null。
+function newestJsonlMtime(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return null; }
+  let newest = null;
+  for (const name of entries) {
+    if (!name.endsWith('.jsonl')) continue;
+    try {
+      const m = fs.statSync(path.join(dir, name)).mtimeMs;
+      if (newest == null || m > newest) newest = m;
+    } catch { /* skip unreadable */ }
+  }
+  return newest;
+}
+
+// 本 session transcript 的最新 mtime（毫秒）：優先 cwd 對應的 project 資料夾，
+// 找不到再退回 projects 底下全域最新（cwarm 本就假設單一 session）。null = 完全找不到。
+export function transcriptMtimeMs(claudeDir, cwd) {
+  const projects = path.join(claudeDir, 'projects');
+  const direct = newestJsonlMtime(path.join(projects, encodeProjectDir(cwd)));
+  if (direct != null) return direct;
+  let subdirs;
+  try { subdirs = fs.readdirSync(projects, { withFileTypes: true }); } catch { return null; }
+  let newest = null;
+  for (const d of subdirs) {
+    if (!d.isDirectory()) continue;
+    const m = newestJsonlMtime(path.join(projects, d.name));
+    if (m != null && (newest == null || m > newest)) newest = m;
+  }
+  return newest;
+}
+
+// 距上次訊息（transcript 寫入）多久（毫秒）；找不到 transcript 回 null。
+// 這才是 prompt cache 年齡的正確訊號——終端「輸入」（捲動／讀回覆／打到一半沒送出）
+// 都不會刷新 cache，故不以 stdin 計時，改看 transcript mtime。
+export function transcriptIdleMs(claudeDir, cwd, now = Date.now()) {
+  const m = transcriptMtimeMs(claudeDir, cwd);
+  return m == null ? null : now - m;
+}
+
+// 純決策：現在該不該注入 keepalive？idleMs = 距上次訊息多久（由 transcriptIdleMs 算）。
+export function decideInject({ now, idleMs, lastFire, idleThreshold, ttl, disabled }) {
+  if (disabled) return false;                          // 暫停開關
+  if (idleMs == null) return false;                    // 找不到 transcript → 保守不發
+  if (idleMs < idleThreshold * 1000) return false;     // 距上次訊息還不夠久
+  if (now - lastFire < ttl * 1000) return false;       // 冷卻未滿一個 TTL
   return true;
 }