pi-kimi-keepalive 0.1.0 → 0.2.1

package/README.md

@@ -30,18 +30,33 @@ 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 — deliberately past the ~5-minute nominal cache TTL. An 8-minute probe rarely 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 observed TTL (`/keepalive interval=4m45s`…`7m`): every probe is then billed at cache-read rates (~1/10 of full price) and the loop keeps running until `maxidle` cuts it off.
+
+**`smart` (`/keepalive mode=smart`)** — self-tunes the cadence toward the real cache TTL instead of guessing it:
+
+1. Starts at **8 minutes**.
+2. After **5 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: 5 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 +66,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 5-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; ≤ 5m to stay inside the cache TTL)
 /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

package/README.zh-CN.md

@@ -30,17 +30,34 @@ 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 分钟**——刻意超过 ~5 分钟的名义缓存 TTL。8 分钟的探测通常无法命中：以全价输入运行一次、确认缓存已过期，默认 `miss=1` 随即停止探测，因此最坏情况是每个空闲期仅一次全价冷读。若想保持会话常热，可把间隔设在实测 TTL 之内（`/keepalive interval=4m45s`…`7m`）：每次探测按缓存读价计费（约为全价的 1/10），循环持续到 `maxidle` 截断。
+
+**`smart`（`/keepalive mode=smart`）**——不猜测 TTL，而是自适应逼近真实值：
+
+1. 从 **8 分钟**起跳。
+2. **连续 5 次命中**后该间隔即被确认，档位 **+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）仍然生效。
+
+每个学习周期的花费极小：5 次缓存读价探测确认一档，一次全价探测结束本轮——停靠后的档位让之后的每个会话都直接运行在实测可行的最高值上。
+
 ## 命令
 
 ```
@@ -49,7 +66,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；每 5 连中 +30s；一次 miss 即停靠，mode=smart 恢复探测）
+/keepalive mode=default     固定间隔（即 interval= 的值）
+/keepalive interval=4m45s   default 模式下的探测间隔（≥ 30s；应 ≤ 5m 以保持缓存命中）
 /keepalive maxidle=30m      空闲上限（0 = 不设限）
 /keepalive miss=1           连续 N 次缓存 miss 后暂停
 /keepalive errors=3         连续 N 次探测失败后熔断

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-kimi-keepalive",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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,6 +68,8 @@ 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;
 }
@@ -79,16 +81,23 @@ const DEFAULT_CONFIG: Readonly<PersistedConfig> = Object.freeze({
   // 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,
+  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 5-hit confirmation
+const SMART_CONFIRM_HITS = 5;
+const SMART_MAX_CONTEXT_TOKENS = 200_000; // context cap: grow only below this
+
 const MIN_INTERVAL_MS = 30_000;
 const PROBE_TIMEOUT_MS = 30_000;
 
@@ -99,7 +108,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 5-hit confirmation; a miss pauses probing, mode=smart resumes)",
+  "  /keepalive mode=default   fixed cadence (the interval= value)",
+  "  /keepalive interval=4m45s probe cadence (default mode; >= 30s; <= 5m stays inside the cache TTL)",
   "  /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 +155,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 +193,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 +234,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 +242,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 +263,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 +280,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 +296,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 +315,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 5 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 +352,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 +546,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 +556,20 @@ 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 {
+        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 +584,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; // 5-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 +707,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 +761,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 +931,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();
   });