pi-provider-kimi-code 0.1.9 → 0.2.0

package/README.md

@@ -1,16 +1,38 @@
-# pi-provider-kimi-code
-
+# 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 Membership](https://www.kimi.com/code/docs/en/) inside [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)** — 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.
+
+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 K2.5, Kimi K2 Thinking Turbo, and the umbrella `kimi-code` model 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.
+
+## Who is this for?
+
+- You already pay for a **[Kimi Code Membership](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.5** or **Kimi K2 Thinking Turbo** as a pi provider.
+
+Pay-per-token via `KIMI_API_KEY` also works if you just want to try Kimi in CI or without a subscription.
+
+## Features
 
-A [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) custom provider extension that adds [Kimi Code](https://kimi.com) models with OAuth device-code login.
+- **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 three 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.
 
 ## Install
 
+From npm:
+
 ```bash
 pi install npm:pi-provider-kimi-code
 ```
 
-Or load without installing:
+Or load a local checkout without installing:
 
 ```bash
 pi -e /path/to/pi-provider-kimi-code
@@ -18,19 +40,19 @@ pi -e /path/to/pi-provider-kimi-code
 
 ## Authentication
 
-### OAuth (recommended)
+### Browser login (recommended)
 
-Inside pi, run:
+Inside `pi`, run:
 
 ```
 /login kimi-coding
 ```
 
-This starts the device-code flow — a browser window opens, you authorize, and credentials are stored automatically.
+A browser tab opens, you sign into your Kimi account, and credentials are stored at `~/.pi/agent/auth.json`. Tokens refresh automatically.
 
-### API Key
+### API key
 
-Set the `KIMI_API_KEY` environment variable:
+For CI or pay-per-token use, set `KIMI_API_KEY`:
 
 ```bash
 KIMI_API_KEY=sk-... pi
@@ -44,101 +66,88 @@ KIMI_API_KEY=sk-... pi
 | `kimi-k2.5`              | Kimi K2.5                        | yes       | text, image | 262 144 | 32 000     |
 | `kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo           | yes       | text        | 262 144 | 32 000     |
 
-Select a model inside pi:
+Select a model inside `pi`:
 
 ```
 /model kimi-coding/kimi-code
 ```
 
-## Environment Overrides
+## Environment variables
 
-- `KIMI_CODE_BASE_URL` — override the default API base URL (default depends on protocol; see below)
-- `KIMI_CODE_OAUTH_HOST` — override the OAuth host
-- `KIMI_OAUTH_HOST` — fallback OAuth host override for compatibility
-- `KIMI_CODE_PROTOCOL` — choose protocol mode:
-  - unset / `anthropic` → `anthropic-messages` via `/coding/v1/messages`
-  - `openai` → `openai-completions` via `/coding/v1/chat/completions`
-- `KIMI_MODEL_TEMPERATURE` — force temperature on outbound requests
-- `KIMI_MODEL_TOP_P` — force top-p on outbound requests
-- `KIMI_MODEL_MAX_TOKENS` — force max tokens on outbound requests
-- `KIMI_CODE_DEBUG=1` — print provider-side debug logs (request metadata, file upload logs)
+| 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           |
 
-## Prompt Caching
+Full list with defaults and the test-script variables: [docs/ENV.md](docs/ENV.md).
 
-Kimi Code API requires a `prompt_cache_key` field at the payload root for prompt caching. The pi framework separately injects Anthropic-style `cache_control: { type: "ephemeral" }` markers. This extension bridges both:
+## FAQ
 
-1. **Session key injection**: Extracts your current pi `sessionId` and injects it as `prompt_cache_key` on every request.
-2. **TTL**: Approximately **5-10 minutes**. Consistently hits at 300s, borderline at 600s, misses at 900s. Measure in your environment with `KIMI_E2E_ONLY_CACHE=1` (see [E2E test script](#end-to-end-test-script)).
-3. **Manual override**: Set `prompt_cache_key` explicitly in the payload or options to override the automatic session-based key.
+### How is this different from the official `kimi-cli`?
 
-Cache usage is easiest to verify on the Anthropic-compatible endpoint, which returns `cache_read_input_tokens` / `cache_creation_input_tokens` fields.
+`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.
 
-## OpenAI Compatibility Mode
+### Do I need a paid Kimi subscription?
 
-Set `KIMI_CODE_PROTOCOL=openai` to switch the provider to Kimi Coding's OpenAI-compatible chat completions endpoint. Internally this extension uses `openai-completions` (not `openai-responses`) and applies Kimi-specific compatibility overrides:
+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.
 
-- Maps `developer` role to `system` (Kimi does not recognize the OpenAI `developer` role)
-- Disables `store`
-- Uses `max_tokens`
-- Sends `KimiCLI/*` + `X-Msh-*` agent headers required by the Coding endpoint
+### Where does my data go?
 
-## End-to-End Test Script
+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.
 
-This repo includes a tracked smoke-test script:
+### Is this affiliated with Moonshot AI?
 
-```bash
-KIMI_API_KEY=sk-... ./test_e2e.sh
-```
+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.
+
+### Which pi version does this work with?
+
+Any recent [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent).
+
+### Why are there two protocol modes?
+
+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.
+
+## 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.
+
+### `/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.
+
+### "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.
+
+### 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.
+
+### 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).
+
+### 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.
+
+## References
 
-By default it explicitly targets `--model kimi-coding/kimi-code`, disables extension discovery with `-ne`, and turns on provider debug logging.
-
-What it does:
-
-1. Runs a `pi -ne -e <extension-dir>` smoke test in Anthropic mode.
-2. Runs the same smoke test in OpenAI mode.
-3. Runs a high-thinking smoke test (saves full JSONL, extracts thinking + answer + usage).
-4. Runs a prompt-cache TTL probe and prints a conclusion on observed cache lifetime.
-5. Uploads a watermarked image to `/files`, then asks the model to read back the watermark via `ms://` reference.
-6. Sends a `prompt_cache_key` request directly to verify cache key injection.
-
-Useful environment variables for the test script:
-
-| Variable                   | Default                 | Description                             |
-| -------------------------- | ----------------------- | --------------------------------------- |
-| `KIMI_API_KEY`             | (required)              | API key (or pass as positional arg)     |
-| `KIMI_CODE_DEBUG`          | `1`                     | Provider debug logs                     |
-| `KIMI_E2E_VERBOSE`         | `1`                     | Command and environment diagnostics     |
-| `KIMI_E2E_MODEL`           | `kimi-coding/kimi-code` | Model for `pi` smoke tests              |
-| `KIMI_E2E_CACHE_INTERVALS` | `60,300`                | Absolute seconds from warmup per probe  |
-| `KIMI_E2E_CACHE_KEY`       | auto                    | Override cache key for TTL probe        |
-| `KIMI_E2E_CACHE_REPEAT`    | `2000`                  | Long-text repeat count for cache warmup |
-| `KIMI_E2E_SKIP_CACHE`      | `0`                     | Set `1` to skip the cache TTL phase     |
-| `KIMI_E2E_ONLY_CACHE`      | `0`                     | Set `1` to run only the cache TTL test  |
-
-### Proxy / networking note
-
-If `curl` can reach Kimi but `pi` reports `fetch failed`, check your `http_proxy` / `https_proxy` / `all_proxy` environment. `pi` runs on Node's `fetch` / undici stack, which may behave differently from `curl`; the test script prints the effective proxy-related environment for easier debugging.
-
-## How It Works
-
-- Registers provider `kimi-coding` with Kimi's API endpoint
-- Supports two protocol modes:
-  - `anthropic-messages` (default)
-  - `openai-completions` when `KIMI_CODE_PROTOCOL=openai`
-- Adds a small `streamSimple` wrapper to suppress Kimi's leaked `(Empty response: ...)` placeholder blocks
-- Injects `prompt_cache_key` automatically so Kimi's cache works with pi sessions
-- Maps pi thinking levels to Kimi-native `reasoning_effort` + `extra_body.thinking`
-- Pre-uploads large image / video attachments to Kimi Files API (returns `ms://` references)
-- Maps `developer` role to `system` for OpenAI protocol compatibility
-- Sends the same `KimiCLI/1.30.0` + `X-Msh-*` headers as current `kimi-cli`
-- Persists a stable device ID at `~/.pi/providers/kimi-coding/device_id`
-- OAuth uses [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628) device authorization grant against `https://auth.kimi.com`
-- Zero dependencies — types from `@mariozechner/pi-ai` and `@mariozechner/pi-coding-agent` are provided by the pi runtime
-- Zero build step — pi loads TypeScript directly via jiti
+- 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)
+- 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)
+- Architecture notes: [docs/architecture.md](docs/architecture.md)
 
 ## Credits
 
-This extension is based on the OAuth implementation from [kimi-cli](https://github.com/MoonshotAI/kimi-cli) by Moonshot AI.
+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).
 
 ## License
 

package/index.ts

@@ -18,9 +18,11 @@ import type {
   OAuthCredentials,
   OAuthLoginCallbacks,
   AssistantMessageEvent,
+  CacheRetention,
   Context,
   Model,
   SimpleStreamOptions,
+  ThinkingLevel,
 } from "@mariozechner/pi-ai";
 import {
   streamSimpleAnthropic,
@@ -361,13 +363,39 @@ async function refreshKimiCodeToken(credentials: OAuthCredentials): Promise<OAut
 }
 
 // =============================================================================
-// Stream wrapper: strip "(Empty response: ...)" text blocks from Kimi API
+// Payload / stream helpers: types + pure utilities
 // =============================================================================
-// The Kimi API wraps thinking-only responses (no text content) into a text
-// block like: (Empty response: {'content': [{'type': 'thinking', ...}]})
-// This leaks internal state to the user. We detect and suppress such blocks.
 
 const EMPTY_RESPONSE_PREFIX = "(Empty response:";
+const DEFAULT_KIMI_INLINE_UPLOAD_THRESHOLD_BYTES = 1 * 1024 * 1024;
+
+type JsonRecord = Record<string, unknown>;
+type Uploader = (mimeType: string, data: string) => Promise<string | null>;
+
+interface KimiEnvOverrides {
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+}
+
+function resolveCacheRetention(value?: CacheRetention): CacheRetention {
+  if (value === "none" || value === "short" || value === "long") return value;
+  if (process.env.PI_CACHE_RETENTION === "long") return "long";
+  return "short";
+}
+
+interface KimiPayloadContext {
+  api: "anthropic-messages" | "openai-completions";
+  upload?: Uploader;
+  cacheKey?: string;
+  cacheRetention: CacheRetention;
+  reasoning?: ThinkingLevel;
+  envOverrides: KimiEnvOverrides;
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 
 function mapThinkingLevel(level?: string): { effort: string | null; enabled: boolean } | undefined {
   if (!level) return undefined;
@@ -378,215 +406,373 @@ function mapThinkingLevel(level?: string): { effort: string | null; enabled: boo
   return undefined;
 }
 
-async function transformContextFiles(context: Context, apiKey: string): Promise<Context> {
-  const transformedMessages = [];
-  for (const message of context.messages) {
-    if (message.role === "user" && Array.isArray(message.content)) {
-      const newContent = [];
-      for (const block of message.content) {
-        if (block.type === "image") {
-          // If the image is extremely large or if it's actually a video masquerading as an image,
-          // upload it to Kimi's /v1/files endpoint.
-          // For Kimi, images > 5MB or videos should be uploaded. We'll use 5MB threshold.
-          const buffer = Buffer.from(block.data, "base64");
-          if (buffer.length > 5 * 1024 * 1024 || block.mimeType.startsWith("video/")) {
-            const formData = new FormData();
-            const filename = block.mimeType.startsWith("video/") ? "upload.mp4" : "upload.png";
-            formData.append("file", new Blob([buffer], { type: block.mimeType }), filename);
-            formData.append("purpose", block.mimeType.startsWith("video/") ? "video" : "image");
-
-            const filesBaseUrl = (
-              process.env.KIMI_CODE_BASE_URL || "https://api.kimi.com/coding/v1"
-            ).replace(/\/$/, "");
-            const uploadUrl = `${filesBaseUrl}/files`;
-            if (process.env.KIMI_CODE_DEBUG === "1") {
-              console.log(
-                `\n[kimi-coding] Uploading ${filename} to ${uploadUrl} (size: ${(buffer.length / 1024 / 1024).toFixed(2)} MB)...`,
-              );
-            }
-            const response = await fetch(uploadUrl, {
-              method: "POST",
-              headers: {
-                Authorization: `Bearer ${apiKey}`,
-                ...getCommonHeaders(),
-              },
-              body: formData,
-            });
-
-            if (response.ok) {
-              const fileObj = (await response.json()) as { id?: string; url?: string };
-              const fileUrl = `ms://${fileObj.id}`;
-              if (process.env.KIMI_CODE_DEBUG === "1") {
-                console.log(`[kimi-coding] Upload success. File URL: ${fileUrl}`);
-              }
-              // Replace the block with Kimi's specific reference
-              if (block.mimeType.startsWith("video/")) {
-                newContent.push({
-                  type: "video_url" as any,
-                  video_url: { url: fileUrl },
-                });
-              } else {
-                newContent.push({
-                  type: "image_url" as any,
-                  image_url: { url: fileUrl },
-                });
-              }
-              continue;
-            } else {
-              console.error("Failed to upload file to Kimi API", await response.text());
-            }
-          }
+function parseInlineUploadThreshold(raw: string | undefined): number {
+  const parsed = Number.parseInt(raw ?? "", 10);
+  return Number.isFinite(parsed) && parsed >= 0
+    ? parsed
+    : DEFAULT_KIMI_INLINE_UPLOAD_THRESHOLD_BYTES;
+}
+
+function deriveFilesBaseUrl(baseUrl: string): string {
+  const trimmed = baseUrl.replace(/\/$/, "");
+  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+
+function parseDataUrl(url: string): { mimeType: string; data: string } | null {
+  const match = url.match(/^data:([^;,]+);base64,([A-Za-z0-9+/=]+)$/);
+  return match ? { mimeType: match[1], data: match[2] } : null;
+}
+
+function getUploadFilename(mimeType: string): string {
+  const map: Record<string, string> = {
+    "image/jpeg": "upload.jpg",
+    "image/png": "upload.png",
+    "image/gif": "upload.gif",
+    "image/webp": "upload.webp",
+    "video/mp4": "upload.mp4",
+    "video/quicktime": "upload.mov",
+  };
+  return map[mimeType] ?? (mimeType.startsWith("video/") ? "upload.mp4" : "upload.bin");
+}
+
+function readEnvOverrides(): KimiEnvOverrides {
+  const out: KimiEnvOverrides = {};
+  const temp = process.env.KIMI_MODEL_TEMPERATURE;
+  if (temp) out.temperature = parseFloat(temp);
+  const topP = process.env.KIMI_MODEL_TOP_P;
+  if (topP) out.topP = parseFloat(topP);
+  const maxTokens = process.env.KIMI_MODEL_MAX_TOKENS;
+  if (maxTokens) out.maxTokens = parseInt(maxTokens, 10);
+  return out;
+}
+
+// =============================================================================
+// File upload (I/O edge)
+// =============================================================================
+
+async function uploadKimiFile(
+  apiKey: string,
+  mimeType: string,
+  data: string,
+): Promise<string | null> {
+  const buffer = Buffer.from(data, "base64");
+  const isVideo = mimeType.startsWith("video/");
+  const threshold = parseInlineUploadThreshold(process.env.KIMI_CODE_UPLOAD_THRESHOLD_BYTES);
+  if (!isVideo && buffer.length <= threshold) return null;
+
+  const filename = getUploadFilename(mimeType);
+  const formData = new FormData();
+  formData.append("file", new Blob([buffer], { type: mimeType }), filename);
+  formData.append("purpose", isVideo ? "video" : "image");
+
+  const baseUrl = process.env.KIMI_CODE_BASE_URL || DEFAULT_BASE_URL;
+  const uploadUrl = `${deriveFilesBaseUrl(baseUrl)}/files`;
+  const debug = process.env.KIMI_CODE_DEBUG === "1";
+  if (debug) {
+    console.log(
+      `\n[kimi-coding] Uploading ${filename} to ${uploadUrl} (${(buffer.length / 1024 / 1024).toFixed(2)} MB)`,
+    );
+  }
+
+  try {
+    const response = await fetch(uploadUrl, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, ...getCommonHeaders() },
+      body: formData,
+    });
+    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
+    const fileObj = (await response.json()) as { id?: string };
+    if (!fileObj.id) throw new Error("missing file id");
+    const fileUrl = `ms://${fileObj.id}`;
+    if (debug) console.log(`[kimi-coding] Upload success: ${fileUrl}`);
+    return fileUrl;
+  } catch (err) {
+    console.error("[kimi-coding] Upload failed:", err);
+    return null;
+  }
+}
+
+// =============================================================================
+// Payload file transformers (pure given an Uploader)
+// =============================================================================
+// These walk the provider-specific payload shape and replace inline base64
+// image/video blocks with ms:// references returned by the injected uploader.
+// They take an Uploader rather than an apiKey so they can be unit-tested with
+// a fake uploader; all network I/O stays behind that boundary.
+
+async function transformOpenAIPayloadFiles(payload: JsonRecord, upload: Uploader): Promise<void> {
+  if (!Array.isArray(payload.messages)) return;
+  const cache = new Map<string, string>();
+
+  for (const message of payload.messages) {
+    if (!isRecord(message) || !Array.isArray(message.content)) continue;
+
+    for (const block of message.content) {
+      if (!isRecord(block)) continue;
+      const key =
+        block.type === "image_url" ? "image_url" : block.type === "video_url" ? "video_url" : null;
+      if (!key) continue;
+
+      const field = block[key];
+      const urlValue =
+        typeof field === "string"
+          ? field
+          : isRecord(field) && typeof field.url === "string"
+            ? field.url
+            : null;
+      if (!urlValue || urlValue.startsWith("ms://")) continue;
+
+      const parsed = parseDataUrl(urlValue);
+      if (!parsed) continue;
+
+      const uploaded = cache.get(urlValue) ?? (await upload(parsed.mimeType, parsed.data));
+      if (!uploaded) continue;
+      cache.set(urlValue, uploaded);
+
+      block[key] =
+        typeof field === "string" ? uploaded : { ...(field as JsonRecord), url: uploaded };
+    }
+  }
+}
+
+async function transformAnthropicPayloadFiles(
+  payload: JsonRecord,
+  upload: Uploader,
+): Promise<void> {
+  if (!Array.isArray(payload.messages)) return;
+  const cache = new Map<string, string>();
+
+  const transformImageBlock = async (block: unknown): Promise<unknown> => {
+    if (!isRecord(block) || block.type !== "image") return block;
+    const source = block.source;
+    if (!isRecord(source) || source.type !== "base64") return block;
+    const mediaType = source.media_type;
+    const data = source.data;
+    if (typeof mediaType !== "string" || typeof data !== "string") return block;
+
+    const cacheKey = `${mediaType}:${data}`;
+    const uploaded = cache.get(cacheKey) ?? (await upload(mediaType, data));
+    if (!uploaded) return block;
+    cache.set(cacheKey, uploaded);
+
+    const next: JsonRecord = { type: "image", source: { type: "url", url: uploaded } };
+    if (block.cache_control !== undefined) next.cache_control = block.cache_control;
+    return next;
+  };
+
+  for (const message of payload.messages) {
+    if (!isRecord(message) || !Array.isArray(message.content)) continue;
+
+    for (let i = 0; i < message.content.length; i++) {
+      const block = message.content[i];
+      if (isRecord(block) && block.type === "tool_result" && Array.isArray(block.content)) {
+        for (let j = 0; j < block.content.length; j++) {
+          block.content[j] = await transformImageBlock(block.content[j]);
         }
-        newContent.push(block);
+        continue;
       }
-      transformedMessages.push({ ...message, content: newContent });
-    } else {
-      transformedMessages.push(message);
+      message.content[i] = await transformImageBlock(block);
     }
   }
-  return { ...context, messages: transformedMessages };
 }
 
+// =============================================================================
+// Payload mutation pipeline
+// =============================================================================
+// Applies all Kimi-specific mutations to a provider payload in place.
+// Pure given its context: no process.env / fs / network access of its own —
+// every side effect enters via ctx.upload or pre-read values in ctx.
+// This makes the five steps below testable with fixture payloads.
+
+async function applyKimiPayloadMutations(
+  payload: JsonRecord,
+  ctx: KimiPayloadContext,
+): Promise<void> {
+  // 1. Map unsupported roles: Kimi does not recognize "developer" (OpenAI-specific).
+  if (Array.isArray(payload.messages)) {
+    payload.messages = payload.messages.map((msg) =>
+      isRecord(msg) && msg.role === "developer" ? { ...msg, role: "system" } : msg,
+    );
+  }
+
+  // 2. File upload dispatch (protocol-specific).
+  if (ctx.upload) {
+    if (ctx.api === "openai-completions") {
+      await transformOpenAIPayloadFiles(payload, ctx.upload);
+    } else if (ctx.api === "anthropic-messages") {
+      await transformAnthropicPayloadFiles(payload, ctx.upload);
+    }
+  }
+
+  // 3. prompt_cache_key injection. Respect any key already on the payload,
+  //    otherwise fall back to the caller-provided cacheKey (sessionId or
+  //    explicit options.prompt_cache_key override). Skipped entirely when
+  //    cacheRetention is "none" (via options.cacheRetention or
+  //    PI_CACHE_RETENTION) so callers can truly disable caching — otherwise
+  //    Kimi's native session cache would still fire even if pi-ai's
+  //    Anthropic-style cache_control markers are omitted.
+  if (ctx.cacheRetention !== "none") {
+    const existing = payload.prompt_cache_key;
+    const resolved = (typeof existing === "string" && existing) || ctx.cacheKey;
+    if (resolved) payload.prompt_cache_key = resolved;
+  }
+
+  // 4. Env-level hyperparameter overrides (pre-parsed into numbers by caller).
+  const { temperature, topP, maxTokens } = ctx.envOverrides;
+  if (temperature !== undefined) payload.temperature = temperature;
+  if (topP !== undefined) payload.top_p = topP;
+  if (maxTokens !== undefined) payload.max_tokens = maxTokens;
+
+  // 5. Reasoning effort mapping.
+  if (ctx.reasoning) {
+    const mapped = mapThinkingLevel(ctx.reasoning);
+    if (mapped) {
+      payload.reasoning_effort = mapped.effort;
+      const extraBody = isRecord(payload.extra_body) ? payload.extra_body : {};
+      extraBody.thinking = { type: mapped.enabled ? "enabled" : "disabled" };
+      payload.extra_body = extraBody;
+    }
+  }
+}
+
+// =============================================================================
+// Event stream filter: suppress Kimi "(Empty response: ...)" text blocks
+// =============================================================================
+// The Kimi API wraps thinking-only responses (no text content) into a text
+// block like: (Empty response: {'content': [{'type': 'thinking', ...}]}).
+// This leaks internal state to the user. We buffer text_start/text_delta
+// events and drop the whole block if text_end starts with the marker.
+// Pure async generator — no closure dependencies, testable with synthetic
+// event arrays.
+
+async function* filterEmptyResponseStream(
+  upstream: AsyncIterable<AssistantMessageEvent>,
+): AsyncIterable<AssistantMessageEvent> {
+  const suppressedIndices = new Set<number>();
+  let textBuffer: AssistantMessageEvent[] = [];
+  let bufferingIndex: number | null = null;
+
+  for await (const event of upstream) {
+    // Start buffering when a new text block begins.
+    if (event.type === "text_start") {
+      bufferingIndex = event.contentIndex;
+      textBuffer = [event];
+      continue;
+    }
+
+    // Accumulate text deltas + detect the empty-response marker on text_end.
+    if (
+      bufferingIndex !== null &&
+      "contentIndex" in event &&
+      event.contentIndex === bufferingIndex
+    ) {
+      if (event.type === "text_delta") {
+        textBuffer.push(event);
+        continue;
+      }
+      if (event.type === "text_end") {
+        if (event.content.startsWith(EMPTY_RESPONSE_PREFIX)) {
+          // Suppress entire text block. Do NOT splice the message content
+          // array: it is a shared reference into session state, and mutating
+          // it would shift subsequent contentIndex values, corrupting the
+          // stream.
+          suppressedIndices.add(bufferingIndex);
+        } else {
+          // Legitimate text block — flush buffered events + end event.
+          for (const buffered of textBuffer) yield buffered;
+          yield event;
+        }
+        textBuffer = [];
+        bufferingIndex = null;
+        continue;
+      }
+    }
+
+    // Skip any event targeting an already-suppressed content index.
+    if ("contentIndex" in event && suppressedIndices.has(event.contentIndex)) {
+      continue;
+    }
+
+    // Clean suppressed blocks out of the final message.
+    if (event.type === "done" && suppressedIndices.size > 0) {
+      event.message.content = event.message.content.filter(
+        (block) =>
+          !(
+            block.type === "text" &&
+            typeof block.text === "string" &&
+            block.text.startsWith(EMPTY_RESPONSE_PREFIX)
+          ),
+      );
+    }
+
+    yield event;
+  }
+}
+
+// =============================================================================
+// Stream wrapper: orchestrates payload mutation + event filter
+// =============================================================================
+// Reads every side-effect source (process.env, options, apiKey) at the top
+// and hands a plain KimiPayloadContext to applyKimiPayloadMutations. The only
+// thing this function itself "does" is wire SDK streaming + filter + error
+// fallback; the actual logic lives in the pure units above.
+
 function streamSimpleKimi(
   model: Model<"anthropic-messages" | "openai-completions">,
   context: Context,
   options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
-  // Pre-process context files: upload large images/videos to Kimi API
   const filtered = new AssistantMessageEventStream();
   const apiKey = options?.apiKey || process.env.KIMI_API_KEY || "";
 
-  void (async () => {
-    let finalContext = context;
-    try {
-      if (apiKey) {
-        finalContext = await transformContextFiles(context, apiKey);
+  const cacheKeyOverride = (
+    options as (SimpleStreamOptions & { prompt_cache_key?: unknown }) | undefined
+  )?.prompt_cache_key;
+  const cacheKey = (typeof cacheKeyOverride === "string" && cacheKeyOverride) || options?.sessionId;
+  const cacheRetention = resolveCacheRetention(options?.cacheRetention);
+  const envOverrides = readEnvOverrides();
+  const upload: Uploader | undefined = apiKey
+    ? (mimeType, data) => uploadKimiFile(apiKey, mimeType, data)
+    : undefined;
+
+  const originalOnPayload = options?.onPayload;
+  const patchedOptions: SimpleStreamOptions = {
+    ...options,
+    onPayload: async (payload, modelData) => {
+      let nextPayload: unknown = payload;
+
+      if (isRecord(nextPayload)) {
+        await applyKimiPayloadMutations(nextPayload, {
+          api: model.api,
+          upload,
+          cacheKey,
+          cacheRetention,
+          reasoning: options?.reasoning,
+          envOverrides,
+        });
       }
-    } catch (e) {
-      console.error("Error transforming context files", e);
-    }
-
-    // Intercept the payload to inject Kimi's proprietary prompt_cache_key
-    // because Kimi's Anthropic compatibility endpoint requires it alongside cache_control.
-    const originalOnPayload = options?.onPayload;
-    const patchedOptions: SimpleStreamOptions = {
-      ...options,
-      onPayload: async (payload: any, modelData) => {
-        let nextPayload = payload;
-        if (originalOnPayload) {
-          const res = await originalOnPayload(payload, modelData);
-          if (res !== undefined) nextPayload = res;
-        }
 
-        if (nextPayload && typeof nextPayload === "object") {
-          // Map unsupported roles: Kimi does not recognize "developer" (OpenAI-specific).
-          if (Array.isArray(nextPayload.messages)) {
-            nextPayload.messages = nextPayload.messages.map((msg: any) =>
-              msg.role === "developer" ? { ...msg, role: "system" } : msg,
-            );
-          }
-
-          // Inject prompt_cache_key: allow explicit override, fallback to stable sessionId.
-          const cacheKey =
-            nextPayload.prompt_cache_key ||
-            (options as any)?.prompt_cache_key ||
-            options?.sessionId;
-          if (cacheKey) {
-            nextPayload = { ...nextPayload, prompt_cache_key: cacheKey };
-          }
+      if (originalOnPayload) {
+        const res = await originalOnPayload(nextPayload, modelData);
+        if (res !== undefined) nextPayload = res;
+      }
 
-          // Environment overrides
-          const envTemp = process.env.KIMI_MODEL_TEMPERATURE;
-          if (envTemp) nextPayload.temperature = parseFloat(envTemp);
-
-          const envTopP = process.env.KIMI_MODEL_TOP_P;
-          if (envTopP) nextPayload.top_p = parseFloat(envTopP);
-
-          const envMaxTokens = process.env.KIMI_MODEL_MAX_TOKENS;
-          if (envMaxTokens) nextPayload.max_tokens = parseInt(envMaxTokens, 10);
-
-          // Reasoning effort mapping
-          const reasoningLevel = (options as any)?.reasoning;
-          if (reasoningLevel) {
-            const mapped = mapThinkingLevel(reasoningLevel);
-            if (mapped) {
-              nextPayload.reasoning_effort = mapped.effort;
-              nextPayload.extra_body = nextPayload.extra_body || {};
-              nextPayload.extra_body.thinking = {
-                type: mapped.enabled ? "enabled" : "disabled",
-              };
-            }
-          }
-        }
-        return nextPayload;
-      },
-    };
+      return nextPayload;
+    },
+  };
 
+  void (async () => {
     const upstream =
       model.api === "openai-completions"
-        ? streamSimpleOpenAICompletions(model as any, finalContext, patchedOptions)
-        : streamSimpleAnthropic(model as any, finalContext, patchedOptions);
-
-    // Buffer text block events so we can suppress the entire block if it
-    // turns out to be a Kimi "(Empty response: ...)" wrapper.
-    const suppressedIndices = new Set<number>();
-    let textBuffer: AssistantMessageEvent[] = [];
-    let bufferingIndex: number | null = null;
+        ? streamSimpleOpenAICompletions(
+            model as Model<"openai-completions">,
+            context,
+            patchedOptions,
+          )
+        : streamSimpleAnthropic(model as Model<"anthropic-messages">, context, patchedOptions);
 
     try {
-      for await (const event of upstream) {
-        // Start buffering when a new text block begins
-        if (event.type === "text_start") {
-          bufferingIndex = event.contentIndex;
-          textBuffer = [event];
-          continue;
-        }
-
-        // Accumulate text deltas while buffering
-        if (
-          bufferingIndex !== null &&
-          "contentIndex" in event &&
-          event.contentIndex === bufferingIndex
-        ) {
-          if (event.type === "text_delta") {
-            textBuffer.push(event);
-            continue;
-          }
-          if (event.type === "text_end") {
-            if (event.content.startsWith(EMPTY_RESPONSE_PREFIX)) {
-              // Suppress entire text block — discard buffered events.
-              // Do NOT splice content array: it is a shared reference
-              // into session state, and mutating it shifts subsequent
-              // contentIndex values, corrupting the stream.
-              suppressedIndices.add(bufferingIndex);
-            } else {
-              // Legitimate text block — flush buffer + end event
-              for (const buffered of textBuffer) filtered.push(buffered);
-              filtered.push(event);
-            }
-            textBuffer = [];
-            bufferingIndex = null;
-            continue;
-          }
-        }
-
-        // Skip events for already-suppressed indices
-        if ("contentIndex" in event && suppressedIndices.has(event.contentIndex)) {
-          continue;
-        }
-
-        // Clean suppressed blocks from the final message
-        if (event.type === "done" && suppressedIndices.size > 0) {
-          event.message.content = event.message.content.filter(
-            (block) =>
-              !(
-                block.type === "text" &&
-                typeof block.text === "string" &&
-                block.text.startsWith(EMPTY_RESPONSE_PREFIX)
-              ),
-          );
-        }
-
+      for await (const event of filterEmptyResponseStream(upstream)) {
         filtered.push(event);
       }
     } catch (err) {

package/package.json

@@ -1,20 +1,40 @@
 {
   "name": "pi-provider-kimi-code",
-  "version": "0.1.9",
-  "description": "pi custom provider extension for Kimi Code models with OAuth device-code login",
+  "version": "0.2.0",
+  "description": "Pi extension for Kimi Code — reuse your kimi.com Membership in pi-coding-agent (K2.5, K2 Thinking Turbo)",
   "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-provider",
+    "pi",
+    "pi-coding-agent",
+    "pi-mono",
     "coding-agent",
+    "ai-provider",
+    "llm",
+    "llm-provider",
     "kimi",
     "kimi-code",
-    "llm",
-    "pi",
-    "pi-extension"
+    "kimi-for-coding",
+    "kimi-coder",
+    "kimi-k2",
+    "kimi-k2.5",
+    "kimi-k2-thinking",
+    "moonshot",
+    "moonshotai",
+    "oauth",
+    "device-code",
+    "subscription"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/Leechael/pi-provider-kimi-code"
   },
+  "bugs": {
+    "url": "https://github.com/Leechael/pi-provider-kimi-code/issues"
+  },
+  "author": "Leechael",
   "files": [
     "index.ts",
     "package.json",
@@ -30,6 +50,10 @@
     "format:check": "oxfmt . --check",
     "pre-commit": "prek run"
   },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*"
+  },
   "devDependencies": {
     "@j178/prek": "^0.3.8",
     "oxfmt": "^0.44.0",