pi-provider-kimi-code 0.6.7 → 0.6.9

package/README.md

@@ -3,40 +3,35 @@
 [![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)
 
-**Use Kimi Code in Pi, with the Kimi parts handled.**
+> **Kimi Code harness extension for Pi.** Pi v0.82.0 ships a built-in `kimi-coding` provider that handles the LLM layer — K3, adaptive thinking, and a generated model catalog — plus native OAuth sign-in via `/login`. This extension brings the rest of the Kimi Code surface into Pi: shared login state with the official `kimi-code` CLI, Kimi Files API uploads, and Kimi-native tools such as `moonshot_search`, `moonshot_fetch`, and `kimi_datasource`.
 
-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, tool schema compatibility, live model metadata, measured cache behavior, and API-tested parameter handling.
+Pi's built-in `kimi-coding` provider handles the LLM. This extension covers the rest: shared login state with the official CLI, file uploads through Kimi's Files API, and Kimi-native tools. It also keeps a legacy provider registration so existing model sessions still load. New users should use Pi's built-in model provider.
 
-> **Kimi K3 supported.** The provider combines Kimi's live `/v1/models` catalog with your membership level from `/usages`, exposing only eligible models and advertising the correct K3 context limit. It refreshes this metadata at startup and through `/kimi-settings`; OAuth login and token refresh also update the model catalog.
+> **Live model catalog (legacy).** For backward compatibility, the extension still reads Kimi's live `/v1/models` catalog when it has credentials. New Pi users should rely on the built-in provider's generated catalog instead.
 
 ## Why this exists
 
-Pi is a small harness you adapt to your own workflow. Kimi Code is Moonshot's official coding agent. This package sits between them: Kimi Code as a Pi provider, plus the Kimi-specific details that the basic provider keeps simple.
+Pi is a small harness you adapt to your own workflow. Kimi Code is Moonshot's official coding agent. Pi now ships a built-in `kimi-coding` provider that covers the LLM, including OAuth login. This extension is for the parts of Kimi Code that Pi's built-in provider does not cover: the account session, file uploads, and Kimi's own tools/datasource APIs.
 
-Kimi's API surface goes beyond the LLM itself. It includes file uploads, web search, page fetch, and a growing set of datasource APIs. This extension wires those capabilities into Pi so you can use them alongside the community's existing extensions — MCP servers, custom themes, skills, and any other Pi add-on — without leaving the harness.
+Use the built-in provider if you only want to chat with Kimi models. Install this extension when you also want the full Kimi Code surface inside Pi:
 
-- **Use your Kimi account.** Log in with `/login kimi-coding`, or reuse an existing `kimi-code` session.
+- **Share a session with the official `kimi-code` CLI.** Reuse an existing `kimi-code` login, or sync Pi's OAuth login back to `kimi-code` so both CLIs stay authenticated.
 - **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 Kimi-native tools.** `moonshot_search`, `moonshot_fetch`, and `kimi_datasource` are opt-in tools that call Moonshot's server-side services.
 - **Keep Pi's tools working.** Moonshot's API rejects tool schemas over 15 KB — a limit that Pi's extension ecosystem regularly hits ([#16](https://github.com/Leechael/pi-provider-kimi-code/issues/16), [#21](https://github.com/Leechael/pi-provider-kimi-code/issues/21)). This extension automatically deduplicates schemas with `$ref`/`$defs` before sending, so subagents and other extensions don't break.
-- **Tested against the live API.** Thinking config, parameter constraints, protocol compatibility, and streaming behavior are all verified against Kimi's Coding endpoint — not assumed from docs. When the API rejects something (wrong `temperature`, unsupported `tool_choice`), the provider normalizes the request before you see a 400.
-- **Turn on Kimi-native tools when you want them.** `moonshot_search`, `moonshot_fetch`, and `kimi_datasource` are opt-in, configurable per user or per project.
-- **Embed in your own build.** `KimiCode()` factory lets you ship Kimi Code support inside a custom Pi agent with programmatic config overrides — no file-based extension path needed.
+- **Embed in your own build.** The `KimiCode()` factory lets you ship Kimi Code support inside a custom Pi agent with programmatic config overrides — no file-based extension path needed.
 
 ## What this package adds
 
-- Kimi account login in Pi, plus `KIMI_API_KEY` for CI or pay-per-token use.
-- `kimi-code` credential reuse from `~/.kimi-code/credentials/kimi-code.json`, with read-only support for the legacy `~/.kimi` path.
-- Kimi Files API uploads for large inline images.
-- Live model metadata combined with membership-aware K3 and HighSpeed availability.
-- OpenAI-compatible mode by default, Anthropic-compatible mode on request.
-- K2.7 and K3 reasoning level mapping for Pi's reasoning controls.
-- Tool schema dedup to stay under Moonshot's 15 KB per-tool-schema limit.
-- K2.7 parameter guard: removes rejected `temperature` and `top_p` values and rewrites unsupported `tool_choice` values to `auto`.
-- Stream cleanup for Kimi's thinking-only placeholder text.
-- Optional `moonshot_search`, `moonshot_fetch`, and unified datasource `kimi_datasource` tools via `/kimi-settings`.
-- Programmatic `KimiCode()` factory for embedding in custom Pi builds.
-- No build step; Pi loads the TypeScript extension directly.
+- **Credential reuse with `kimi-code`.** Reads `~/.kimi-code/credentials/kimi-code.json` and syncs refreshed OAuth tokens back to it.
+- **Kimi account login in Pi.** `/login kimi-coding` stores credentials in `~/.pi/agent/auth.json`; tokens refresh automatically.
+- **`KIMI_API_KEY` fallback.** For CI or key-based access.
+- **Kimi Files API uploads.** Uploads large inline images and references them as `ms://` instead of inline base64.
+- **Optional Kimi-native tools.** `moonshot_search`, `moonshot_fetch`, and `kimi_datasource` via `/kimi-settings`.
+- **Tool schema dedup.** Collapses repeated `$ref`/`$defs` structures to stay under Moonshot's 15 KB per-tool limit.
+- **Legacy provider registration.** Keeps existing model sessions loading; new users should use Pi's built-in provider.
+- **Programmatic `KimiCode()` factory.** Embed Kimi Code in a custom Pi build with config overrides.
+- **No build step.** Pi loads the TypeScript extension directly.
 
 ## Install
 
@@ -76,57 +71,32 @@ main(process.argv.slice(2), {
 
 `KimiCode()` with no arguments behaves identically to the file-based extension. Pass a `KimiCodeConfigPatch` to override defaults (protocol, upload threshold, tools, model parameters). See [docs/programmatic-usage.md](docs/programmatic-usage.md) for the full API.
 
-## Sign in
+## Authentication
 
-Inside Pi, run:
-
-```text
-/login kimi-coding
-```
-
-A browser tab opens, you sign into your Kimi account, and Pi stores the credential at `~/.pi/agent/auth.json`. Tokens refresh automatically. The extension also syncs refreshed credentials to the current `kimi-code` credential file:
-
-```text
-~/.kimi-code/credentials/kimi-code.json
-```
+Pi's built-in `kimi-coding` provider already supports OAuth login via `/login`. This extension handles the credential layer around that login:
 
-If you already use `kimi-code`, the extension can reuse that session. Set `KIMI_CODE_HOME` if its home directory lives somewhere else.
-
-The legacy credential path is also supported:
-
-```text
-~/.kimi/credentials/kimi-code.json
-```
-
-Legacy credentials are read-only. Set `KIMI_SHARE_DIR` to override the legacy `~/.kimi` directory.
-
-For CI or pay-per-token use, set `KIMI_API_KEY` instead:
+- **Syncs refreshed tokens back to `kimi-code`.** Pi stores credentials at `~/.pi/agent/auth.json`; this extension keeps the official CLI's credential file (`~/.kimi-code/credentials/kimi-code.json`) up to date so both stay authenticated.
+- **Reuses existing `kimi-code` sessions.** If you already use the official CLI, the extension reads its session directly. Set `KIMI_CODE_HOME` if its home directory lives somewhere else.
+- **Supports the legacy `~/.kimi` path.** Read-only. Set `KIMI_SHARE_DIR` to override it.
+- **`KIMI_API_KEY` fallback.** For CI or key-based access:
 
 ```bash
 KIMI_API_KEY=sk-... pi
 ```
 
-## Models
-
-This provider publishes three Pi model IDs:
-
-| Pi model ID                             | Upstream model           | Access                                                 |
-| --------------------------------------- | ------------------------ | ------------------------------------------------------ |
-| `kimi-coding/kimi-for-coding`           | Kimi K2.7 Code           | All Kimi Code members                                  |
-| `kimi-coding/kimi-for-coding-highspeed` | Kimi K2.7 Code HighSpeed | Allegretto and above                                   |
-| `kimi-coding/k3`                        | Kimi K3                  | Moderato: 256K context; Allegretto and above: up to 1M |
+## Models (legacy provider registration)
 
-Plans below Moderato cannot use K3. The provider reads the current membership level from `/usages` and combines it with `/models`: server catalog availability remains authoritative, while known plan limits can only hide unavailable selections or lower K3's advertised context window. Unknown or unavailable membership data falls back to the server catalog instead of guessing.
+> **New users:** Use Pi's built-in `kimi-coding` provider for model discovery, reasoning controls, and OAuth login. This extension keeps its own model registration only for backward compatibility with existing sessions.
 
-Select a model inside Pi:
+When this extension does register models, the official catalog determines what it publishes. The following IDs are the fallback set when catalog discovery is unavailable:
 
-```text
-/model kimi-coding/kimi-for-coding
-/model kimi-coding/kimi-for-coding-highspeed
-/model kimi-coding/k3
-```
+| Pi model ID                             | Default name             | Availability and context |
+| --------------------------------------- | ------------------------ | ------------------------ |
+| `kimi-coding/kimi-for-coding`           | Kimi K2.7 Code           | Official catalog         |
+| `kimi-coding/kimi-for-coding-highspeed` | Kimi K2.7 Code HighSpeed | Official catalog         |
+| `kimi-coding/k3`                        | Kimi K3                  | Official catalog         |
 
-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 (e.g., Kimi K2.7) or internal test, Pi can pick up the latest model name and context size without waiting for a package release.
+Kimi's official catalog at `https://api.kimi.com/coding/v1/models` is authoritative for model availability and context windows. When discovery is unavailable, the extension uses the fallback models and defaults below.
 
 Fallback values:
 
@@ -135,13 +105,13 @@ Fallback values:
 - Input: text and image
 - Reasoning: enabled
 
-The provider maps Pi's reasoning levels to Kimi's top-level `thinking` parameter. K3 currently advertises only `max`; `max` and `xhigh` map to `max`, `high` and `medium` map to `high`, and `low` and `minimal` map to `low`. It sends `thinking.effort` only when `/models` advertises the mapped value. The mapping refreshes automatically on credential refresh. Opening `/kimi-settings` also re-discovers the latest model and membership metadata.
+The provider maps Pi's reasoning levels to Kimi's top-level `thinking` parameter. It sends `thinking.effort` only when the official catalog advertises the mapped value. The mapping refreshes automatically on credential refresh. Opening `/kimi-settings` also re-discovers the latest model metadata.
 
 Switching models or thinking effort invalidates Kimi's existing context cache. Start a new session when switching to avoid re-prefilling a long conversation and consuming extra quota.
 
 ## Optional tools
 
-Kimi Coding has server-side capabilities that this extension can expose as opt-in tools. All tools are off by default. Enable them individually through `/kimi-settings` or JSON config.
+Kimi Code has server-side capabilities that this extension exposes as opt-in tools. All tools are off by default. Enable them individually through `/kimi-settings` or JSON config.
 
 Inside Pi, run:
 
@@ -213,8 +183,8 @@ If you already use another search or fetch tool, pick one path for a session. Ov
 
 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. Can also be set through `/kimi-settings` or JSON config.
+- `KIMI_API_KEY` — static API key for CI or key-based access.
+- `KIMI_CODE_PROTOCOL` — `openai` by default; set to `anthropic` for Anthropic-compatible requests.
 
 Tools, protocol, and upload threshold are all configurable through `/kimi-settings` or JSON config files.
 
@@ -224,30 +194,15 @@ The full env list, including base URL overrides, `kimi-code` path overrides, upl
 
 ### Kimi Code vs Pi
 
-`kimi-code` 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.
+`kimi-code` is Moonshot's official terminal agent. Pi is the harness you adapt to your own workflow. Pi's built-in `kimi-coding` provider handles the LLM; this extension adds the rest of the Kimi Code surface to Pi.
 
 ### Cache behavior
 
-Kimi's cache is content-based. It fires automatically when your prompt prefix matches an earlier request. `prompt_cache_key`, Anthropic `cache_control` markers, and identifying headers like `X-Msh-Device-Id` are all ignored for cache decisions — cache is keyed purely by prompt content and is shared across machines, agent forks, and device-id rotations on the same Kimi account.
-
-See [docs/caching.md](docs/caching.md) for the measured behavior: TTL, cross-protocol cache reuse, 256-token prefix alignment, device-id sharing, and the cases that invalidate cache.
+Kimi's cache is content-based and keyed purely by prompt prefix. `prompt_cache_key`, Anthropic `cache_control` markers, and device-id headers are ignored. Cache benefits accrue within a session, not across cold starts. See [docs/caching.md](docs/caching.md) for measured behavior.
 
 ### 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.
+Kimi's coding endpoint speaks both Anthropic and OpenAI dialects. This extension defaults to OpenAI-compatible mode (`/coding/v1/chat/completions`) because it uses a dedicated `role: "tool"` message, which keeps tool results separate from user messages in multi-turn loops. Anthropic mode (`/coding/v1/messages`) is available if your setup depends on Anthropic-style semantics. See [issue #5](https://github.com/Leechael/pi-provider-kimi-code/issues/5) for details.
 
 ### Is this affiliated with Moonshot AI?
 
@@ -257,25 +212,19 @@ No. This is an independent extension. The login flow is derived from the public
 
 ### `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 uses Node's `fetch` / undici stack, which handles `http_proxy` / `https_proxy` / `all_proxy` differently from `curl`. Check the proxy variables in the Pi process's environment. `scripts/test_e2e.sh` prints the effective proxy settings for debugging.
 
 ### `/login kimi-coding` prints a device code but the browser never opens
 
-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.
+The login flow always prints a verification URL. Copy it into a browser manually if your terminal or OS blocks auto-open.
 
 ### "Access denied" or subscription errors after a successful login
 
-Your Moonshot account needs an active Kimi Code Plan for the provider to do anything useful. If the same account works in `kimi-code`, re-run `/login kimi-coding` to refresh credentials.
-
-### Tools do not show up
-
-Run `/kimi-settings` and check whether the tool is enabled in the home or project config. All 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.
+Your Moonshot account needs an active Kimi Code Plan. If the same account works in `kimi-code`, re-run `/login kimi-coding` to refresh credentials.
 
-### Tools return subscription or whitelist errors
+### Tools do not show up or return errors
 
-The tools call Moonshot's server-side services. Some accounts may not have access even with an active Kimi Code Plan. The error comes from the upstream service.
+Run `/kimi-settings` and check whether the tool is enabled in the home or project config. All tools require OAuth login; `KIMI_API_KEY` is not enough. Subscription or whitelist errors come from the upstream Moonshot service.
 
 ### Large images fail with a payload error
 
@@ -283,19 +232,11 @@ This extension uploads images over `KIMI_CODE_UPLOAD_THRESHOLD_BYTES` (default 1
 
 ### Prompt cache never seems to hit
 
-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 a focused suite under `scripts/e2e/cache/`, starting with `scripts/e2e/cache/ttl.sh`. See [docs/caching.md](docs/caching.md) for full mechanics.
+Cache benefits accrue within a single session. If `cache_read_input_tokens` (Anthropic) or `cached_tokens` (OpenAI) stays at `0`, something in the prompt is varying between turns — a changed system prompt, tool set, `ms://` reference, or timestamp. See [docs/caching.md](docs/caching.md) for the full list of invalidation causes and measurement scripts.
 
 ### OpenAI-compatible tools complain about a `developer` role
 
-In OpenAI mode this extension maps the `developer` role to `system` (Kimi's Coding endpoint does not recognize `developer`). If something in your toolchain expects `developer` to round-trip, use Anthropic mode instead.
+In OpenAI mode this extension maps `developer` to `system` because Kimi's Coding endpoint does not recognize `developer`. Use Anthropic mode if your toolchain expects `developer` to round-trip.
 
 ## References
 
@@ -306,10 +247,6 @@ In OpenAI mode this extension maps the `developer` role to `system` (Kimi's Codi
 - Cache behavior: [docs/caching.md](docs/caching.md)
 - Architecture notes: [docs/architecture.md](docs/architecture.md)
 
-## Credits
-
-Based on the login implementation from Kimi Code by Moonshot AI. Pi was originally created by [@badlogic](https://github.com/badlogic).
-
 ## License
 
 MIT