pi-kimi-keepalive 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Prompt-cache keepalive for [Kimi](https://www.kimi.com/) (`kimi-coding` provider) sessions in the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
 
-Kimi's automatic prompt cache has an observed TTL of ~5 minutes. Once it expires, the next request re-reads the full context at full input price. This extension captures the last real provider request and replays it on a fixed interval while the session is idle, so the cached prefix stays warm and subsequent requests are billed at cache-read rates.
+Kimi's automatic prompt cache nominally expires after ~5 minutes of idle, but real-world testing shows the live TTL runs longer — probes as far apart as 8 minutes still hit reliably. Once the cache does expire, the next request re-reads the full context at full input price. This extension captures the last real provider request and replays it on a fixed interval while the session is idle, so the cached prefix stays warm and subsequent requests are billed at cache-read rates.
 
 Replayed requests are sent directly to the provider endpoint. They do not pass through the Pi session pipeline: no synthetic messages, no model turns, no changes to conversation history. Only aggregate statistics are surfaced.
 
@@ -30,18 +30,35 @@ After the package is published to npm: `pi install npm:pi-kimi-keepalive`.
 
 ## Setup
 
-On the first start with no `~/.pi/cache-keepalive/state.json` present and an interactive UI, the extension runs a setup wizard that configures the four guardrails below. Leaving a prompt empty or pressing Esc keeps the default. The wizard can be rerun with `/keepalive setup`; in headless sessions it is skipped and defaults are kept.
+On the first start with no `~/.pi/cache-keepalive/state.json` present and an interactive UI, the extension runs a setup wizard that configures the five settings below. Leaving a prompt empty or pressing Esc keeps the default. The wizard can be rerun with `/keepalive setup`; in headless sessions it is skipped and defaults are kept.
 
 | Step | Setting | Command | Default | Description |
 | --- | --- | --- | --- | --- |
 | 1 | Max idle cutoff | `maxidle` | `30m` | Probing stops after this much idle time; `0` disables the cutoff. |
-| 2 | Miss pause threshold | `miss` | `1` | Pause after N consecutive probes that do not hit the prompt cache. A hit resets the count. |
+| 2 | Miss pause threshold | `miss` | `1` | Pause after N consecutive probes that do not hit the prompt cache. A hit resets the count. Applies in `default` mode. |
 | 3 | Error circuit breaker | `errors` | `3` | Pause after N consecutive probe failures (network errors, HTTP 5xx). HTTP 401/403 always pauses immediately. |
 | 4 | Session spend cap | `cap` | `$1.00` | Ceiling on estimated USD probe spend per session; `0` removes the cap. |
+| 5 | Probing mode | `mode` | `default` | `default` keeps the fixed cadence; `smart` self-tunes it (below). |
 
 The wizard ends with a prompt to enable keepalive. Probing starts after the next real turn, which provides the captured request.
 
-Two operating points are worth knowing. The default cadence is **7 minutes** — deliberately past the ~5-minute cache TTL. A 7-minute probe never hits the cache: it runs once at full input price, confirms the cache has expired, and the default `miss=1` stops probing immediately, so the worst case is a single cold read per idle period. For an always-warm session instead, set a cadence inside the TTL (`/keepalive interval=4m45s`): every probe is then billed at cache-read rates (~1/10 of full price) and the loop keeps running until `maxidle` cuts it off.
+## Probing modes
+
+Two modes share the same guardrails; they differ in how the cadence is chosen.
+
+**`default` (the starting mode)** — the cadence is fixed at whatever `interval=` says, **8 minutes** by default. Real-world testing shows probes at this cadence reliably hit the prefix cache (the effective TTL runs longer than the ~5-minute nominal one), so the default cadence already works as the always-warm heartbeat: every probe renews the cache at cache-read rates (~1/10 of full input price) until `maxidle` cuts the loop off.
+
+If the cache does expire underneath it (server-side eviction, TTL change), the mode self-heals instead of giving up: the missed probe itself rebuilds the cache entry with the same prefix, so the cadence drops to the **5-minute safe floor** (inside the nominal TTL), probing continues, and the next probe renews the entry. Only a miss **at** the 5-minute floor counts toward the `miss` pause threshold — a cache that cannot even be rebuilt at 5m is an environment problem, and the default `miss=1` stops probing there. The back-off is persisted; `/keepalive interval=8m` returns to the original cadence.
+
+**`smart` (`/keepalive mode=smart`)** — self-tunes the cadence toward the real cache TTL instead of guessing it:
+
+1. Starts at **8 minutes**.
+2. After **3 consecutive hits** the cadence is confirmed and the value grows by **+30s**. Only confirmed values are persisted, so `~/.pi/cache-keepalive/state.json` always holds the largest cadence with observed consecutive hits.
+3. A **miss** immediately parks probing: the cadence steps back **30s** to the last confirmed value (never below the 8m floor), the value is persisted, and probing stays **stopped**. A fresh real turn does **not** resume it — only re-selecting smart mode (`/keepalive mode=smart`) continues from the parked cadence.
+4. **Context guard:** growth only happens while the last probe saw ≤ **200k prompt tokens**; the first probe above that immediately reverts the cadence to the 8m floor and keeps it there (a missed probe on a 200k+ context is too expensive to risk).
+5. Guardrails (`maxidle`, `cap`, `errors`, HTTP 401/403) still apply while smart is probing.
+
+Per learn cycle the spend is minimal: 3 cache-read probes confirm a step, and one full-price probe ends the cycle — the parked cadence keeps every future session at the highest value the cache has proven to hold.
 
 ## Commands
 
@@ -51,7 +68,9 @@ Two operating points are worth knowing. The default cadence is **7 minutes** —
 /keepalive on|off           enable / disable (persisted)
 /keepalive now              one manual probe (bypasses pauses)
 /keepalive resume           clear a sticky pause
-/keepalive interval=4m45s   probe cadence (≥ 30s; ≤ 5m to stay inside the cache TTL)
+/keepalive mode=smart       adaptive cadence (8m floor; +30s per 3-hit confirmation; a miss parks probing, mode=smart resumes)
+/keepalive mode=default     fixed cadence (the interval= value)
+/keepalive interval=4m45s   probe cadence in default mode (≥ 30s; default 8m reliably hits the cache in practice)
 /keepalive maxidle=30m      idle cutoff (0 = disabled)
 /keepalive miss=1           pause after N consecutive cache misses
 /keepalive errors=3         pause after N consecutive probe failures
@@ -103,7 +122,7 @@ On a Kimi subscription, billing is quota-based and USD figures are indicative on
 
 ## Limitations
 
-- The ~5 minute TTL and the pricing above are observed behavior, not an API contract. The `saved` estimate is informational, not a guaranteed saving.
+- The nominal ~5-minute TTL, the longer effective TTL observed in practice, and the pricing above are observed behavior, not an API contract. The `saved` estimate is informational, not a guaranteed saving.
 - Only the `kimi-coding` provider (`kimi-openai-completions` API, with an `anthropic-messages` fallback) is supported. Other providers have different cache-key semantics and are out of scope.
 - Captured payloads and headers live only in process memory; probes are sent only to `https://` endpoints.
 

package/README.zh-CN.md

@@ -4,7 +4,7 @@ English | [中文文档](README.zh-CN.md)
 
 Prompt-cache keepalive for [Kimi](https://www.kimi.com/) (`kimi-coding` provider) sessions in the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
 
-Kimi 的自动 prompt 缓存 TTL 实测约 5 分钟。TTL 过期后恢复会话时，整个上下文以全价 input（$3 / 1M）重新计算。本扩展捕获最后一条真实 provider 请求，在会话空闲期间以固定间隔将其重放至同一端点，使缓存前缀在 TTL 内保持有效，后续请求按 cache-read 价格（$0.3 / 1M）计费。
+Kimi 的自动 prompt 缓存名义上在空闲 ~5 分钟后过期，但实测实际 TTL 更长——间隔 8 分钟的探测仍基本稳定命中。缓存真正过期后，整个上下文以全价 input（$3 / 1M）重新计算。本扩展捕获最后一条真实 provider 请求，在会话空闲期间以固定间隔将其重放至同一端点，使缓存前缀在 TTL 内保持有效，后续请求按 cache-read 价格（$0.3 / 1M）计费。
 
 重放请求直接发送到 provider 端点，不经过 Pi 会话管道：不产生合成消息、不产生模型回合、不改动对话历史，仅在界面上展示聚合统计。
 
@@ -30,17 +30,36 @@ npm 发布后可使用 `pi install npm:pi-kimi-keepalive`。
 
 ## 初始化
 
-首次启动（`~/.pi/cache-keepalive/state.json` 不存在）且有交互 UI 时，扩展运行初始化向导配置四项护栏。提示符留空或按 Esc 保留默认值；之后可用 `/keepalive setup` 重新运行；headless 会话自动跳过并保留默认值。
+首次启动（`~/.pi/cache-keepalive/state.json` 不存在）且有交互 UI 时，扩展运行初始化向导配置五项设置。提示符留空或按 Esc 保留默认值；之后可用 `/keepalive setup` 重新运行；headless 会话自动跳过并保留默认值。
 
 | 步骤 | 设置项 | 命令 | 默认值 | 说明 |
 | --- | --- | --- | --- | --- |
 | 1 | Max idle cutoff | `maxidle` | `30m` | 空闲超过该时长后停止探测；`0` 表示不设限 |
-| 2 | Miss pause threshold | `miss` | `2` | 连续 N 次探测未命中前缀缓存后暂停；命中会重置计数 |
+| 2 | Miss pause threshold | `miss` | `1` | 连续 N 次探测未命中前缀缓存后暂停；命中会重置计数。仅在 `default` 模式下生效 |
 | 3 | Error circuit breaker | `errors` | `3` | 连续 N 次探测失败（网络错误、HTTP 5xx）后暂停；HTTP 401/403 不受此值约束，直接暂停 |
 | 4 | Session spend cap | `cap` | `$1.00` | 会话探测花费（估算 USD）上限；`0` 表示不设上限 |
+| 5 | Probing mode | `mode` | `default` | `default` 固定间隔；`smart` 自适应（见下文） |
 
 向导结束时询问是否立即启用 keepalive。探测在下一次真实请求（完成捕获）之后开始。全部配置持久化到 `~/.pi/cache-keepalive/state.json`。
 
+## 探测模式
+
+两种模式共用一套护栏，区别仅在间隔的确定方式。
+
+**`default`（默认模式）**——间隔固定为 `interval=` 所设值，默认 **8 分钟**。实测该间隔的探测基本稳定命中前缀缓存（实际 TTL 长于名义的 ~5 分钟），因此默认间隔本身就是常热心跳：每次探测以缓存读价（约为全价 input 的 1/10）续期缓存，循环持续到 `maxidle` 截断。
+
+若缓存确实在下方过期（服务端逐出、TTL 变更），该模式会自愈而非直接失效：miss 的那次探测本身会以相同前缀重建缓存条目，因此档位自动回退至 **5 分钟安全档**（名义 TTL 之内）、继续探测，下一次探测即续期成功。只有**在 5 分钟档**再 miss 才计入 `miss` 暂停阈值——连 5m 都无法重建缓存的属于环境异常，默认 `miss=1` 在此暂停。降档会持久化；`/keepalive interval=8m` 可调回原档位。
+
+**`smart`（`/keepalive mode=smart`）**——不猜测 TTL，而是自适应逼近真实值：
+
+1. 从 **8 分钟**起跳。
+2. **连续 3 次命中**后该间隔即被确认，档位 **+30s**。只有确认过的值才会持久化，因此 `~/.pi/cache-keepalive/state.json` 中始终保存的是实测可连续命中的最大档位。
+3. 一次 **miss** 立即停靠探测：档位回退 **30s** 到最近确认值（至多退到 8m 下限）并持久化，随后探测**停止**。下一次真实轮次**不会**自动恢复——只有重新选择 smart 模式（`/keepalive mode=smart`）才会从停靠档位继续探测。
+4. **上下文保护：** 只有最近一次探测的 prompt tokens ≤ **200k** 才允许升档；一旦超过，档位立即回退至 8m 下限并冻结升档（200k+ 上下文一次全价 miss 代价太高，不冒这个险）。
+5. smart 探测运行期间通用护栏（`maxidle`、`cap`、`errors`、HTTP 401/403）仍然生效。
+
+每个学习周期的花费极小：3 次缓存读价探测确认一档，一次全价探测结束本轮——停靠后的档位让之后的每个会话都直接运行在实测可行的最高值上。
+
 ## 命令
 
 ```
@@ -49,7 +68,9 @@ npm 发布后可使用 `pi install npm:pi-kimi-keepalive`。
 /keepalive on|off           启用 / 停用（持久化）
 /keepalive now              手动探测一次（绕过暂停）
 /keepalive resume           清除 sticky 暂停
-/keepalive interval=4m45s   探测间隔（≥ 30s；应 ≤ 5m 以保持缓存命中）
+/keepalive mode=smart       自适应间隔（下限 8m；每 3 连中 +30s；一次 miss 即停靠，mode=smart 恢复探测）
+/keepalive mode=default     固定间隔（即 interval= 的值）
+/keepalive interval=4m45s   default 模式下的探测间隔（≥ 30s；默认 8m 实测基本稳定命中）
 /keepalive maxidle=30m      空闲上限（0 = 不设限）
 /keepalive miss=1           连续 N 次缓存 miss 后暂停
 /keepalive errors=3         连续 N 次探测失败后熔断
@@ -99,7 +120,7 @@ Kimi 订阅按 quota 计费，USD 数值仅供参考。
 
 ## 限制
 
-- ~5 分钟 TTL 与上述定价为观测行为，非 API 契约；`saved` 仅为估算。
+- 名义 ~5 分钟 TTL、实测更长的有效 TTL 与上述定价均为观测行为，非 API 契约；`saved` 仅为估算。
 - 仅支持 `kimi-coding`（`kimi-openai-completions` API，含 `anthropic-messages` 回退）；其他 provider 缓存键语义不同，不在范围内。
 - 捕获内容仅存内存；探测仅发往 `https://` 端点。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-kimi-keepalive",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Prompt-cache keepalive for Kimi (kimi-coding) sessions in the Pi coding agent. Replays the last real provider request while idle so the automatic prefix cache never expires.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,9 @@
     "keepalive"
   ],
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": [
+      "./src/index.ts"
+    ]
   },
   "files": [
     "src",
@@ -43,4 +45,4 @@
     "@types/node": "^24",
     "typescript": "^5"
   }
-}
+}

package/src/index.ts

@@ -68,27 +68,44 @@ interface PersistedConfig {
   maxMissStreak: number;
   /** Consecutive failed probes (network/server errors) before probing pauses. */
   maxErrorStreak: number;
+  /** "default" = fixed interval; "smart" = adaptive cadence that grows while probes keep hitting. */
+  mode: "default" | "smart";
   /** True once the first-run setup wizard has completed (or been skipped). */
   initialized: boolean;
 }
 
 const DEFAULT_CONFIG: Readonly<PersistedConfig> = Object.freeze({
   enabled: false,
-  // 7 min: past the ~5 min cache TTL by design. A 7-min probe never hits the
-  // cache, so it acts as a single full-price confirmation that the cache is
-  // dead, and the default miss=1 stops probing right after — worst-case total
-  // spend is one cold read per session. Use /keepalive interval=4m45s for a
-  // hit-mode heartbeat (every probe is a cache read, ~10x cheaper).
-  intervalMs: 7 * 60_000,
+  // 8 min: real-world testing shows probes at this cadence still hit the
+  // prefix cache reliably (the effective TTL runs longer than the ~5 min
+  // nominal TTL), so the default cadence IS the hit-mode heartbeat — every
+  // probe is billed at cache-read rates (~10x cheaper than a cold read).
+  // If the cache does expire (e.g. server-side eviction), the probe misses
+  // once at full price and the default miss=1 stops probing immediately.
+  intervalMs: 8 * 60_000,
   maxIdleMs: 30 * 60_000,
   minPromptTokens: 512,
   maxOutputTokens: 16,
   spendCapUsd: 1.0,
   maxMissStreak: 1,
   maxErrorStreak: 3,
+  mode: "default",
   initialized: false,
 });
 
+// smart-mode constants
+const SMART_BASE_MS = 8 * 60_000; // smart starting/floor cadence (matches the default interval)
+const SMART_STEP_MS = 30_000; // +30s per 3-hit confirmation
+const SMART_CONFIRM_HITS = 3;
+const SMART_MAX_CONTEXT_TOKENS = 200_000; // context cap: grow only below this
+/**
+ * default-mode safe floor: the nominal cache TTL. A miss while probing above
+ * this cadence drops the cadence here and keeps probing (the miss probe
+ * itself rebuilds the cache entry, so the next ≤5m probe renews it); only a
+ * miss AT this floor counts toward the miss-pause threshold.
+ */
+const DEFAULT_FALLBACK_MS = 5 * 60_000;
+
 const MIN_INTERVAL_MS = 30_000;
 const PROBE_TIMEOUT_MS = 30_000;
 
@@ -99,7 +116,9 @@ const HELP_TEXT = [
   "  /keepalive on|off         enable / disable (persisted)",
   "  /keepalive now            one manual probe (bypasses pauses)",
   "  /keepalive resume         clear a sticky pause",
-  "  /keepalive interval=4m45s probe cadence (>= 30s; <= 5m stays inside the cache TTL)",
+  "  /keepalive mode=smart     adaptive cadence (8m floor; +30s per 3-hit confirmation; a miss parks probing, mode=smart resumes)",
+  "  /keepalive mode=default   fixed cadence (the interval= value)",
+  "  /keepalive interval=4m45s probe cadence (default mode; >= 30s; default 8m reliably hits the cache in practice)",
   "  /keepalive maxidle=30m    stop probing after this idle time (0 = never stop)",
   "  /keepalive miss=1         pause after N consecutive cache misses",
   "  /keepalive errors=3       pause after N consecutive probe failures",
@@ -144,7 +163,12 @@ export default function (pi: ExtensionAPI) {
   let pausedReason: string | null = null;
   let missStreak = 0;
   let errorStreak = 0;
-
+  // smart-mode runtime state (cadence itself lives in config.intervalMs, persisted)
+  let smartHitStreak = 0;
+  // Set when a smart-mode miss pauses probing; only re-selecting smart mode
+  // clears it (a fresh real turn does NOT resume probing in this case).
+  let smartPaused = false;
+  let lastProbeInputTokens = 0;
   const stats: Stats = { probes: 0, hits: 0, misses: 0, errors: 0, savedUsd: 0, spendUsd: 0 };
 
   // ---------- persistence ----------
@@ -177,6 +201,7 @@ export default function (pi: ExtensionAPI) {
               : DEFAULT_CONFIG.spendCapUsd,
         maxMissStreak: int(raw.maxMissStreak, DEFAULT_CONFIG.maxMissStreak, 1),
         maxErrorStreak: int(raw.maxErrorStreak, DEFAULT_CONFIG.maxErrorStreak, 1),
+        mode: raw.mode === "smart" ? "smart" : "default",
           initialized: raw.initialized === true,
       };
     } catch {
@@ -217,7 +242,7 @@ export default function (pi: ExtensionAPI) {
       config.initialized = true;
       persistConfig();
       notify(
-        "Setup skipped — defaults kept (interval 7m, maxidle 30m, miss 1, errors 3, cap $1.00). " +
+        "Setup skipped — defaults kept (mode default/8m, maxidle 30m, miss 1, errors 3, cap $1.00). " +
           "Run /keepalive setup to configure later, /keepalive on to enable.",
         "info",
       );
@@ -225,9 +250,9 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    // 1/4 — max idle cutoff
+    // 1/5 — max idle cutoff
     const maxIdleRaw = await wizardCtx.ui.input(
-      "Step 1/4 — Max idle cutoff (now " + formatDuration(config.maxIdleMs) + ")\n" +
+      "Step 1/5 — Max idle cutoff (now " + formatDuration(config.maxIdleMs) + ")\n" +
         "Stop probing once you have been idle longer than this, so a session left overnight " +
         "does not keep spending quota. Examples: 30m, 1h, 2h — or 0 to never stop.\n" +
         "Leave empty / press Esc to keep the default (30m).",
@@ -246,9 +271,9 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // 2/4 — miss pause threshold
+    // 2/5 — miss pause threshold
     const missRaw = await wizardCtx.ui.input(
-      "Step 2/4 — Miss pause threshold (now " + config.maxMissStreak + ")\n" +
+      "Step 2/5 — Miss pause threshold (now " + config.maxMissStreak + ")\n" +
         "Pause probing after this many consecutive probes that did NOT hit the prompt cache " +
         "(a cache hit resets the count). A high cache-read price with no hits means the " +
         "provider's caching behaviour changed; pausing keeps you from burning quota blindly.",
@@ -263,9 +288,9 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // 3/4 — error circuit breaker
+    // 3/5 — error circuit breaker
     const errorRaw = await wizardCtx.ui.input(
-      "Step 3/4 — Error circuit breaker (default " + config.maxErrorStreak + ")\n" +
+      "Step 3/5 — Error circuit breaker (default " + config.maxErrorStreak + ")\n" +
         "Pause probing after this many consecutive failed probes (network errors, HTTP 5xx). " +
         "Auth failures (HTTP 401/403) always pause immediately regardless of this value.",
       String(config.maxErrorStreak),
@@ -279,9 +304,9 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    // 4/4 — spend cap
+    // 4/5 — spend cap
     const spendRaw = await wizardCtx.ui.input(
-      "Step 4/4 — Session spend cap in USD (default " +
+      "Step 4/5 — Session spend cap in USD (default " +
         formatUsd(DEFAULT_CONFIG.spendCapUsd ?? 1.0) +
         ")\n" +
         "Ceiling on the estimated USD cost of probes in this session. A probe costs roughly " +
@@ -298,6 +323,27 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
+    // 5/5 — probing mode
+    const modeRaw = await wizardCtx.ui.input(
+      "Step 5/5 — Probing mode (now " + config.mode + ")\n" +
+        "default: probes run at the fixed interval above.\n" +
+        "smart: starts at 8m; after 3 consecutive hits (context ≤ 200k) the cadence grows by 30s; " +
+        "one miss steps back to the last confirmed value and parks probing until you re-select smart mode — " +
+        "it self-tunes toward the real cache TTL to minimize probe spend.\n" +
+        "Type smart to enable; leave empty / press Esc for default.",
+      "",
+    );
+    if (modeRaw !== undefined) {
+      const v = modeRaw.trim().toLowerCase();
+      if (v === "smart" || v === "default") {
+        config.mode = v;
+        smartPaused = false;
+        if (v === "smart" && config.intervalMs < SMART_BASE_MS) config.intervalMs = SMART_BASE_MS;
+      } else if (v !== "") {
+        notify(`Unknown mode "${modeRaw}" — keeping ${config.mode}`, "error");
+      }
+    }
+
     config.initialized = true;
     persistConfig();
 
@@ -314,6 +360,7 @@ export default function (pi: ExtensionAPI) {
     persistConfig();
     notify(
       "pi-kimi-keepalive configured:\n" +
+        `  mode:         ${config.mode}${config.mode === "smart" ? ` (starting at ${formatDuration(config.intervalMs)})` : ` (fixed ${formatDuration(config.intervalMs)})`}\n` +
         `  maxidle:      ${config.maxIdleMs === 0 ? "never stop" : formatDuration(config.maxIdleMs)}\n` +
         `  miss pause:   after ${config.maxMissStreak} consecutive cache misses\n` +
         `  error breaker: ${config.maxErrorStreak} consecutive failures\n` +
@@ -507,6 +554,7 @@ export default function (pi: ExtensionAPI) {
     if (!capture) return;
     stats.probes += 1;
     stats.spendUsd += estimateProbeSpendUsd(usage, capture.cost);
+    lastProbeInputTokens = usage.inputTokens;
 
     if (!isCacheMiss(usage.inputTokens, usage.cacheReadTokens, config.minPromptTokens)) {
       stats.hits += 1;
@@ -516,12 +564,34 @@ export default function (pi: ExtensionAPI) {
       debug(
         `probe hit: cache_read=${usage.cacheReadTokens} input=${usage.inputTokens} saved=${stats.savedUsd.toFixed(4)}`,
       );
+      if (config.mode === "smart") {
+        smartAdaptAfterHit(usage.inputTokens);
+      }
     } else {
       stats.misses += 1;
-      missStreak += 1;
-      debug(`probe miss #${missStreak}: cache_read=0 input=${usage.inputTokens}`);
-      if (missStreak >= config.maxMissStreak) {
-        pause("probes stopped hitting the prefix cache; waiting for your next real turn");
+      debug(`probe miss: cache_read=0 input=${usage.inputTokens}`);
+      if (config.mode === "smart") {
+        smartAdaptAfterMiss();
+      } else if (config.intervalMs > DEFAULT_FALLBACK_MS) {
+        // Miss while probing above the safe floor: the miss probe itself
+        // rebuilds the cache entry with the same prefix, so drop to the 5m
+        // safe cadence (inside the nominal TTL) and keep probing — the next
+        // probe renews it. Reset the streak so the new cadence gets a fresh
+        // chance before a pause is considered.
+        config.intervalMs = DEFAULT_FALLBACK_MS;
+        missStreak = 0;
+        persistConfig();
+        notify(
+          `cache miss — cadence backed off to ${formatDuration(config.intervalMs)} (safe TTL window); probing continues`,
+          "info",
+        );
+        updateUi();
+      } else {
+        missStreak += 1;
+        debug(`probe miss #${missStreak}: cache_read=0 input=${usage.inputTokens}`);
+        if (missStreak >= config.maxMissStreak) {
+          pause("probes stopped hitting the prefix cache; waiting for your next real turn");
+        }
       }
     }
 
@@ -536,6 +606,65 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
+  /**
+   * smart-mode cadence adaptation.
+   *
+   * config.intervalMs doubles as the persisted "last confirmed cadence":
+   * promotion only ever happens after SMART_CONFIRM_HITS consecutive hits, so
+   * the value on disk is always one the cache has actually held for. A miss
+   * steps back 30s to that last confirmed value (never below the 8m floor),
+   * persists it, and pauses probing — a fresh real turn does NOT resume;
+   * only re-selecting smart mode (`/keepalive mode=smart`) continues.
+   * Contexts above 200k tokens are never pushed upward and immediately revert
+   * to the floor cadence, because a miss there costs too much full-price
+   * input to risk.
+   */
+  function smartAdaptAfterHit(inputTokens: number): void {
+    if (inputTokens > SMART_MAX_CONTEXT_TOKENS) {
+      // Too expensive to experiment; drop to floor and stop growing.
+      if (config.intervalMs > SMART_BASE_MS) {
+        config.intervalMs = SMART_BASE_MS;
+        persistConfig();
+        notify(
+          `smart: context ${inputTokens} tokens exceeds ${SMART_MAX_CONTEXT_TOKENS / 1000}k — cadence back to the 8m floor`,
+          "info",
+        );
+      }
+      smartHitStreak = 0;
+      updateUi();
+      return;
+    }
+    smartHitStreak += 1;
+    if (smartHitStreak < SMART_CONFIRM_HITS) return;
+    const roomUnderMaxIdle =
+      config.maxIdleMs === 0 || config.intervalMs + SMART_STEP_MS < config.maxIdleMs;
+    if (roomUnderMaxIdle) {
+      config.intervalMs += SMART_STEP_MS; // 3-hit-confirmed value stays on disk
+      persistConfig();
+      debug(
+        `smart: ${smartHitStreak} consecutive hits — cadence grows to ${formatDuration(config.intervalMs)}`,
+      );
+    }
+    smartHitStreak = 0;
+    updateUi();
+  }
+
+  function smartAdaptAfterMiss(): void {
+    smartHitStreak = 0;
+    const fellBack = config.intervalMs > SMART_BASE_MS;
+    if (fellBack) {
+      // Step back to the last confirmed cadence before pausing.
+      config.intervalMs = Math.max(SMART_BASE_MS, config.intervalMs - SMART_STEP_MS);
+      persistConfig();
+    }
+    smartPaused = true;
+    pause(
+      `cache miss in smart mode — cadence ${fellBack ? `back to ${formatDuration(config.intervalMs)}` : "already at the floor"}; ` +
+        `probing stopped, run /keepalive mode=smart to resume`,
+    );
+    updateUi();
+  }
+
   function recordFailure(message: string): void {
     stats.errors += 1;
     errorStreak += 1;
@@ -600,6 +729,7 @@ export default function (pi: ExtensionAPI) {
       "pi-kimi-keepalive",
       `  state:     ${config.enabled ? "on" : "off"}${pausedReason ? ` (paused: ${pausedReason})` : ""}`,
       `  capture:   ${route}`,
+      `  mode: ${config.mode}${config.mode === "smart" ? ` · cadence ${formatDuration(config.intervalMs)}${lastProbeInputTokens > SMART_MAX_CONTEXT_TOKENS ? ` · context ${lastProbeInputTokens.toLocaleString()} > cap, frozen at floor` : ""}` : " (fixed via interval=)"}`,
       `  interval:  ${formatDuration(config.intervalMs)} · maxidle ${config.maxIdleMs === 0 ? "off" : formatDuration(config.maxIdleMs)} · minPromptTokens ${config.minPromptTokens} · maxOutput ${config.maxOutputTokens}`,
       `  spend cap: ${config.spendCapUsd === null ? "none" : formatUsd(config.spendCapUsd)} · est. probe spend ${formatUsd(stats.spendUsd)}`,
       `  probes:    ${stats.probes} (hits ${stats.hits}, misses ${stats.misses}, errors ${stats.errors})`,
@@ -653,12 +783,44 @@ export default function (pi: ExtensionAPI) {
             }
             break;
           case "resume":
+            if (smartPaused) {
+              notify("smart-mode pause is intentional — run /keepalive mode=smart to resume probing", "warning");
+              break;
+            }
             pausedReason = null;
             missStreak = 0;
             errorStreak = 0;
+            smartHitStreak = 0;
             notify("keepalive resumed", "info");
             break;
+          case "mode": {
+            const next = value === "smart" || value === "default" ? value : null;
+            if (next === null) {
+              notify("usage: /keepalive mode=smart (adaptive) or mode=default (fixed)", "error");
+              break;
+            }
+            config.mode = next;
+            smartHitStreak = 0;
+            smartPaused = false; // re-selecting the mode is the documented way out of a smart miss-pause
+            if (next === "smart") {
+              // smart manages the cadence itself; snap back to its floor.
+              if (config.intervalMs < SMART_BASE_MS) config.intervalMs = SMART_BASE_MS;
+              notify(
+                `mode=smart — probing resumes at ${formatDuration(config.intervalMs)}; +30s per ${SMART_CONFIRM_HITS} hits (context ≤ ${SMART_MAX_CONTEXT_TOKENS / 1000}k), one miss parks probing`,
+                "info",
+              );
+            } else {
+              notify("mode=default — fixed cadence via /keepalive interval=<duration>", "info");
+            }
+            persistConfig();
+            updateUi();
+            break;
+          }
           case "interval": {
+            if (config.mode === "smart") {
+              notify("smart mode manages the cadence itself — use /keepalive mode=default to set it manually", "warning");
+              break;
+            }
             const ms = value !== undefined ? parseDurationMs(value) : null;
             if (ms === null || ms < MIN_INTERVAL_MS) {
               notify(`/keepalive interval=${value ?? "?"} rejected — minimum 30s, e.g. interval=4m`, "error");
@@ -791,12 +953,23 @@ export default function (pi: ExtensionAPI) {
       cost: (model.cost ?? undefined) as Partial<CostPerM> | undefined,
     };
     // A fresh real request means fresh credentials and a warm prefix cache;
-    // automatically recover from any sticky pause.
+    // automatically recover from any sticky pause. Exception: a smart-mode
+    // miss intentionally parks probing until the user re-selects smart mode.
     if (pausedReason !== null || missStreak > 0 || errorStreak > 0) {
-      pausedReason = null;
+      if (smartPaused) {
+        if (pausedReason !== null) {
+          debug("fresh real request observed — smart-mode miss pause kept; /keepalive mode=smart to resume");
+          missStreak = 0;
+          errorStreak = 0;
+          updateUi();
+          return;
+        }
+      } else {
+        pausedReason = null;
+        debug("fresh real request observed — keepalive unpaused");
+      }
       missStreak = 0;
       errorStreak = 0;
-      debug("fresh real request observed — keepalive unpaused");
     }
     updateUi();
   });