claude-cache-keepalive 0.1.0 → 0.1.3

package/README.md

@@ -1,12 +1,16 @@
 # 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.
+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 cache's 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.
 
 Cross‑platform, **no tmux required**. This is the missing piece for setups (Windows / Git Bash, plain terminals) where the usual tmux‑based keepalive isn't available.
 
-> ⚠️ **Honest note — this uses your usage/quota.** Keeping the cache warm means sending a small message (`hi`) when you go idle, which counts against your plan usage and leaves `hi` turns in the conversation. It only fires after a long idle (≈58 min on Max, ≈4 min on Pro) with a one‑TTL cooldown, so it's conservative — but it is opt‑in by design. If that trade‑off isn't for you, don't use it.
+> ⚠️ **Honest note — this uses your usage/quota.** Keeping the cache warm means sending a small message (`hi`) when you go idle, which counts against your plan usage and leaves `hi` turns in the conversation. It only fires after a long idle (≈58 min on a 1‑hour cache, ≈4 min on a 5‑minute cache) with a one‑TTL cooldown, so it's conservative — but it is opt‑in by design. If that trade‑off isn't for you, don't use it.
 
 ## Install
 
@@ -35,10 +39,11 @@ 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.
-- **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.
+- **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.)
+- **TTL‑aware (measured, not guessed)** — the cache TTL is read straight from the transcript's `message.usage.cache_creation`, not inferred from your subscription:
+  - any recent turn wrote `ephemeral_1h_input_tokens` → **1 h cache** → inject after ~58 min idle, cooldown 1 h.
+  - only `ephemeral_5m_input_tokens` (or no evidence yet) → **5 min cache** (conservative) → inject after ~4 min idle, cooldown 5 min.
+  - This survives client‑version, env‑var and server‑flag changes that the plan string can't see (e.g. a Pro account can still get a 1 h cache).
 - **Focus/minimize independent** — injection is an in‑process `pty.write`, unrelated to window state. Only closing the window (ending the host process) stops it.
 
 ## Optional: cache‑countdown statusline
@@ -87,9 +92,9 @@ Environment variables (mostly for testing / advanced use):
 
 讓 [Claude Code](https://claude.com/claude-code) 的 **prompt cache 在你離開時保持溫熱**，回來時就不必再付一次完整的 cache‑miss。
 
-`cwarm` 把 `claude` 跑在自己控制的 PTY 裡；當你閒置超過方案的 cache TTL 時，注入一個極小的 keepalive 訊息讓 cache 不過期。因為注入是行程內部的 PTY 寫入，**視窗非焦點、縮小、在背景都照常運作**——只有關閉視窗才會停。跨平台、**不需要 tmux**。
+`cwarm` 把 `claude` 跑在自己控制的 PTY 裡；當你閒置超過 cache 的 TTL 時，注入一個極小的 keepalive 訊息讓 cache 不過期。因為注入是行程內部的 PTY 寫入，**視窗非焦點、縮小、在背景都照常運作**——只有關閉視窗才會停。跨平台、**不需要 tmux**。
 
-> ⚠️ **誠實說明**：保溫＝閒置時送一則小訊息（`hi`），會消耗你的方案用量、並在對話留下 `hi` 紀錄。只在長時間閒置後才觸發（Max 約 58 分、Pro 約 4 分）且有冷卻，屬保守設計、明確 opt‑in。不接受這個取捨就別用。
+> ⚠️ **誠實說明**：保溫＝閒置時送一則小訊息（`hi`），會消耗你的方案用量、並在對話留下 `hi` 紀錄。只在長時間閒置後才觸發（1h cache 約 58 分、5m cache 約 4 分）且有冷卻，屬保守設計、明確 opt‑in。不接受這個取捨就別用。
 
 - **安裝**：`npm install -g claude-cache-keepalive`
 - **使用**：`cwarm`（＝`claude --continue` 跑在保溫 host 裡；其餘參數原樣轉給 claude）
@@ -97,6 +102,17 @@ Environment variables (mostly for testing / advanced use):
 - **選配 statusline**（顯示 `♻️ cache 58m12s` 倒數；會先備份、包裝既有 statusline、可一鍵還原）：`cwarm setup` / `cwarm setup --remove`
 - **限制**：不能 detach（關視窗＝結束，但縮小／背景照常保溫）。
 
+## Changelog
+
+### 0.1.3
+- **Change:** the cache TTL is now **measured from the transcript** (`message.usage.cache_creation`'s `ephemeral_1h` / `ephemeral_5m` tokens) instead of being guessed from your subscription plan. A recent 1h write → 1h regime; only 5m writes (or no evidence) → 5m regime (conservative). This drops the `~/.claude/.credentials.json` read entirely and is correct even when a Pro account gets a 1h cache. Adds `transcriptPath` / `readTtlRegime` / `detectTtlRegime` / `regimeParams`; removes `detectPlan` / `planParams`.
+
+### 0.1.2
+- **Fix:** idle is now measured from the newest transcript file's mtime — i.e. time since your last *message* — instead of keystrokes. Scrolling, arrow‑key reading, or a half‑typed prompt no longer reset the idle timer, so the keepalive actually fires while you're reading and the cache stops going cold. Adds `encodeProjectDir` / `transcriptMtimeMs` / `transcriptIdleMs`.
+
+### 0.1.0
+- Initial release. (0.1.1 was a version‑only bump and was never published to npm.)
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-cache-keepalive",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "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/cli.mjs

@@ -27,8 +27,10 @@ Usage:
 Everything except the 'setup' subcommand is passed straight to claude
 (e.g. \`cwarm --version\`, \`cwarm resume\`, \`cwarm -p "..."\`).
 
-Keepalive only fires after you've been idle past the plan threshold
-(max ~58min / pro ~4min). Pause anytime:  touch ~/.claude/cwarm.disabled
+Keepalive only fires after you've been idle past the cache-TTL threshold.
+The TTL is auto-detected from the transcript's cache_creation (1h cache ->
+fire after ~58min idle; 5m cache -> ~4min), not guessed from your plan.
+Pause anytime:  touch ~/.claude/cwarm.disabled
 Log:  ~/.claude/cwarm-keepalive.log
 `);
 }

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, regimeParams, detectTtlRegime, 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 {}
@@ -68,14 +69,16 @@ export function startHost(opts = {}) {
 
   let lastFire = 0;
   const timer = setInterval(() => {
-    const plan = detectPlan(claudeDir);
-    const { ttl, idleThreshold } = planParams(plan, overrides);
+    const cwd = process.cwd();
+    const regime = detectTtlRegime(claudeDir, cwd);           // 從 transcript 實測 1h/5m，不再猜方案
+    const { ttl, idleThreshold } = regimeParams(regime, overrides);
     const now = Date.now();
-    if (decideInject({ now, lastInput, lastFire, idleThreshold, ttl, disabled: fs.existsSync(DISABLE) })) {
+    const idleMs = transcriptIdleMs(claudeDir, 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);
-      try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" plan=${plan} idle=${idle}s\n`); } catch {}
+      const idle = idleMs == null ? -1 : Math.round(idleMs / 1000);
+      try { fs.appendFileSync(LOG, `${new Date().toISOString()} inject "${msg}" regime=${regime ?? 'unknown'} idle=${idle}s\n`); } catch {}
     }
   }, tickMs);
 

package/src/keepalive.mjs

@@ -1,16 +1,17 @@
-// keepalive.mjs — 純決策邏輯 + plan 偵測（無 PTY、無副作用，便於單元測試）。
+// keepalive.mjs — 決策邏輯 + TTL 檔位 / 閒置偵測（無 PTY，便於單元測試）。
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-// plan → { ttl(秒), idleThreshold(秒) }。對齊各家慣例：max 提早 ~2 分注入、pro 提早 1 分。
-export const PLAN_PARAMS = {
-  max: { ttl: 3600, idleThreshold: 3480 },
-  pro: { ttl: 300, idleThreshold: 240 },
+// TTL 檔位 → { ttl(秒), idleThreshold(秒) }。long=1h cache、short=5m cache。
+// 提早注入幅度對齊各家慣例：long 提早 ~2 分、short 提早 1 分。
+export const REGIME_PARAMS = {
+  long: { ttl: 3600, idleThreshold: 3480 },
+  short: { ttl: 300, idleThreshold: 240 },
 };
 
-export function planParams(plan, overrides = {}) {
-  const base = PLAN_PARAMS[plan] || PLAN_PARAMS.pro;
+export function regimeParams(regime, overrides = {}) {
+  const base = REGIME_PARAMS[regime] || REGIME_PARAMS.short; // 未知一律 short（保守，門檻短不讓 cache 冷掉）
   return {
     ttl: overrides.ttl ?? base.ttl,
     idleThreshold: overrides.idleThreshold ?? base.idleThreshold,
@@ -21,21 +22,115 @@ export function defaultClaudeDir() {
   return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 }
 
-// 從 Claude Code 憑證判方案；讀不到一律當 'pro'（保守）。
-export function detectPlan(claudeDir = defaultClaudeDir()) {
+// 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, '-');
+}
+
+// 某資料夾內 mtime 最新的 *.jsonl 完整路徑；沒有則 null。
+function newestJsonlPath(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return null; }
+  let best = null, bestM = null;
+  for (const name of entries) {
+    if (!name.endsWith('.jsonl')) continue;
+    try {
+      const m = fs.statSync(path.join(dir, name)).mtimeMs;
+      if (bestM == null || m > bestM) { bestM = m; best = path.join(dir, name); }
+    } catch { /* skip unreadable */ }
+  }
+  return best;
+}
+
+// 本 session transcript 的完整路徑：優先 cwd 對應的 project 資料夾，
+// 找不到再退回 projects 底下全域最新（cwarm 本就假設單一 session）。null = 完全找不到。
+export function transcriptPath(claudeDir, cwd) {
+  const projects = path.join(claudeDir, 'projects');
+  const direct = newestJsonlPath(path.join(projects, encodeProjectDir(cwd)));
+  if (direct != null) return direct;
+  let subdirs;
+  try { subdirs = fs.readdirSync(projects, { withFileTypes: true }); } catch { return null; }
+  let best = null, bestM = null;
+  for (const d of subdirs) {
+    if (!d.isDirectory()) continue;
+    const p = newestJsonlPath(path.join(projects, d.name));
+    if (p == null) continue;
+    try {
+      const m = fs.statSync(p).mtimeMs;
+      if (bestM == null || m > bestM) { bestM = m; best = p; }
+    } catch { /* skip */ }
+  }
+  return best;
+}
+
+// 本 session transcript 的最新 mtime（毫秒）；null = 完全找不到。
+export function transcriptMtimeMs(claudeDir, cwd) {
+  const p = transcriptPath(claudeDir, cwd);
+  if (!p) return null;
+  try { return fs.statSync(p).mtimeMs; } catch { return null; }
+}
+
+// 距上次訊息（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;
+}
+
+// 讀 transcript 尾端，判斷這個 session 實際拿到的 cache TTL 檔位。
+// 回傳 'long'(1h) / 'short'(5m) / null（找不到可判讀的 cache_creation）。
+// 為什麼讀 transcript 而非帳號方案：message.usage.cache_creation 的
+// ephemeral_1h_input_tokens / ephemeral_5m_input_tokens 是 API 親口回報「這批 token
+// 寫進哪個 TTL 桶」的實測值；subscriptionType 只是間接猜測，且會被 client 版本、
+// 環境變數、伺服器端旗標影響而失準（實測 pro 帳號也可能拿到 1h）。
+export function readTtlRegime(tpath, { maxBytes = 65536, scanTurns = 8 } = {}) {
+  if (!tpath) return null;
+  let size, buf;
+  let fd = null;
   try {
-    const cred = JSON.parse(fs.readFileSync(path.join(claudeDir, '.credentials.json'), 'utf8'));
-    return cred?.claudeAiOauth?.subscriptionType === 'max' ? 'max' : 'pro';
+    size = fs.statSync(tpath).size;
+    const start = Math.max(0, size - maxBytes);
+    const len = size - start;
+    buf = Buffer.alloc(len);
+    fd = fs.openSync(tpath, 'r');
+    fs.readSync(fd, buf, 0, len, start);
   } catch {
-    return 'pro';
+    return null;
+  } finally {
+    if (fd != null) { try { fs.closeSync(fd); } catch {} }
   }
+  let lines = buf.toString('utf8').split(/\r?\n/);
+  if (size > maxBytes && lines.length) lines = lines.slice(1); // 丟掉被切半的第一行
+  let sawShort = false;
+  let examined = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || obj.type !== 'assistant') continue;
+    const cc = obj.message && obj.message.usage && obj.message.usage.cache_creation;
+    if (!cc || typeof cc !== 'object') continue;
+    const h = cc.ephemeral_1h_input_tokens || 0;
+    const m = cc.ephemeral_5m_input_tokens || 0;
+    if (h > 0) return 'long';                 // 最近任一回合寫過 1h → 1h 檔位（決定性）
+    if (m > 0) { sawShort = true; if (++examined >= scanTurns) break; } // 只看最近數筆有寫 cache 的回合
+  }
+  return sawShort ? 'short' : null;
+}
+
+// 找出本 session transcript 並判斷 TTL 檔位。'long' / 'short' / null。
+export function detectTtlRegime(claudeDir, cwd, opts) {
+  return readTtlRegime(transcriptPath(claudeDir, cwd), opts);
 }
 
-// 純決策：現在該不該注入 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
+// 純決策：現在該不該注入 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;
 }

package/src/statusline/segment.mjs

@@ -4,7 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { defaultClaudeDir, detectPlan } from '../keepalive.mjs';
+import { defaultClaudeDir, readTtlRegime, regimeParams } from '../keepalive.mjs';
 
 const claudeDir = defaultClaudeDir();
 const ORIG = path.join(claudeDir, 'cwarm-statusline-orig.json');
@@ -13,14 +13,14 @@ function readStdin() {
   try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
 }
 
-// cache 倒數段：用 transcript mtime 當 idle、plan 決定 TTL（max 1h / pro 5min）。
+// cache 倒數段：用 transcript mtime 當 idle、用 transcript 實測的 cache_creation 判 TTL（1h / 5m）。
 function cacheSegment(payload) {
   const tp = payload?.transcript_path;
   if (!tp) return '';
   let mtimeMs;
   try { mtimeMs = fs.statSync(tp).mtimeMs; } catch { return ''; }
-  const plan = detectPlan(claudeDir);
-  const ttl = plan === 'max' ? 3600 : 300;
+  const { ttl } = regimeParams(readTtlRegime(tp));   // 'long'→3600 / 'short'|null→300
+
   const idle = Math.max(0, Math.floor((Date.now() - mtimeMs) / 1000));
   const rem = ttl - idle;
   if (rem <= 0) return `\u{1F534} cache ${Math.floor(idle / 60)}m`;      // 🔴 已冷