pi-kimi-keepalive 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oliverlyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# pi-kimi-keepalive
+
+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.
+
+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.
+
+[中文文档](README.zh-CN.md)
+
+## Requirements
+
+- Node ≥ 20, pi ≥ 0.84 (exposes the `before_provider_headers` / `before_provider_request` hooks)
+- `kimi-coding` provider (OAuth subscription recommended), `kimi-openai-completions` API
+
+## Install
+
+```bash
+git clone https://github.com/realoliversama/pi-kimi-keepalive
+pi install /path/to/pi-kimi-keepalive
+```
+
+For a single session without installing:
+
+```bash
+pi -e /path/to/pi-kimi-keepalive/src/index.ts
+```
+
+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.
+
+| 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. |
+| 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. |
+
+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.
+
+## Commands
+
+```
+/keepalive                  status
+/keepalive setup            rerun the setup wizard
+/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 maxidle=30m      idle cutoff (0 = disabled)
+/keepalive miss=1           pause after N consecutive cache misses
+/keepalive errors=3         pause after N consecutive probe failures
+/keepalive cap=1.0          session probe-spend ceiling in USD (0 = none)
+/keepalive token=512        minimum prompt size for miss classification
+/keepalive maxoutput=16     probe max_tokens clamp
+/keepalive reset            zero the session stats
+```
+
+All settings persist to `~/.pi/cache-keepalive/state.json`. Statistics are per-session.
+
+## How it works
+
+1. **Capture.** The `before_provider_request` hook snapshots a `structuredClone` of the payload of each real `kimi-coding` request. In-memory only; nothing is written to disk.
+2. **Replay.** While the agent is idle and enabled, the captured request is POSTed to `{baseUrl}/chat/completions` (kimi-openai-completions) with only terminal parameters changed:
+
+   | Change | Reason |
+   | --- | --- |
+   | remove `stream` / `stream_options` | returns usage as a single JSON body |
+   | remove `thinking` | avoids thinking-budget constraints against the output clamp below |
+   | remove `store` | probe output is unused; no need to persist it |
+   | `max_completion_tokens: 16` | bounds the probe's output cost |
+   | HTTP 400 retry | drops `prompt_cache_retention` (a terminal parameter, not part of the prefix) |
+
+   `messages`, `tools`, and Kimi's `prompt_cache_key` / `prompt_cache_retention` are kept byte-identical — the inputs to the provider's prefix-cache key — so the replay matches the existing cache entry and restarts its TTL at cache-read pricing. Verified live: a probe against a 48k-token session reports `use.prompt_tokens_details.cached_tokens × 48,116 / 48,116`.
+3. **Authentication.** pi injects the OAuth bearer token after the `before_provider_headers` hook fires, so captured headers usually lack auth. Probes read the current `kimi-coding.access` token from pi's auth store (`~/.pi/agent/auth.json`) at probe time, staying in sync with pi's token refreshes.
+4. **Classification.** Response usage (`prompt_tokens_details.cached_tokens`, falling back to Anthropic-style fields) classifies each probe as a hit or a miss. The response is otherwise discarded.
+
+Captured headers are merged in minus hop-by-hop and length headers; the bearer token always comes from the auth store.
+
+## Guardrails
+
+- Probes are skipped while a turn is running; the timer rearms on `agent_settled`.
+- `maxIdle` cutoff stops probing during extended idle periods.
+- `miss` / `errors` streaks and HTTP 401/403 pause probing until the next real turn recaptures credentials and resets state.
+- Session probe spend is estimated from model pricing and pauses at the cap.
+- Timers are `unref()`'d and never keep the process alive.
+- All pauses are cleared automatically by the next real provider request.
+
+## Cost accounting
+
+Kimi K3 list prices (USD per 1M tokens): input 3, output 15, cache read 0.3, cache write 0.
+
+- A probe that hits the prefix cache costs approximately the cache-read price of the full context: ~$0.015 at 50k tokens, ~$0.03 at 100k, ~$0.06 at 200k.
+- A probe that misses re-reads the prefix at full input price. Consecutive misses pause the loop (threshold: `miss`).
+- The `saved` counter estimates `cacheReadTokens × (input − cacheRead) / 1M` — what an equivalent cold resume would have cost at full input price.
+
+On a Kimi subscription, billing is quota-based and USD figures are indicative only.
+
+## 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.
+- 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.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test          # 26 tests; stubbed fetch, temp $HOME, no network
+```
+
+Tests run on Node's native TypeScript stripping (Node ≥ 22.18 / 24).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,118 @@
+# pi-kimi-keepalive
+
+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）计费。
+
+重放请求直接发送到 provider 端点，不经过 Pi 会话管道：不产生合成消息、不产生模型回合、不改动对话历史，仅在界面上展示聚合统计。
+
+## 环境要求
+
+- Node ≥ 20，pi ≥ 0.84（提供 `before_provider_headers` / `before_provider_request` 钩子）
+- `kimi-coding` provider（建议 OAuth 订阅），`kimi-openai-completions` API
+
+## 安装
+
+```bash
+git clone https://github.com/realoliversama/pi-kimi-keepalive
+pi install /path/to/pi-kimi-keepalive
+```
+
+单次会话试运行（不安装）：
+
+```bash
+pi -e /path/to/pi-kimi-keepalive/src/index.ts
+```
+
+npm 发布后可使用 `pi install npm:pi-kimi-keepalive`。
+
+## 初始化
+
+首次启动（`~/.pi/cache-keepalive/state.json` 不存在）且有交互 UI 时，扩展运行初始化向导配置四项护栏。提示符留空或按 Esc 保留默认值；之后可用 `/keepalive setup` 重新运行；headless 会话自动跳过并保留默认值。
+
+| 步骤 | 设置项 | 命令 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| 1 | Max idle cutoff | `maxidle` | `30m` | 空闲超过该时长后停止探测；`0` 表示不设限 |
+| 2 | Miss pause threshold | `miss` | `2` | 连续 N 次探测未命中前缀缓存后暂停；命中会重置计数 |
+| 3 | Error circuit breaker | `errors` | `3` | 连续 N 次探测失败（网络错误、HTTP 5xx）后暂停；HTTP 401/403 不受此值约束，直接暂停 |
+| 4 | Session spend cap | `cap` | `$1.00` | 会话探测花费（估算 USD）上限；`0` 表示不设上限 |
+
+向导结束时询问是否立即启用 keepalive。探测在下一次真实请求（完成捕获）之后开始。全部配置持久化到 `~/.pi/cache-keepalive/state.json`。
+
+## 命令
+
+```
+/keepalive                  查看状态
+/keepalive setup            重新运行初始化向导
+/keepalive on|off           启用 / 停用（持久化）
+/keepalive now              手动探测一次（绕过暂停）
+/keepalive resume           清除 sticky 暂停
+/keepalive interval=4m45s   探测间隔（≥ 30s；应 ≤ 5m 以保持缓存命中）
+/keepalive maxidle=30m      空闲上限（0 = 不设限）
+/keepalive miss=1           连续 N 次缓存 miss 后暂停
+/keepalive errors=3         连续 N 次探测失败后熔断
+/keepalive cap=1.0          会话探测花费上限（USD，0 = 无上限）
+/keepalive token=512        判定 miss 的最小 prompt token 数
+/keepalive maxoutput=16     探测 max_tokens
+/keepalive reset            清零会话统计
+```
+
+统计（hits / misses / spend）为会话级；配置项持久化。`PI_KEEPALIVE_DEBUG=1` 输出调试日志到 stderr。
+
+## 工作机制
+
+1. **捕获**。`before_provider_request` 钩子快照每条真实 `kimi-coding` 请求的 payload（`structuredClone`）。只存内存，不落盘。
+2. **重放**。捕获的请求 POST 至 `{baseUrl}/chat/completions`（kimi-openai-completions 路由），仅修改终端参数：
+
+   | 修改 | 原因 |
+   | --- | --- |
+   | 移除 `stream` / `stream_options` | 非流式响应中 usage 可直接解析 |
+   | 移除 `thinking` / `store` | 与输出收紧参数兼容性未知；非前缀组成部分 |
+   | `max_completion_tokens: 16` | 限制探测输出成本 |
+   | HTTP 400 时重试 | 去掉 `prompt_cache_retention`（终端参数，非缓存键） |
+
+   `messages` / `tools` / `prompt_cache_key` / `prompt_cache_retention` 保持 byte-identical——这些是 provider 前缀缓存键的输入，重放因此命中既有缓存条目并重置 TTL，按 cache-read 计费。实测对 48k 上下文的探测实现 48,116/48,116 全量命中。
+3. **认证**。pi 在 `before_provider_headers` 钩子之后才注入 OAuth 凭据，捕获的 headers 通常不含认证；探测时从 pi 的凭据存储（`~/.pi/agent/auth.json` 的 `kimi-coding.access`）读取当前 token，与 pi 的自动刷新保持同步。
+4. **判定**。解析响应 usage（`prompt_tokens_details.cached_tokens`，回退 Anthropic 风格字段）将探测分类为 hit 或 miss；响应其余部分丢弃。
+
+捕获的业务 headers 原样合并（去除 hop-by-hop 与长度头）。
+
+## 护栏
+
+- 回合运行中跳过探测；`agent_settled` 重新 arm 定时器。
+- `maxIdle` 在长空闲期停止探测。
+- `miss` / `errors` 连续次数达到阈值，或 HTTP 401/403，暂停探测；下一次真实请求重新捕获凭据并自动解除暂停。
+- 会话探测花费按模型定价估算，达到上限即暂停。
+- 定时器 `unref()`，不阻止进程退出。
+
+## 成本
+
+Kimi K3 官方单价（$/1M tokens）：input 3，output 15，cache read 0.3，cache write 0。
+
+- 命中的探测约等于整个上下文的 cache-read 费用：50k tokens ≈ $0.015，100k ≈ $0.03，200k ≈ $0.06。
+- 未命中的探测按全价 input 重读同一前缀；连续 miss 达到阈值即暂停。
+- `saved` 统计 = `cacheReadTokens × (input − cacheRead) / 1M`，即等效冷恢复在全价下的开销的估算。
+
+Kimi 订阅按 quota 计费，USD 数值仅供参考。
+
+## 限制
+
+- ~5 分钟 TTL 与上述定价为观测行为，非 API 契约；`saved` 仅为估算。
+- 仅支持 `kimi-coding`（`kimi-openai-completions` API，含 `anthropic-messages` 回退）；其他 provider 缓存键语义不同，不在范围内。
+- 捕获内容仅存内存；探测仅发往 `https://` 端点。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test          # 26 项测试；stub fetch、临时 $HOME、无网络
+```
+
+测试依赖 Node 原生 TypeScript 剥离（Node ≥ 22.18 / 24）。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pi-kimi-keepalive",
+  "version": "0.1.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",
+  "author": "realOliverSama <159797106+realOliverSama@users.noreply.github.com>",
+  "homepage": "https://github.com/realoliversama/pi-kimi-keepalive#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/realoliversama/pi-kimi-keepalive.git"
+  },
+  "bugs": {
+    "url": "https://github.com/realoliversama/pi-kimi-keepalive/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "kimi",
+    "moonshot",
+    "prompt-cache",
+    "cache",
+    "keepalive"
+  ],
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/keepalive.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@types/node": "^24",
+    "typescript": "^5"
+  }
+}