pi-provider-kimi-code 0.3.1 → 0.3.2

package/README.md

@@ -2,27 +2,41 @@
 [![npm](https://img.shields.io/npm/v/pi-provider-kimi-code)](https://www.npmjs.com/package/pi-provider-kimi-code)
 [![license](https://img.shields.io/npm/l/pi-provider-kimi-code)](./LICENSE)
 
-**Reuse your [Kimi Code Plan](https://www.kimi.com/code/docs/en/) inside [pi-coding-agent](https://pi.dev/)** — no separate API credits, no second billing dashboard. Every request draws from your Kimi Code membership quota (the 5-hour token bucket) instead of billing per-token on the Moonshot Open Platform.
+**Use Kimi Code in Pi without losing the Kimi-specific bits.**
 
-It's **"Claude Code for Kimi"** — log in with your Kimi account, with `KIMI_API_KEY` still supported as a fallback for CI. You get `kimi-for-coding` (the Kimi-k2.6 latest alias, backed by the same Kimi Code Plan that covers K2.6 and K2.5) with a 262K-token context window, automatic prompt caching, automatic large-image and video upload, and compatibility with both Anthropic-style and OpenAI-style clients.
+Pi gives you the harness and extension ecosystem. Kimi CLI gives you the official Kimi Code path. This package sits between them: Kimi Code as a Pi provider, plus the details the basic provider keeps simple — file uploads, cache behavior, session reuse, and a base for Kimi-native tools.
+
+## Why this exists
+
+Pi already has a built-in `kimi-coding` provider (see [`pi.dev/docs/.../providers`](https://pi.dev/docs/latest/providers)). It is good basic support: point Pi at Kimi Code and start coding.
+
+This extension is for the next layer. If you are building real Pi workflows, the Kimi-specific details start to matter:
+
+- **Files should go through Kimi's Files API.** Large images are uploaded to `/files` and referenced as `ms://` IDs instead of being sent as huge inline base64 payloads.
+- **Cache behavior should be visible.** Kimi caches by content prefix, not by `prompt_cache_key`. This repo measures that behavior and keeps the provider aligned with it.
+- **Existing Kimi sessions should carry over.** If you already use `kimi-cli`, this extension can reuse that login instead of making you manage another API key.
+- **Protocol choice should stay available.** The default is OpenAI-compatible mode, but Anthropic-compatible mode is still there when your Pi setup needs it.
+
+> On prompt caching: the built-in provider works fine. Kimi's Coding endpoint caches by content prefix hash automatically — neither `cache_control` markers nor `prompt_cache_key` actually drive cache hits. See [docs/caching.md](docs/caching.md) for measurements.
 
 ## Who is this for?
 
-- You already pay for a **[Kimi Code Plan](https://www.kimi.com/code/docs/en/)** and want to use it inside `pi-coding-agent` instead of the official `kimi-cli` — see [MoonshotAI/kimi-cli#757](https://github.com/MoonshotAI/kimi-cli/issues/757) for the canonical feature request this extension answers.
-- You want **"Claude Code for Kimi"**: log in with your Kimi account instead of buying separate API credits. (`KIMI_API_KEY` is also supported as a fallback for CI.)
-- You're in the [pi / pi-mono](https://github.com/badlogic/pi-mono) ecosystem and want **Kimi K2.6** (and the K2.5 coverage that comes with the Code Plan) as a pi provider.
+- You use Pi as your coding harness and want Kimi Code inside that workflow.
+- You already use `kimi-cli`, but want Pi's extensions, skills, prompts, themes, and custom UI pieces around the same Kimi Code account.
+- You are building on top of Pi and need the Kimi-specific parts to behave predictably: uploads, cache behavior, model metadata, and protocol choice.
 
-Pay-per-token via `KIMI_API_KEY` also works if you just want to try Kimi in CI or without a subscription.
+Pay-per-token via `KIMI_API_KEY` still works if you just want to try Kimi in CI or without a subscription.
 
-## Features
+## What this package adds
 
-- **Browser login with your Kimi account** — reuse your Kimi Code Membership without buying separate API credits. Credentials are stored locally and refreshed automatically. `KIMI_API_KEY` is also accepted for pay-per-token or CI use.
-- **262K-token context window** on all registered models.
-- **Automatic prompt caching** — binds Kimi's prompt cache to your pi session so repeated calls hit the cache cheaply (observed TTL ~5-10 minutes). Honors pi's `PI_CACHE_RETENTION=none` if you want to disable caching entirely.
-- **Automatic large-image and video upload** — images over 1 MB and all videos are uploaded to Kimi ahead of time, so you don't hit inline payload limits.
-- **Works with both Anthropic- and OpenAI-compatible modes** — use whichever one your pi setup expects.
-- **Stream cleaning** — Kimi occasionally leaks placeholder blocks into the stream during thinking phases; this extension catches and hides them so your pi UI stays clean.
-- **Zero dependencies, zero build step** — the extension loads directly as TypeScript, nothing to compile.
+- **Kimi account login in Pi** — sign in with your Kimi Code account. `KIMI_API_KEY` still works for CI or pay-per-token use.
+- **`kimi-cli` session reuse** — if you already signed in with the official CLI, this extension can read `~/.kimi/credentials/kimi-code.json` and skip another browser login.
+- **Kimi Files API upload** — large images are uploaded to `/v1/files` and sent as `ms://` references instead of huge inline base64 payloads.
+- **Measured cache behavior** — Kimi's Coding endpoint caches by content prefix hash with TTL ≥ 5 minutes. This repo documents what changes the cache and what does not.
+- **Live model metadata** — name, context window, reasoning support, and image-input support refresh from Kimi's `/v1/models` endpoint at login / refresh time.
+- **Protocol choice** — OpenAI-compatible mode is the default. Anthropic-compatible mode is still available with `KIMI_CODE_PROTOCOL=anthropic`.
+- **Stream cleanup** — Kimi occasionally emits placeholder text during thinking-only responses; this extension hides those blocks before they reach the Pi UI.
+- **No build step** — Pi loads the TypeScript extension directly.
 
 ## Install
 
@@ -50,11 +64,11 @@ curl -L https://github.com/Leechael/pi-provider-kimi-code/releases/latest/downlo
 pi install /tmp/pi-provider-kimi-code
 ```
 
-## Authentication
+## Sign in
 
-### Browser login (recommended)
+### Browser login
 
-Inside `pi`, run:
+Inside Pi, run:
 
 ```
 /login kimi-coding
@@ -62,6 +76,10 @@ Inside `pi`, run:
 
 A browser tab opens, you sign into your Kimi account, and credentials are stored at `~/.pi/agent/auth.json`. Tokens refresh automatically.
 
+### Already logged in via `kimi-cli`?
+
+If `~/.kimi/credentials/kimi-code.json` exists, `/login kimi-coding` reads that file, refreshes the access token if needed, and finishes without opening a browser. The `kimi-cli` credential file is read-only from this extension's perspective — it is never overwritten. Set `KIMI_SHARE_DIR` to point at a non-default location.
+
 ### API key
 
 For CI or pay-per-token use, set `KIMI_API_KEY`:
@@ -70,64 +88,85 @@ For CI or pay-per-token use, set `KIMI_API_KEY`:
 KIMI_API_KEY=sk-... pi
 ```
 
-## Models
+## Model
+
+This provider publishes one Pi model ID:
+
+```
+kimi-coding/kimi-for-coding
+```
+
+Kimi keeps the Coding model behind aliases, so this provider does not hardcode a long model list. When you log in or refresh your token, it asks Kimi for the current model info and updates what Pi sees. If your account is on a newer rollout or an internal test, Pi can pick up the latest model name and context size without waiting for this package to release.
+
+The fallback values are:
 
-| ID                | Name            | Reasoning | Input              | Context | Max Output |
-| ----------------- | --------------- | --------- | ------------------ | ------- | ---------- |
-| `kimi-for-coding` | Kimi for Coding | yes       | text, image, video | 262 144 | 32 000     |
+- Context window: `262144` tokens
+- Max output: `32000` tokens
+- Input: text and image
+- Reasoning: enabled
 
-`kimi-for-coding` is the latest alias on the Kimi Code Plan — today it points at Kimi-k2.6. The Plan itself still covers K2.5; the upstream routes older model IDs to the current alias, but this provider only publishes the canonical `kimi-for-coding` entry.
+Kimi K2.6 supports Pi's reasoning levels. This provider maps them to Kimi's current reasoning efforts:
 
-Select it inside `pi`:
+- `off` / `none` — reasoning disabled
+- `minimal` / `low` — low effort
+- `medium` — medium effort
+- `high` / `xhigh` — high effort
+
+If Kimi reports a larger context window, the provider uses that value. You can also override the advertised context or model name with `KIMI_MODEL_MAX_CONTEXT_SIZE` / `KIMI_MODEL_NAME`; see [docs/ENV.md](docs/ENV.md).
+
+Select it inside Pi:
 
 ```
 /model kimi-coding/kimi-for-coding
 ```
 
-## Environment variables
+## Common knobs
 
-| Variable                           | Description                                            |
-| ---------------------------------- | ------------------------------------------------------ |
-| `KIMI_API_KEY`                     | Static API key (alternative to browser login)          |
-| `KIMI_CODE_BASE_URL`               | Override the API base URL                              |
-| `KIMI_CODE_OAUTH_HOST`             | Override the OAuth host                                |
-| `KIMI_CODE_PROTOCOL`               | `anthropic` (default) or `openai`                      |
-| `KIMI_CODE_UPLOAD_THRESHOLD_BYTES` | Image auto-upload threshold, default `1048576` (1 MB)  |
-| `KIMI_CODE_DEBUG`                  | Set to `1` to print provider-side debug logs           |
+Most users do not need environment variables. Two are worth knowing:
 
-Full list with defaults and the test-script variables: [docs/ENV.md](docs/ENV.md).
+- `KIMI_API_KEY` — static API key for CI or pay-per-token use.
+- `KIMI_CODE_PROTOCOL` — `openai` by default; set to `anthropic` if your Pi setup needs Anthropic-compatible requests.
 
-## FAQ
+The full list, including base URL overrides, `kimi-cli` path overrides, upload tuning, debug logs, and model metadata overrides, lives in [docs/ENV.md](docs/ENV.md).
 
-### How is this different from the official `kimi-cli`?
+## Notes
 
-`kimi-cli` is Moonshot's own terminal agent. It's a full CLI — it replaces pi, you can't use it as a pi provider. This extension is the bridge: it lets you keep pi as your harness and point it at your Kimi Code Membership for inference, reusing the same login flow `kimi-cli` v1.3+ ships.
+### Kimi CLI vs Pi
 
-### Do I need a paid Kimi subscription?
+`kimi-cli` is Moonshot's official terminal agent. Pi is the harness you adapt to your own workflow: extensions, skills, prompts, themes, custom commands, status bars, and UI pieces. This package lets you keep Kimi Code as the model path while staying inside Pi.
 
-For browser login, yes — whatever your Moonshot account is entitled to is what the provider can access. Without a plan you'll hit rate limits quickly. For pay-per-token usage, set `KIMI_API_KEY` instead.
+### Cache behavior
 
-### Where does my data go?
+Kimi's cache is content-based. It fires automatically when your prompt prefix matches an earlier request. `prompt_cache_key` and Anthropic `cache_control` markers do not control cache hits on the Coding endpoint.
 
-Requests go only to `api.kimi.com` (Moonshot's servers). Login credentials are stored locally at `~/.pi/agent/auth.json`, readable only by your user. Nothing is uploaded to any third party.
+See [docs/caching.md](docs/caching.md) for the measured behavior: TTL, cross-protocol cache reuse, 256-token prefix alignment, and the cases that invalidate cache.
 
-### Is this affiliated with Moonshot AI?
+### Protocol modes
 
-No. This is an independent extension. The login flow is derived from the public implementation in the open-source [`kimi-cli`](https://github.com/MoonshotAI/kimi-cli) repository.
+Kimi's coding endpoint speaks both Anthropic and OpenAI dialects. This extension defaults to OpenAI-compatible mode.
+
+`KIMI_CODE_PROTOCOL` supports:
+
+- `openai` — default, uses `/coding/v1/chat/completions`
+- `anthropic` — uses `/coding/v1/messages`
 
-### Which pi version does this work with?
+Use Anthropic mode if your Pi setup depends on Anthropic-style request or tool semantics.
 
-Any recent [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent).
+### Why OpenAI-compatible mode is the default
 
-### Why are there two protocol modes?
+The Anthropic-compatible protocol has an awkward tool-result shape: tool output is wrapped inside a `role: "user"` message. That is valid Anthropic format, but Kimi can sometimes read it like a real user message and continue from the wrong premise in multi-turn tool loops.
 
-Kimi's coding endpoint speaks both Anthropic and OpenAI dialects. Anthropic mode has better visibility into cache hits, so it's the default. Switch via `KIMI_CODE_PROTOCOL=openai` if something in your pi setup prefers the OpenAI path.
+The OpenAI-compatible protocol uses a dedicated `role: "tool"` message, so the boundary is clearer. That is why this extension now defaults to `openai`. The Anthropic path stays available for setups that need it. See [issue #5](https://github.com/Leechael/pi-provider-kimi-code/issues/5) for details.
+
+### Is this affiliated with Moonshot AI?
+
+No. This is an independent extension. The login flow is derived from the public implementation in the open-source [`kimi-cli`](https://github.com/MoonshotAI/kimi-cli) repository.
 
 ## Troubleshooting
 
 ### `pi` reports `fetch failed` even though `curl` works
 
-pi runs on Node's `fetch` / undici stack, which handles `http_proxy` / `https_proxy` / `all_proxy` differently from `curl`. Verify those variables in the pi process's environment. The bundled smoke-test script `scripts/test_e2e.sh` prints the effective proxy-related environment for easier debugging.
+Pi runs on Node's `fetch` / undici stack, which handles `http_proxy` / `https_proxy` / `all_proxy` differently from `curl`. Verify those variables in the Pi process's environment. The bundled smoke-test script `scripts/test_e2e.sh` prints the effective proxy-related environment for easier debugging.
 
 ### `/login kimi-coding` prints a device code but the browser never opens
 
@@ -139,11 +178,19 @@ Your Moonshot account needs an active Kimi Code subscription for the provider to
 
 ### Large images fail with a payload error
 
-This extension uploads images over `KIMI_CODE_UPLOAD_THRESHOLD_BYTES` (default 1 MB) to Kimi's Files API and references them as `ms://`. Videos always upload. Set `KIMI_CODE_DEBUG=1` to see upload decisions in the provider logs.
+This extension uploads images over `KIMI_CODE_UPLOAD_THRESHOLD_BYTES` (default 1 MB) to Kimi's Files API and references them as `ms://`. Set `KIMI_CODE_DEBUG=1` to see upload decisions in the provider logs.
 
 ### Prompt cache never seems to hit
 
-The cache is keyed off your pi session, which changes between sessions. Long-lived sessions get cache hits within a few minutes; cold sessions won't. Also check `PI_CACHE_RETENTION` — if it's set to `none`, this extension intentionally skips cache-key injection. For deterministic measurement, run the cache-TTL probe with a fixed key — see [docs/TESTING.md](docs/TESTING.md).
+Kimi's cache is **content-based**: it fires automatically when your prompt prefix matches an earlier request, independent of any explicit cache key. If `cache_read_input_tokens` (Anthropic) or `cached_tokens` (OpenAI) stays at `0` across calls, something in the prompt is varying between turns. The usual suspects:
+
+- On the Anthropic-compat endpoint, the `system` prompt or the `tools` array changed (e.g. an extension changed the tool set mid-session). Either fully invalidates the cache — see [docs/caching.md](docs/caching.md), Finding 11. OpenAI-compat endpoint not yet measured for this scenario.
+- An `image_url` reference (`ms://<file_id>`) changed between turns. Same rule — see Finding 17.
+- You're comparing across two cold `pi` invocations, not within a single session. Cache benefits accrue **within** a session; Pi's system/tools assembly drifts between sessions. See Finding 18.
+- A timestamp, request ID, or randomized header is being interpolated into the prompt.
+- The first ~256 tokens of the prompt differ between turns.
+
+`PI_CACHE_RETENTION=none` skips `prompt_cache_key` injection but **does not** disable Kimi's caching (the cache is unconditional). For deterministic measurement, run `scripts/test_e2e.sh` with `KIMI_E2E_ONLY_CACHE=1`. See [docs/caching.md](docs/caching.md) for full mechanics.
 
 ### OpenAI-compatible tools complain about a `developer` role
 
@@ -151,15 +198,16 @@ In OpenAI mode this extension maps the `developer` role to `system` (Kimi's Codi
 
 ## References
 
-- Upstream harness: [badlogic/pi-mono](https://github.com/badlogic/pi-mono) · [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
+- Pi: [earendil-works/pi](https://github.com/earendil-works/pi)
 - Upstream login implementation and feature request: [MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli) · [kimi-cli#757](https://github.com/MoonshotAI/kimi-cli/issues/757)
 - Environment variables: [docs/ENV.md](docs/ENV.md)
 - Testing guide: [docs/TESTING.md](docs/TESTING.md)
+- Cache behavior: [docs/caching.md](docs/caching.md)
 - Architecture notes: [docs/architecture.md](docs/architecture.md)
 
 ## Credits
 
-Based on the login implementation from [`kimi-cli`](https://github.com/MoonshotAI/kimi-cli) by Moonshot AI. Built as an extension for [`pi-coding-agent`](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) by [@badlogic](https://github.com/badlogic).
+Based on the login implementation from [`kimi-cli`](https://github.com/MoonshotAI/kimi-cli) by Moonshot AI. Built as a Pi extension by [@badlogic](https://github.com/badlogic).
 
 ## License