pi-provider-kimi-code 0.6.8 → 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 reads Kimi's live `/v1/models` catalog as the source of truth for model availability and context limits. It refreshes the catalog at startup and through `/kimi-settings`; OAuth login and token refresh also update it.
+> **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 from Kimi's official catalog, including server-advertised model availability and context limits.
-- 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,39 +71,24 @@ 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
-```
-
-If you already use `kimi-code`, the extension can reuse that session. Set `KIMI_CODE_HOME` if its home directory lives somewhere else.
+Pi's built-in `kimi-coding` provider already supports OAuth login via `/login`. This extension handles the credential layer around that login:
 
-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
+## Models (legacy provider registration)
+
+> **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.
 
-The official catalog determines the models this provider publishes. The following IDs are the fallback set when catalog discovery is unavailable:
+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:
 
 | Pi model ID                             | Default name             | Availability and context |
 | --------------------------------------- | ------------------------ | ------------------------ |
@@ -118,16 +98,6 @@ The official catalog determines the models this provider publishes. The followin
 
 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.
 
-Select a model inside Pi:
-
-```text
-/model kimi-coding/kimi-for-coding
-/model kimi-coding/kimi-for-coding-highspeed
-/model kimi-coding/k3
-```
-
-Kimi keeps Coding models behind aliases. Rather than hardcoding a stale model list, this extension reads the official catalog at startup, when credentials change, and through `/kimi-settings`. If your account is on a newer rollout (e.g., Kimi K2.7) or internal test, Pi can pick up the latest model IDs, names, and context sizes without waiting for a package release.
-
 Fallback values:
 
 - Context window: `256k` tokens
@@ -141,7 +111,7 @@ Switching models or thinking effort invalidates Kimi's existing context cache. S
 
 ## 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

package/index.ts

@@ -27,6 +27,9 @@ import {
 import { Input, SettingsList, type SettingItem, truncateToWidth } from "@earendil-works/pi-tui";
 import os from "node:os";
 
+// pi-ai <=0.79 has no "./compat"
+const piAiCompatModule = "@earendil-works/pi-ai/compat";
+
 import {
   type KimiCodeConfig,
   type KimiCodeConfigPatch,
@@ -38,7 +41,13 @@ import {
   saveProjectKimiCodeConfig,
   type KimiToolName,
 } from "./src/config.ts";
-import { PROVIDER_ID, PROVIDER_VERSION, getBaseUrl, getKimiApiType } from "./src/constants.ts";
+import {
+  KIMI_GLOBAL_FALLBACK_SOURCE_ID,
+  PROVIDER_ID,
+  PROVIDER_VERSION,
+  getBaseUrl,
+  getKimiApiType,
+} from "./src/constants.ts";
 import {
   type KimiOAuthCredentials,
   type KimiOAuthExtras,
@@ -53,7 +62,12 @@ import {
   hasKimiModelMetadata,
   resolveKimiModelConfig,
 } from "./src/models.ts";
-import { getKimiApiKey, loginKimiCode, refreshKimiCodeToken } from "./src/oauth.ts";
+import {
+  getKimiApiKey,
+  loginKimiCode,
+  refreshKimiAuthToken,
+  refreshKimiCodeToken,
+} from "./src/oauth.ts";
 import { isKimiProjectConfigApproved } from "./src/project-trust.ts";
 import {
   type KimiConfigScope,
@@ -69,6 +83,7 @@ import { buildKimiDatasourceTool } from "./src/tools/datasource.ts";
 interface KimiRuntimeState {
   cwd: string;
   config: KimiCodeConfig;
+  fallbackSourceId: string;
   modelExtras: KimiOAuthExtras;
   projectTrusted: boolean;
   overrides?: KimiCodeConfigPatch;
@@ -141,15 +156,30 @@ function applyEffectiveKimiRuntimeConfig(
   return config;
 }
 
-async function refreshModelExtras(state: KimiRuntimeState): Promise<boolean> {
-  const token = getKimiUsageToken();
+async function refreshModelExtras(
+  state: KimiRuntimeState,
+  token = getKimiUsageToken(),
+): Promise<boolean> {
   if (!token) return false;
-  const extras = await discoverKimiModelMetadata(token, state.config.protocol);
+  const extras = await discoverKimiModelMetadata(token, state.config.protocol, {
+    refreshAccessToken: refreshKimiAuthToken,
+  });
   if (Object.keys(extras).length === 0) return false;
   Object.assign(state.modelExtras, extras);
   return true;
 }
 
+// Discovery can lose a race with a concurrent OAuth refresh: the token it
+// started with may already be dead by the time the request goes out. Retry
+// once, but only when the stored token actually changed underneath us.
+async function discoverModelExtras(state: KimiRuntimeState): Promise<boolean> {
+  const token = getKimiUsageToken();
+  if (await refreshModelExtras(state, token)) return true;
+  const refreshedToken = getKimiUsageToken();
+  if (!refreshedToken || refreshedToken === token) return false;
+  return refreshModelExtras(state, refreshedToken);
+}
+
 async function openSettingsMenu(
   pi: ExtensionAPI,
   ctx: ExtensionCommandContext,
@@ -165,7 +195,7 @@ async function openSettingsMenu(
   if (!modelsRefreshed && refreshedToken && refreshedToken !== modelDiscoveryToken) {
     modelsRefreshed = await refreshModelExtras(state);
   }
-  if (modelsRefreshed) registerKimiProvider(pi, state);
+  if (modelsRefreshed) await registerKimiProvider(pi, state);
   const usage = usageSnapshot.summary;
 
   const projectTrusted = await isKimiProjectConfigApproved(ctx, ctx.cwd);
@@ -402,7 +432,84 @@ function buildKimiCatalogModels(state: KimiRuntimeState) {
   );
 }
 
-function registerKimiProvider(pi: ExtensionAPI, state: KimiRuntimeState): void {
+// Node reports a missing subpath export (pi-ai <=0.79) and a missing package
+// with these codes. Both mean "this pi-ai has no compat layer", which is an
+// expected configuration rather than a failure worth reporting: the fallback
+// simply does not exist there.
+const MODULE_UNAVAILABLE_CODES = new Set(["ERR_MODULE_NOT_FOUND", "ERR_PACKAGE_PATH_NOT_EXPORTED"]);
+
+// Every api id this extension can hand out, not only the one for the currently
+// configured protocol: sessions persist the api id that was current when the
+// model was resolved, so a session created before a protocol switch still
+// carries the other id and would keep crashing. streamSimpleKimi routes on the
+// model's wireProtocol / the resolved runtime config and never on model.api, so
+// both ids dispatch identically.
+const KIMI_FALLBACK_APIS = [getKimiApiType("openai"), getKimiApiType("anthropic")];
+
+type PiAiApiRegistry = {
+  registerApiProvider: (
+    provider: {
+      api: string;
+      stream: typeof streamSimpleKimi;
+      streamSimple: typeof streamSimpleKimi;
+    },
+    sourceId: string,
+  ) => void;
+  unregisterApiProviders: (sourceId: string) => void;
+  getApiProvider: (api: string) => unknown;
+};
+
+async function loadPiAiApiRegistry(action: string): Promise<PiAiApiRegistry | null> {
+  try {
+    return (await import(piAiCompatModule)) as PiAiApiRegistry;
+  } catch (error: unknown) {
+    const code = (error as { code?: unknown } | undefined)?.code;
+    if (typeof code === "string" && MODULE_UNAVAILABLE_CODES.has(code)) return null;
+    console.error(
+      `[pi-provider-kimi-code] failed to ${action} the global api fallback:`,
+      error instanceof Error ? error.message : error,
+    );
+    return null;
+  }
+}
+
+let nextFallbackSourceId = 0;
+const liveFallbackSources = new Set<string>();
+
+function createKimiGlobalFallbackSourceId(): string {
+  nextFallbackSourceId += 1;
+  return `${KIMI_GLOBAL_FALLBACK_SOURCE_ID}:${nextFallbackSourceId}`;
+}
+
+async function registerKimiGlobalApiFallback(sourceId: string): Promise<void> {
+  if (!liveFallbackSources.has(sourceId)) return;
+  const registry = await loadPiAiApiRegistry("register");
+  if (!registry) return;
+  for (const api of KIMI_FALLBACK_APIS) {
+    // Never displace an entry someone else owns: this is a shared,
+    // process-wide table and the fallback only exists to fill a hole, not to
+    // win a conflict. pi-ai installs its own builtins under the same rule.
+    if (registry.getApiProvider(api)) continue;
+    registry.registerApiProvider(
+      { api, stream: streamSimpleKimi, streamSimple: streamSimpleKimi },
+      sourceId,
+    );
+  }
+}
+
+// The registry outlives each session. Remove only the entries owned by the
+// retiring runtime, then hand any holes to another live runtime.
+async function unregisterKimiGlobalApiFallback(sourceId: string): Promise<void> {
+  if (!liveFallbackSources.delete(sourceId)) return;
+  const registry = await loadPiAiApiRegistry("unregister");
+  if (!registry) return;
+  registry.unregisterApiProviders(sourceId);
+  const successor = liveFallbackSources.values().next().value;
+  if (successor) await registerKimiGlobalApiFallback(successor);
+}
+
+async function registerKimiProvider(pi: ExtensionAPI, state: KimiRuntimeState): Promise<void> {
+  await registerKimiGlobalApiFallback(state.fallbackSourceId);
   pi.registerProvider(PROVIDER_ID, {
     baseUrl: getBaseUrl(state.config.protocol),
     apiKey: "$KIMI_API_KEY",
@@ -481,6 +588,50 @@ function registerKimiProvider(pi: ExtensionAPI, state: KimiRuntimeState): void {
   });
 }
 
+// What pi throws from any `pi` method once the extension runtime behind it has
+// been retired, which is what a /reload does. Same wording on every version
+// this extension supports (0.78.1 through 0.82.0); if it ever changes, the
+// worst case is that a reload race gets logged instead of ignored.
+const STALE_EXTENSION_RUNTIME_PREFIX = "This extension ctx is stale";
+
+let pendingModelDiscovery: Promise<void> = Promise.resolve();
+
+/**
+ * Resolves once the discovery started by the most recent extension load has
+ * settled. Nothing in the runtime waits for it; it exists so tests can observe
+ * the deferred registration without polling.
+ */
+export function kimiModelDiscoverySettled(): Promise<void> {
+  return pendingModelDiscovery;
+}
+
+// pi's extension loader awaits this factory before it builds the session, and
+// the TUI only draws its first frame after that returns, so a network round
+// trip here is a stall the user sees on every launch and every /reload. The
+// stored OAuth credential already carries the last known catalog (pi replays it
+// through oauth.modifyModels), so register what the config describes right away
+// and fold the fresh metadata in when it lands.
+function startModelDiscovery(pi: ExtensionAPI, state: KimiRuntimeState): void {
+  pendingModelDiscovery = discoverModelExtras(state)
+    .then((discovered) => {
+      if (!discovered) return;
+      reloadEffectiveKimiRuntimeConfig(state, state.cwd, state.projectTrusted);
+      return registerKimiProvider(pi, state);
+    })
+    .catch((error: unknown) => {
+      const message = error instanceof Error ? error.message : String(error);
+      // A /reload retires this extension runtime while discovery may still be
+      // in flight, and registering against a retired runtime throws. The
+      // reloaded factory runs its own discovery, so there is nothing to redo.
+      if (message.startsWith(STALE_EXTENSION_RUNTIME_PREFIX)) return;
+      // Anything else used to surface as an extension load failure, back when
+      // this ran inside the factory. Deferring it must not make it invisible:
+      // the provider stays registered with the metadata it already had, and
+      // the user needs to know why it stopped refreshing.
+      console.error("[kimi-coding] deferred model discovery failed:", message);
+    });
+}
+
 export function KimiCode(overrides?: KimiCodeConfigPatch): ExtensionFactory {
   return async (pi: ExtensionAPI) => {
     const cwd = process.cwd();
@@ -488,28 +639,22 @@ export function KimiCode(overrides?: KimiCodeConfigPatch): ExtensionFactory {
       { cwd, home: os.homedir(), includeProject: false },
       overrides,
     );
-    const discoveryToken = getKimiUsageToken();
-    const initialDiscovery = discoveryToken
-      ? await discoverKimiModelMetadata(discoveryToken, config.protocol)
-      : {};
-    let discovered = initialDiscovery;
-    const refreshedToken = getKimiUsageToken();
-    if (
-      Object.keys(discovered).length === 0 &&
-      refreshedToken &&
-      refreshedToken !== discoveryToken
-    ) {
-      discovered = await discoverKimiModelMetadata(refreshedToken, config.protocol);
-    }
     const state: KimiRuntimeState = {
       cwd,
       config,
-      modelExtras: discovered,
+      fallbackSourceId: createKimiGlobalFallbackSourceId(),
+      modelExtras: {},
       projectTrusted: false,
       overrides,
     };
     reloadEffectiveKimiRuntimeConfig(state, cwd, false);
-    registerKimiProvider(pi, state);
+    liveFallbackSources.add(state.fallbackSourceId);
+    try {
+      await registerKimiProvider(pi, state);
+    } catch (error) {
+      liveFallbackSources.delete(state.fallbackSourceId);
+      throw error;
+    }
 
     registerConfiguredMoonshotTools(pi, state.config, { updateActiveTools: false });
 
@@ -519,7 +664,11 @@ export function KimiCode(overrides?: KimiCodeConfigPatch): ExtensionFactory {
         updateActiveTools: true,
         projectTrusted,
       });
-      registerKimiProvider(pi, state);
+      await registerKimiProvider(pi, state);
+    });
+
+    pi.on("session_shutdown", async () => {
+      await unregisterKimiGlobalApiFallback(state.fallbackSourceId);
     });
 
     pi.registerCommand("kimi-settings", {
@@ -532,6 +681,8 @@ export function KimiCode(overrides?: KimiCodeConfigPatch): ExtensionFactory {
         await openSettingsMenu(pi, ctx, state);
       },
     });
+
+    startModelDiscovery(pi, state);
   };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-provider-kimi-code",
-  "version": "0.6.8",
-  "description": "Use Kimi Code in Pi without losing the Kimi-specific bits",
+  "version": "0.6.9",
+  "description": "Kimi Code harness extension for Pi: shared login state, file uploads, and Kimi-native tools",
   "keywords": [
     "ai-provider",
     "coding-agent",
@@ -53,9 +53,9 @@
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.9",
-    "@earendil-works/pi-coding-agent": "^0.80.9",
-    "@earendil-works/pi-tui": "^0.80.9",
+    "@earendil-works/pi-ai": "^0.82.0",
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
     "@j178/prek": "^0.4.4",
     "@types/node": "^24.0.0",
     "@types/proper-lockfile": "^4.1.4",

package/src/constants.ts

@@ -41,12 +41,12 @@ export function getDefaultBaseUrl(protocol: KimiWireProtocol): string {
 
 export const DEFAULT_BASE_URL = getDefaultBaseUrl(ENV_KIMI_CODE_PROTOCOL);
 
-export const PROVIDER_VERSION = "0.6.8";
+export const PROVIDER_VERSION = "0.6.9";
 
 // Upstream kimi-code CLI version — used in User-Agent and X-Msh-Version
 // headers to match the official client's identity. Update this when
 // syncing with https://github.com/MoonshotAI/kimi-code.
-export const KIMI_UPSTREAM_VERSION = "0.28.0";
+export const KIMI_UPSTREAM_VERSION = "0.29.1";
 export const KIMI_CODE_USER_AGENT = `kimi-code-cli/${KIMI_UPSTREAM_VERSION}`;
 export const KIMI_PLATFORM = "kimi_code_cli";
 
@@ -63,6 +63,10 @@ export const RETRYABLE_REFRESH_STATUSES = new Set([429, 500, 502, 503, 504]);
 
 export const PROVIDER_ID = "kimi-coding";
 
+// Owner tag for the entries this extension adds to pi-ai's global api-provider
+// registry, so they can be identified and removed as a group.
+export const KIMI_GLOBAL_FALLBACK_SOURCE_ID = "pi-provider-kimi-code-global-fallback";
+
 export function getOAuthHost(): string {
   const value =
     process.env.KIMI_CODE_OAUTH_HOST || process.env.KIMI_OAUTH_HOST || DEFAULT_OAUTH_HOST;

package/src/device.ts

@@ -1,10 +1,10 @@
 // Device identification: device-id persistence, Kimi Code-compatible request
 // headers, and the cross-platform device-model string. Pure helpers live near
-// the side-effecting one-shots (file IO, exec) they support.
+// the side-effecting one-shots (file IO) they support.
 
-import { execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import os from "node:os";
 import { dirname } from "node:path";
 
@@ -97,25 +97,68 @@ export function computeDeviceModel(input: DeviceModelInput): string {
   return `${system} ${arch}`.trim();
 }
 
-function macOsProductVersion(): string | undefined {
-  try {
-    const version = execFileSync("/usr/bin/sw_vers", ["-productVersion"], {
-      encoding: "utf-8",
-      timeout: 1000,
-    }).trim();
-    return version.length > 0 ? version : undefined;
-  } catch {
-    return undefined;
-  }
+// Where macOS keeps its product version. Upstream Kimi Code reads it through
+// Python's platform.mac_ver(), which parses this same file, so it is the same
+// source of truth as `sw_vers -productVersion` without the process spawn: a
+// spawn costs ~10ms of blocked event loop, and pi pays it again on every
+// /reload because it re-evaluates extension modules.
+const MAC_PRODUCT_VERSION_PATH = "/System/Library/CoreServices/SystemVersion.plist";
+
+// Exposed for tests. The plist is a flat XML property list, so the version sits
+// in the <string> immediately after the ProductVersion key.
+export function parseMacProductVersion(plist: string): string | undefined {
+  const match = /<key>ProductVersion<\/key>\s*<string>([^<]*)<\/string>/.exec(plist);
+  return match?.[1].trim() || undefined;
 }
 
-function getDeviceModel(): string {
-  return computeDeviceModel({
+let DEVICE_MODEL: string | undefined;
+
+function setDeviceModel(macVersion: string | undefined): string {
+  DEVICE_MODEL ??= computeDeviceModel({
     platform: process.platform,
     release: os.release(),
     arch: os.machine() || process.arch,
-    macVersion: process.platform === "darwin" ? macOsProductVersion() : undefined,
+    macVersion,
   });
+  return DEVICE_MODEL;
+}
+
+async function loadMacDeviceModel(): Promise<void> {
+  try {
+    setDeviceModel(parseMacProductVersion(await readFile(MAC_PRODUCT_VERSION_PATH, "utf-8")));
+  } catch {
+    setDeviceModel(undefined);
+  }
+}
+
+/**
+ * Settles once the module-load lookup has produced a device model. Nothing in
+ * the provider waits for it — headers stay synchronous — but tests use it to
+ * exercise the async path without racing the fallback below.
+ */
+export const deviceModelReady: Promise<void> = (() => {
+  if (process.platform !== "darwin") {
+    // Nothing to read: every other platform derives the model from os.release().
+    setDeviceModel(undefined);
+    return Promise.resolve();
+  }
+  // Read the version off the event loop at module load so the value is usually
+  // in place before anything asks for a header.
+  return loadMacDeviceModel();
+})();
+
+function getDeviceModel(): string {
+  if (DEVICE_MODEL !== undefined) return DEVICE_MODEL;
+  // A header was needed before the async read landed. Read the same file
+  // synchronously rather than reporting the kernel release, which would put a
+  // different device model on the wire than every later request. This costs
+  // ~0.02ms against the ~10ms a `sw_vers` subprocess used to cost, and both
+  // paths memoize into the same slot.
+  try {
+    return setDeviceModel(parseMacProductVersion(readFileSync(MAC_PRODUCT_VERSION_PATH, "utf-8")));
+  } catch {
+    return setDeviceModel(undefined);
+  }
 }
 
 export function getOsVersion(): string {
@@ -133,7 +176,6 @@ export function asciiHeaderValue(value: string, fallback = "unknown"): string {
   return sanitized || fallback;
 }
 
-const DEVICE_MODEL = getDeviceModel();
 let DEVICE_ID: string | null = null;
 
 function getStableDeviceId(): string {
@@ -174,7 +216,7 @@ export function getCommonHeaders(): Record<string, string> {
     "X-Msh-Platform": KIMI_PLATFORM,
     "X-Msh-Version": KIMI_UPSTREAM_VERSION,
     "X-Msh-Device-Name": os.hostname(),
-    "X-Msh-Device-Model": DEVICE_MODEL,
+    "X-Msh-Device-Model": getDeviceModel(),
     "X-Msh-Os-Version": getOsVersion(),
     "X-Msh-Device-Id": getStableDeviceId(),
   };

package/src/models.ts

@@ -8,6 +8,7 @@ import type {
   ModelConfig,
   ModelReasoningMap,
 } from "./config.ts";
+import { DEFAULT_KIMI_CODE_CONFIG } from "./config.ts";
 
 import { type KimiWireProtocol, getBaseUrl } from "./constants.ts";
 import { getKimiProviderHeaders } from "./device.ts";
@@ -36,6 +37,10 @@ const DEFAULT_DISCOVERY_TIMEOUT_MS = 2500;
 
 export interface DiscoverKimiModelMetadataOptions {
   timeoutMs?: number;
+  // 401 recovery for runtime callers (extension startup, settings menu).
+  // oauth.ts's login/refresh flows must NOT pass this: they call discovery
+  // while holding the OAuth lock, and refreshKimiAuthToken would re-enter it.
+  refreshAccessToken?: (currentToken: string) => Promise<string | null>;
 }
 
 function mergeInputModalities(
@@ -84,6 +89,36 @@ function resolveModelCost(
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
 }
 
+// Policy: a model's output cap tracks its context window unless the user
+// explicitly configured model.maxTokens. pi-ai clamps the request cap to
+// contextWindow - used - 4096 (clampMaxTokensToContext in
+// @earendil-works/pi-ai), so setting maxTokens to the window yields the official
+// kimi-code behavior (computeCompletionBudgetCap: maxCtx, clamped to
+// maxCtx - usedContext) instead of a fixed small cap that truncates long
+// max-effort reasoning (reasoning_content counts toward the cap). A deliberate
+// per-request cap still wins (options.maxTokens ?? model.maxTokens). Reconcile
+// wherever contextWindow is authored so the two stay in lockstep.
+//
+// "Explicitly configured" means any value other than the built-in default:
+// ensureKimiCodeConfig materializes the full default config (including
+// maxTokens) into the home config file, so config-source tracking cannot
+// distinguish a deliberate 32000 from a materialized default. A user who
+// explicitly sets the default value gets the window cap — indistinguishable
+// from the materialized-default case, and the intended new behavior anyway.
+const DEFAULT_MODEL_MAX_TOKENS = DEFAULT_KIMI_CODE_CONFIG.model.maxTokens;
+
+// True while the cap is "unset": still the built-in default, or already
+// tracking the context window (set by an earlier withWindowCappedMaxTokens
+// call, before discovery grew the window).
+function isWindowTrackedMaxTokens(model: Model<Api>): boolean {
+  return model.maxTokens === DEFAULT_MODEL_MAX_TOKENS || model.maxTokens === model.contextWindow;
+}
+
+function withWindowCappedMaxTokens<M extends Model<Api>>(model: M): M {
+  if (!isWindowTrackedMaxTokens(model)) return model;
+  return { ...model, maxTokens: model.contextWindow };
+}
+
 export function buildKimiModelFromConfig(
   config: ModelConfig,
   modelId = KIMI_CODING_MODEL_ID,
@@ -97,7 +132,7 @@ export function buildKimiModelFromConfig(
         : modelId === KIMI_CODING_MODEL_ID
           ? "Kimi for Coding"
           : modelId;
-  return {
+  return withWindowCappedMaxTokens({
     id: modelId,
     name,
     reasoning: config.reasoning,
@@ -105,7 +140,7 @@ export function buildKimiModelFromConfig(
     cost: { ...resolveModelCost(modelId) },
     contextWindow: config.contextWindow,
     maxTokens: config.maxTokens,
-  } as Model<Api>;
+  } as Model<Api>);
 }
 
 export function resolveKimiModelConfig(
@@ -225,15 +260,30 @@ export async function discoverKimiModelMetadata(
   const controller = new AbortController();
   const timeout =
     timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs).unref() : undefined;
-  try {
-    const response = await fetch(modelsUrl, {
-      signal: controller.signal,
+  const requestModels = (token: string, signal: AbortSignal) =>
+    fetch(modelsUrl, {
+      signal,
       headers: {
         ...getKimiProviderHeaders(),
-        Authorization: `Bearer ${accessToken}`,
+        Authorization: `Bearer ${token}`,
         Accept: "application/json",
       },
     });
+  try {
+    let response = await requestModels(accessToken, controller.signal);
+    if (response.status === 401 && options.refreshAccessToken) {
+      const refreshed = await options.refreshAccessToken(accessToken);
+      if (refreshed && refreshed !== accessToken) {
+        const retryController = new AbortController();
+        const retryTimeout =
+          timeoutMs > 0 ? setTimeout(() => retryController.abort(), timeoutMs).unref() : undefined;
+        try {
+          response = await requestModels(refreshed, retryController.signal);
+        } finally {
+          if (retryTimeout) clearTimeout(retryTimeout);
+        }
+      }
+    }
     if (!response.ok) return {};
     const json = (await response.json()) as { data?: unknown };
     const list = Array.isArray(json.data) ? (json.data as KimiServerModel[]) : [];
@@ -306,6 +356,9 @@ export function applyKimiOAuthExtrasToModel(
   extras: KimiModelMetadata,
   reasoningMap?: ModelReasoningMap,
 ): Model<Api> {
+  // Capture before extras grow the window: a window-tracked cap must follow
+  // the new window, an explicit cap must survive unchanged.
+  const windowTracked = isWindowTrackedMaxTokens(model);
   const next: Model<Api> & {
     wireModelId?: string;
     supportsThinkingType?: "only" | "no" | "both";
@@ -347,5 +400,7 @@ export function applyKimiOAuthExtrasToModel(
     if (thinkingLevelMap) next.thinkingLevelMap = thinkingLevelMap;
     else delete next.thinkingLevelMap;
   }
+  // Reconcile the output cap with the (possibly discovery-updated) window.
+  if (windowTracked) next.maxTokens = next.contextWindow;
   return next;
 }

package/src/oauth.ts

@@ -658,7 +658,13 @@ export function isKimiAuthErrorMessage(message: unknown): boolean {
     /\b401\b/.test(text) ||
     text.includes("unauthorized") ||
     text.includes("incorrect api key") ||
-    text.includes("invalid api key")
+    text.includes("invalid api key") ||
+    // Kimi's production 401 body: "The API Key appears to be invalid or may
+    // have expired..." with type "invalid_authentication_error". Neither
+    // contains the substrings above, so without these the digit fallback is
+    // the only match and vanishes when a transport strips the status prefix.
+    text.includes("api key appears to be invalid") ||
+    text.includes("invalid_authentication_error")
   );
 }
 

package/src/payload.ts

@@ -2,11 +2,14 @@
 // per-protocol message transforms, OpenAI tool-call / tool-schema normalizers,
 // and the top-level applyKimiPayloadMutations that orchestrates them.
 
+import { createHash } from "node:crypto";
+
 import type { CacheRetention, ThinkingLevel } from "@earendil-works/pi-ai";
 import type { KimiResolvedModelConfig, ModelReasoningEntry } from "./config.ts";
 
 import { getBaseUrl } from "./constants.ts";
 import { getKimiProviderHeaders } from "./device.ts";
+import { refreshKimiAuthToken } from "./oauth.ts";
 import { optimizeToolSchemas } from "./schema-dedup.ts";
 
 // =============================================================================
@@ -30,6 +33,7 @@ export function resolveCacheRetention(value?: CacheRetention): CacheRetention {
 export interface KimiPayloadContext {
   api: "anthropic-messages" | "openai-completions";
   upload?: Uploader;
+  uploadCacheScope?: string;
   cacheKey?: string;
   cacheRetention: CacheRetention;
   reasoning?: ThinkingLevel;
@@ -80,6 +84,16 @@ function getUploadFilename(mimeType: string): string {
     "image/png": "upload.png",
     "image/gif": "upload.gif",
     "image/webp": "upload.webp",
+    // Video extensions mirror upstream kimi-code's MIME_TO_EXT
+    // (packages/kosong/src/providers/kimi-files.ts).
+    "video/mp4": "upload.mp4",
+    "video/mpeg": "upload.mpeg",
+    "video/quicktime": "upload.mov",
+    "video/webm": "upload.webm",
+    "video/x-matroska": "upload.mkv",
+    "video/x-msvideo": "upload.avi",
+    "video/x-flv": "upload.flv",
+    "video/3gpp": "upload.3gp",
   };
   return map[mimeType] ?? "upload.bin";
 }
@@ -88,22 +102,34 @@ function getUploadFilename(mimeType: string): string {
 // File upload (I/O edge)
 // =============================================================================
 
+export interface UploadKimiFileDeps {
+  fetch?: typeof fetch;
+  refreshAccessToken?: (currentToken: string) => Promise<string | null>;
+}
+
 export async function uploadKimiFile(
   apiKey: string,
   mimeType: string,
   data: string,
   thresholdBytes?: number,
+  deps?: UploadKimiFileDeps,
 ): Promise<string | null> {
+  const fetchImpl = deps?.fetch ?? fetch;
+  const refreshAccessToken = deps?.refreshAccessToken ?? refreshKimiAuthToken;
   const buffer = Buffer.from(data, "base64");
-  if (!mimeType.startsWith("image/")) return null;
+  const isVideo = mimeType.startsWith("video/");
+  if (!mimeType.startsWith("image/") && !isVideo) return null;
   const threshold =
     thresholdBytes ?? parseInlineUploadThreshold(process.env.KIMI_CODE_UPLOAD_THRESHOLD_BYTES);
-  if (buffer.length <= threshold) return null;
+  // The inline threshold applies to images only: the Kimi API has no inline
+  // video path (upstream kimi-code uploads every video via /files), so videos
+  // always upload.
+  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", "image");
+  formData.append("purpose", isVideo ? "video" : "image");
 
   const uploadUrl = `${deriveFilesBaseUrl(getBaseUrl())}/files`;
   const debug = process.env.KIMI_CODE_DEBUG === "1";
@@ -113,13 +139,31 @@ export async function uploadKimiFile(
     );
   }
 
-  try {
-    const response = await fetch(uploadUrl, {
+  const postUpload = (token: string) =>
+    fetchImpl(uploadUrl, {
       method: "POST",
-      headers: { ...getKimiProviderHeaders(), Authorization: `Bearer ${apiKey}` },
+      headers: { ...getKimiProviderHeaders(), Authorization: `Bearer ${token}` },
       body: formData,
     });
-    if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
+
+  try {
+    let response = await postUpload(apiKey);
+    // Kimi access tokens are short-lived and invalidated server-side as soon
+    // as any peer process rotates them, so a 401 here usually means our key
+    // snapshot went stale mid-session, not that login is broken. Mirror the
+    // chat-stream recovery: force one refresh and retry once.
+    let responseText: string | undefined;
+    if (response.status === 401) {
+      responseText = await response.text();
+      const refreshed = await refreshAccessToken(apiKey);
+      if (refreshed && refreshed !== apiKey) {
+        console.error("[kimi-coding] upload got 401, retrying with refreshed token");
+        response = await postUpload(refreshed);
+        responseText = undefined;
+      }
+    }
+    if (!response.ok)
+      throw new Error(`${response.status} ${responseText ?? (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}`;
@@ -132,24 +176,69 @@ export async function uploadKimiFile(
 }
 
 // =============================================================================
-// Payload file transformers (pure given an Uploader)
+// Payload file transformers
 //
 // These walk the provider-specific payload shape and replace inline base64
 // image 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.
+//
+// Successful uploads are remembered in a module-level cache shared across
+// requests: payloads are rebuilt from session context every request, so
+// without it a conversation's images would re-upload on every turn. Keys are
+// content hashes rather than the data URLs themselves so the cache does not
+// retain every image's base64 payload in memory. Failures are not cached and
+// retry on the next request.
 // =============================================================================
 
-async function transformOpenAIPayloadFiles(payload: JsonRecord, upload: Uploader): Promise<void> {
+const MAX_UPLOADED_FILE_CACHE_ENTRIES = 512;
+const uploadedFileCache = new Map<string, string>();
+
+function uploadedFileCacheKey(cacheScope: string, mimeType: string, data: string): string {
+  return createHash("sha256")
+    .update(cacheScope)
+    .update("\0")
+    .update(mimeType)
+    .update("\0")
+    .update(data)
+    .digest("hex");
+}
+
+function rememberUploadedFile(
+  uploadCache: Map<string, string>,
+  cacheKey: string,
+  url: string,
+): void {
+  if (
+    uploadCache === uploadedFileCache &&
+    !uploadCache.has(cacheKey) &&
+    uploadCache.size >= MAX_UPLOADED_FILE_CACHE_ENTRIES
+  ) {
+    const oldest = uploadCache.keys().next().value;
+    if (oldest !== undefined) uploadCache.delete(oldest);
+  }
+  uploadCache.set(cacheKey, url);
+}
+
+export function clearKimiUploadedFileCache(): void {
+  uploadedFileCache.clear();
+}
+
+async function transformOpenAIPayloadFiles(
+  payload: JsonRecord,
+  upload: Uploader,
+  uploadCache: Map<string, string>,
+  uploadCacheScope: string,
+): 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" : null;
+      const key =
+        block.type === "image_url" ? "image_url" : block.type === "video_url" ? "video_url" : null;
       if (!key) continue;
 
       const field = block[key];
@@ -164,9 +253,10 @@ async function transformOpenAIPayloadFiles(payload: JsonRecord, upload: Uploader
       const parsed = parseDataUrl(urlValue);
       if (!parsed) continue;
 
-      const uploaded = cache.get(urlValue) ?? (await upload(parsed.mimeType, parsed.data));
+      const cacheKey = uploadedFileCacheKey(uploadCacheScope, parsed.mimeType, parsed.data);
+      const uploaded = uploadCache.get(cacheKey) ?? (await upload(parsed.mimeType, parsed.data));
       if (!uploaded) continue;
-      cache.set(urlValue, uploaded);
+      rememberUploadedFile(uploadCache, cacheKey, uploaded);
 
       block[key] =
         typeof field === "string" ? uploaded : { ...(field as JsonRecord), url: uploaded };
@@ -330,9 +420,10 @@ function normalizeOpenAIToolSchemas(payload: JsonRecord): void {
 async function transformAnthropicPayloadFiles(
   payload: JsonRecord,
   upload: Uploader,
+  uploadCache: Map<string, string>,
+  uploadCacheScope: string,
 ): 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;
@@ -342,10 +433,10 @@ async function transformAnthropicPayloadFiles(
     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));
+    const cacheKey = uploadedFileCacheKey(uploadCacheScope, mediaType, data);
+    const uploaded = uploadCache.get(cacheKey) ?? (await upload(mediaType, data));
     if (!uploaded) return block;
-    cache.set(cacheKey, uploaded);
+    rememberUploadedFile(uploadCache, cacheKey, uploaded);
 
     const next: JsonRecord = { type: "image", source: { type: "url", url: uploaded } };
     if (block.cache_control !== undefined) next.cache_control = block.cache_control;
@@ -390,10 +481,12 @@ export async function applyKimiPayloadMutations(
 
   // 2. File upload dispatch (protocol-specific).
   if (ctx.upload) {
+    const uploadCache = ctx.uploadCacheScope ? uploadedFileCache : new Map<string, string>();
+    const uploadCacheScope = ctx.uploadCacheScope ?? "request";
     if (ctx.api === "openai-completions") {
-      await transformOpenAIPayloadFiles(payload, ctx.upload);
+      await transformOpenAIPayloadFiles(payload, ctx.upload, uploadCache, uploadCacheScope);
     } else if (ctx.api === "anthropic-messages") {
-      await transformAnthropicPayloadFiles(payload, ctx.upload);
+      await transformAnthropicPayloadFiles(payload, ctx.upload, uploadCache, uploadCacheScope);
     }
   }
   if (ctx.api === "openai-completions") {
@@ -447,8 +540,17 @@ export async function applyKimiPayloadMutations(
   }
 
   const generation = ctx.modelConfig.generation;
+  // Official kimi-code sends temperature/top_p only when explicitly configured
+  // (env KIMI_MODEL_TEMPERATURE / KIMI_MODEL_TOP_P → generation.*); otherwise it
+  // omits them and lets the server apply its own defaults. Mirror that exactly:
+  // drop any value pi-ai seeded by default when the user hasn't configured one
+  // (the official client does not pin these to 1.0 / 0.95).
   if (generation.temperature !== undefined) payload.temperature = generation.temperature;
+  else delete payload.temperature;
   if (generation.topP !== undefined) payload.top_p = generation.topP;
+  else delete payload.top_p;
+  // Output cap: an explicit cap (KIMI_MODEL_MAX_COMPLETION_TOKENS / config →
+  // generation.maxCompletionTokens) is honored as a hardCap on the request value.
   if (generation.maxCompletionTokens !== undefined) {
     const maxTokensKey = ctx.api === "anthropic-messages" ? "max_tokens" : "max_completion_tokens";
     const currentMaxTokens = payload[maxTokensKey];
@@ -469,22 +571,39 @@ export async function applyKimiPayloadMutations(
     const mapped = resolveReasoningForLevel(resolvedReasoning, ctx.modelConfig);
     if (mapped) {
       const oldThinking = isRecord(payload.thinking) ? payload.thinking : {};
-      const thinking: JsonRecord = {
-        ...oldThinking,
-        type: mapped.enabled ? "enabled" : "disabled",
-      };
-      delete thinking.effort;
-      if (!mapped.enabled) delete thinking.keep;
       const effort = ctx.reasoning
         ? mapped.effort
         : (ctx.modelConfig.defaultEffort ?? mapped.effort);
-      if (mapped.enabled && effort !== null && ctx.modelConfig.supportEfforts?.includes(effort)) {
-        thinking.effort = effort;
-      }
-      if (mapped.enabled && ctx.modelConfig.thinkingKeep) {
-        thinking.keep = ctx.modelConfig.thinkingKeep;
+      const effortSupported =
+        effort !== null && ctx.modelConfig.supportEfforts?.includes(effort) === true;
+      if (ctx.api === "anthropic-messages" && oldThinking.type === "adaptive") {
+        // pi-ai >=0.82 builds adaptive thinking for models carrying
+        // compat.forceAdaptiveThinking (streamSimpleKimi sets it on the
+        // anthropic runtime model). Keep the adaptive shape — effort lives in
+        // top-level output_config there, not inside thinking — and only
+        // replace it with an explicit disable when the level maps to off.
+        if (mapped.enabled) {
+          if (effortSupported) payload.output_config = { effort };
+          else delete payload.output_config;
+        } else {
+          payload.thinking = { type: "disabled" };
+          delete payload.output_config;
+        }
+      } else {
+        const thinking: JsonRecord = {
+          ...oldThinking,
+          type: mapped.enabled ? "enabled" : "disabled",
+        };
+        delete thinking.effort;
+        if (!mapped.enabled) delete thinking.keep;
+        if (mapped.enabled && effortSupported) {
+          thinking.effort = effort;
+        }
+        if (mapped.enabled && ctx.modelConfig.thinkingKeep) {
+          thinking.keep = ctx.modelConfig.thinkingKeep;
+        }
+        payload.thinking = thinking;
       }
-      payload.thinking = thinking;
     }
   }
 
@@ -510,15 +629,10 @@ export async function applyKimiPayloadMutations(
     }
   }
 
-  // 8. K2.7 Code API constraints: the server rejects non-default values for
-  //    temperature (must be 1.0) and top_p (must be 0.95), and tool_choice
-  //    "required" / function-specific when thinking is enabled (always-on).
-  if (payload.temperature !== undefined && payload.temperature !== 1) {
-    delete payload.temperature;
-  }
-  if (payload.top_p !== undefined && payload.top_p !== 0.95) {
-    delete payload.top_p;
-  }
+  // 8. K2.7 Code API constraints: the server rejects tool_choice "required" /
+  //    function-specific when thinking is enabled (always-on). temperature/top_p
+  //    are handled in step 6 — omitted unless explicitly configured, matching the
+  //    official kimi-code client rather than pinned to 1.0/0.95.
   if (payload.tool_choice !== undefined) {
     const tc = payload.tool_choice;
     const isAllowed =

package/src/stream.ts

@@ -58,9 +58,13 @@ import {
   type KimiResolvedModelConfig,
 } from "./config.ts";
 
-import { ENV_KIMI_CODE_PROTOCOL, getApiProtocol, getBaseUrl } from "./constants.ts";
+import { ENV_KIMI_CODE_PROTOCOL, PROVIDER_ID, getApiProtocol, getBaseUrl } from "./constants.ts";
 import { getKimiProviderHeaders } from "./device.ts";
-import { isKimiAuthErrorMessage, refreshKimiAuthToken } from "./oauth.ts";
+import {
+  isKimiAuthErrorMessage,
+  readStoredOAuthCredential,
+  refreshKimiAuthToken,
+} from "./oauth.ts";
 import {
   type Uploader,
   applyKimiPayloadMutations,
@@ -190,11 +194,21 @@ export async function* filterEmptyResponseStream(
 
 const KIMI_API_KEY_ENV_REFERENCES = new Set(["$KIMI_API_KEY", "${KIMI_API_KEY}"]);
 
+// On the normal request path pi resolves the provider credential through its
+// ModelRuntime and hands it to us. Callers that arrive through pi-ai's global
+// api registry (a bare agentLoop() with no streamFn) have no ModelRuntime
+// behind them and pass nothing, so read the same credential store pi itself
+// would have read instead of sending an unauthenticated request. Kept last so
+// an explicit key and the environment override keep their existing precedence.
+function getStoredKimiAccessToken(): string {
+  return readStoredOAuthCredential(PROVIDER_ID)?.access?.trim() || "";
+}
+
 export function resolveKimiApiKey(apiKey: string | undefined): string {
   if (apiKey !== undefined && KIMI_API_KEY_ENV_REFERENCES.has(apiKey)) {
-    return process.env.KIMI_API_KEY?.trim() || "";
+    return process.env.KIMI_API_KEY?.trim() || getStoredKimiAccessToken();
   }
-  return apiKey || process.env.KIMI_API_KEY || "";
+  return apiKey || process.env.KIMI_API_KEY || getStoredKimiAccessToken();
 }
 
 // SimpleStreamOptions.headers is Record<string, string> on pi <=0.79 and
@@ -285,6 +299,7 @@ export function streamSimpleKimi(
           await applyKimiPayloadMutations(nextPayload, {
             api: apiProtocol,
             upload,
+            uploadCacheScope: apiKey ? `${getBaseUrl(wireProtocol)}:${apiKey}` : undefined,
             cacheKey,
             cacheRetention,
             reasoning: options?.reasoning,
@@ -323,6 +338,19 @@ export function streamSimpleKimi(
         ...model,
         api: apiProtocol,
         baseUrl: getBaseUrl(wireProtocol),
+        // Kimi's anthropic-protocol endpoint speaks adaptive thinking and
+        // rejects/ignores the interleaved-thinking beta header; pi-ai >=0.82
+        // keys both behaviors off these compat flags (its own built-in
+        // kimi-coding models carry them in generated metadata).
+        ...(wireProtocol === "anthropic"
+          ? {
+              compat: {
+                ...(model as { compat?: Record<string, unknown> }).compat,
+                forceAdaptiveThinking: true,
+                allowEmptySignature: true,
+              },
+            }
+          : {}),
       } as Model<Api>;
       const upstream =
         wireProtocol === "openai"