pi-provider-kimi-code 0.3.1 → 0.4.0

package/README.md

@@ -1,28 +1,33 @@
 # Pi extension for Kimi Code
+
 [![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, with the Kimi parts handled.**
 
-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 already has a basic `kimi-coding` provider. This extension is for the parts that start to matter once Kimi Code becomes part of your real Pi workflow: account login reuse, file uploads, measured cache behavior, live model metadata, and optional Moonshot search/fetch tools.
 
-## Who is this for?
+## Why this exists
 
-- 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.
+Pi is a small harness you adapt to your own workflow. Kimi CLI is Moonshot's official Kimi Code path. This package sits between them: Kimi Code as a Pi provider, plus the Kimi-specific details that the basic provider keeps simple.
 
-Pay-per-token via `KIMI_API_KEY` also works if you just want to try Kimi in CI or without a subscription.
+- **Use your Kimi account.** Log in with `/login kimi-coding`, or reuse an existing `kimi-cli` session.
+- **Send files the Kimi way.** Large inline images go through Kimi's Files API and become `ms://` references instead of huge base64 payloads.
+- **Know what the cache is doing.** Kimi caches by content prefix. This repo measures that behavior instead of pretending `prompt_cache_key` controls it.
+- **Use the safer protocol by default.** OpenAI-compatible mode is the default because tool results are less ambiguous there. Anthropic-compatible mode is still available.
+- **Turn on Kimi-native tools when you want them.** `moonshot_search` and `moonshot_fetch` are opt-in, configurable per user or per project.
 
-## 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, plus `KIMI_API_KEY` for CI or pay-per-token use.
+- `kimi-cli` credential reuse from `~/.kimi/credentials/kimi-code.json`.
+- Kimi Files API uploads for large inline images.
+- Live model metadata from Kimi at login / refresh time.
+- OpenAI-compatible mode by default, Anthropic-compatible mode on request.
+- Kimi K2.6 reasoning level mapping for Pi's reasoning controls.
+- Stream cleanup for Kimi's thinking-only placeholder text.
+- Optional `moonshot_search` and `moonshot_fetch` tools via `/kimi-settings`.
+- No build step; Pi loads the TypeScript extension directly.
 
 ## Install
 
@@ -43,107 +48,188 @@ pi -e /path/to/pi-provider-kimi-code
 If you prefer not to use npm, download the tarball from the [latest release](https://github.com/Leechael/pi-provider-kimi-code/releases/latest), extract it, and install from the local path:
 
 ```bash
-# Download and extract
 curl -L https://github.com/Leechael/pi-provider-kimi-code/releases/latest/download/pi-provider-kimi-code.tar.gz | tar -xz -C /tmp
-
-# Install from the extracted directory
 pi install /tmp/pi-provider-kimi-code
 ```
 
-## Authentication
-
-### Browser login (recommended)
+## Sign in
 
-Inside `pi`, run:
+Inside Pi, run:
 
-```
+```text
 /login kimi-coding
 ```
 
-A browser tab opens, you sign into your Kimi account, and credentials are stored at `~/.pi/agent/auth.json`. Tokens refresh automatically.
+A browser tab opens, you sign into your Kimi account, and Pi stores the credential at `~/.pi/agent/auth.json`. Tokens refresh automatically.
+
+If you already use `kimi-cli`, this extension can reuse its credential file:
+
+```text
+~/.kimi/credentials/kimi-code.json
+```
 
-### API key
+The file is read-only from this extension's side. Set `KIMI_SHARE_DIR` if your `kimi-cli` share directory lives somewhere else.
 
-For CI or pay-per-token use, set `KIMI_API_KEY`:
+For CI or pay-per-token use, set `KIMI_API_KEY` instead:
 
 ```bash
 KIMI_API_KEY=sk-... pi
 ```
 
-## Models
+## Model
 
-| ID                | Name            | Reasoning | Input              | Context | Max Output |
-| ----------------- | --------------- | --------- | ------------------ | ------- | ---------- |
-| `kimi-for-coding` | Kimi for Coding | yes       | text, image, video | 262 144 | 32 000     |
+This provider publishes one Pi model ID:
 
-`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.
+```text
+kimi-coding/kimi-for-coding
+```
 
-Select it inside `pi`:
+Select it inside Pi:
 
-```
+```text
 /model kimi-coding/kimi-for-coding
 ```
 
-## Environment variables
+Kimi keeps Coding models behind aliases. Rather than hardcoding a stale model list, this extension asks Kimi for the current model info when you log in or refresh. If your account is on a newer rollout or internal test, Pi can pick up the latest model name and context size without waiting for a package release.
 
-| 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           |
+Fallback values:
 
-Full list with defaults and the test-script variables: [docs/ENV.md](docs/ENV.md).
+- Context window: `262144` tokens
+- Max output: `32000` tokens
+- Input: text and image
+- Reasoning: enabled
 
-## FAQ
+Kimi K2.6 supports Pi's reasoning levels. This provider maps them to Kimi's current reasoning efforts:
 
-### How is this different from the official `kimi-cli`?
+- `off` / `none` — reasoning disabled
+- `minimal` / `low` — low effort
+- `medium` — medium effort
+- `high` / `xhigh` — high effort
 
-`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.
+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).
 
-### Do I need a paid Kimi subscription?
+## Optional Moonshot tools
 
-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.
+Kimi Coding has server-side search and fetch tools. This extension can expose them to Pi as:
 
-### Where does my data go?
+- `moonshot_search`
+- `moonshot_fetch`
 
-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.
+They are off by default. Turn them on when you want Kimi's own search/fetch path in the agent loop.
 
-### Is this affiliated with Moonshot AI?
+Inside Pi, run:
 
-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.
+```text
+/kimi-settings
+```
+
+That command shows your current Kimi usage summary and lets you edit the home or project config. Changes apply to the active session tool set.
+
+Config files are JSON:
+
+- Home: `~/.pi/pi-provider-kimi-code.json`
+- Project override: `<cwd>/.pi/pi-provider-kimi-code.json`
+
+Project config overrides home config with a deep merge. Missing files or missing keys mean both tools stay off.
+
+```json
+{
+  "tools": {
+    "moonshot_search": { "enabled": true, "default_collapsed": true },
+    "moonshot_fetch": { "enabled": true, "default_collapsed": true }
+  }
+}
+```
+
+Both tools require `/login kimi-coding` OAuth credentials. `KIMI_API_KEY` is not used for these tools. Your account also needs access to Moonshot's server-side search/fetch services; if not, the upstream service can return subscription or whitelist errors.
+
+`default_collapsed` controls only the TUI preview. The full tool result still goes to the model; set it to `false` if you want previews expanded by default.
+
+If you already use another search or fetch tool, pick one path for a session. Overlapping tools can make the model choose the wrong one.
+
+## Common knobs
+
+Most users do not need environment variables. Two are worth knowing:
+
+- `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.
 
-### Which pi version does this work with?
+Moonshot search/fetch tools are configured through `/kimi-settings` or JSON config files, not env vars.
 
-Any recent [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent).
+The full env 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).
 
-### Why are there two protocol modes?
+## Notes
 
-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.
+### Kimi CLI vs Pi
+
+`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.
+
+### Cache behavior
+
+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.
+
+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.
+
+### Protocol modes
+
+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`
+
+Use Anthropic mode if your Pi setup depends on Anthropic-style request or tool semantics.
+
+### Why OpenAI-compatible mode is the default
+
+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.
+
+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
 
-The login flow always prints a verification URL — opening it is the terminal's job. If your terminal or OS blocks auto-open, copy the URL and paste it into a browser manually.
+The login flow always prints a verification URL. If your terminal or OS blocks auto-open, copy the URL and paste it into a browser manually.
 
 ### "Access denied" or subscription errors after a successful login
 
 Your Moonshot account needs an active Kimi Code subscription for the provider to do anything useful. If the same account works in `kimi-cli`, re-run `/login kimi-coding` to refresh credentials.
 
+### Moonshot tools do not show up
+
+Run `/kimi-settings` and check whether `moonshot_search` / `moonshot_fetch` are enabled in the home or project config. These tools also require `/login kimi-coding`; `KIMI_API_KEY` is not enough.
+
+If you changed the JSON config by hand, reload it through `/kimi-settings` or start a new Pi session.
+
+### Moonshot tools return subscription or whitelist errors
+
+The tools call Moonshot's server-side search/fetch services. Some accounts may not have access even with an active Kimi Code Plan. The error comes from the upstream service.
+
 ### 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 +237,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