pi-provider-kimi-code 0.3.2 → 0.4.0

package/README.md

@@ -1,42 +1,33 @@
 # Pi extension for Kimi Code
+
 [![npm](https://img.shields.io/npm/v/pi-provider-kimi-code)](https://www.npmjs.com/package/pi-provider-kimi-code)
 [![license](https://img.shields.io/npm/l/pi-provider-kimi-code)](./LICENSE)
 
-**Use Kimi Code in Pi without losing the Kimi-specific bits.**
+**Use Kimi Code in Pi, with the Kimi parts handled.**
 
-Pi gives you the harness and extension ecosystem. Kimi CLI gives you the official Kimi Code path. This package sits between them: Kimi Code as a Pi provider, plus the details the basic provider keeps simple — file uploads, cache behavior, session reuse, and a base for Kimi-native tools.
+Pi already has a basic `kimi-coding` provider. This extension is for the parts that start to matter once Kimi Code becomes part of your real Pi workflow: account login reuse, file uploads, measured cache behavior, live model metadata, and optional Moonshot search/fetch tools.
 
 ## Why this exists
 
-Pi already has a built-in `kimi-coding` provider (see [`pi.dev/docs/.../providers`](https://pi.dev/docs/latest/providers)). It is good basic support: point Pi at Kimi Code and start coding.
-
-This extension is for the next layer. If you are building real Pi workflows, the Kimi-specific details start to matter:
-
-- **Files should go through Kimi's Files API.** Large images are uploaded to `/files` and referenced as `ms://` IDs instead of being sent as huge inline base64 payloads.
-- **Cache behavior should be visible.** Kimi caches by content prefix, not by `prompt_cache_key`. This repo measures that behavior and keeps the provider aligned with it.
-- **Existing Kimi sessions should carry over.** If you already use `kimi-cli`, this extension can reuse that login instead of making you manage another API key.
-- **Protocol choice should stay available.** The default is OpenAI-compatible mode, but Anthropic-compatible mode is still there when your Pi setup needs it.
-
-> On prompt caching: the built-in provider works fine. Kimi's Coding endpoint caches by content prefix hash automatically — neither `cache_control` markers nor `prompt_cache_key` actually drive cache hits. See [docs/caching.md](docs/caching.md) for measurements.
-
-## Who is this for?
+Pi is a small harness you adapt to your own workflow. Kimi CLI is Moonshot's official Kimi Code path. This package sits between them: Kimi Code as a Pi provider, plus the Kimi-specific details that the basic provider keeps simple.
 
-- You use Pi as your coding harness and want Kimi Code inside that workflow.
-- You already use `kimi-cli`, but want Pi's extensions, skills, prompts, themes, and custom UI pieces around the same Kimi Code account.
-- You are building on top of Pi and need the Kimi-specific parts to behave predictably: uploads, cache behavior, model metadata, and protocol choice.
-
-Pay-per-token via `KIMI_API_KEY` still works if you just want to try Kimi in CI or without a subscription.
+- **Use your Kimi account.** Log in with `/login kimi-coding`, or reuse an existing `kimi-cli` session.
+- **Send files the Kimi way.** Large inline images go through Kimi's Files API and become `ms://` references instead of huge base64 payloads.
+- **Know what the cache is doing.** Kimi caches by content prefix. This repo measures that behavior instead of pretending `prompt_cache_key` controls it.
+- **Use the safer protocol by default.** OpenAI-compatible mode is the default because tool results are less ambiguous there. Anthropic-compatible mode is still available.
+- **Turn on Kimi-native tools when you want them.** `moonshot_search` and `moonshot_fetch` are opt-in, configurable per user or per project.
 
 ## What this package adds
 
-- **Kimi account login in Pi** — sign in with your Kimi Code account. `KIMI_API_KEY` still works for CI or pay-per-token use.
-- **`kimi-cli` session reuse** — if you already signed in with the official CLI, this extension can read `~/.kimi/credentials/kimi-code.json` and skip another browser login.
-- **Kimi Files API upload** — large images are uploaded to `/v1/files` and sent as `ms://` references instead of huge inline base64 payloads.
-- **Measured cache behavior** — Kimi's Coding endpoint caches by content prefix hash with TTL ≥ 5 minutes. This repo documents what changes the cache and what does not.
-- **Live model metadata** — name, context window, reasoning support, and image-input support refresh from Kimi's `/v1/models` endpoint at login / refresh time.
-- **Protocol choice** — OpenAI-compatible mode is the default. Anthropic-compatible mode is still available with `KIMI_CODE_PROTOCOL=anthropic`.
-- **Stream cleanup** — Kimi occasionally emits placeholder text during thinking-only responses; this extension hides those blocks before they reach the Pi UI.
-- **No build step** — Pi loads the TypeScript extension directly.
+- Kimi account login in Pi, plus `KIMI_API_KEY` for CI or pay-per-token use.
+- `kimi-cli` credential reuse from `~/.kimi/credentials/kimi-code.json`.
+- Kimi Files API uploads for large inline images.
+- Live model metadata from Kimi at login / refresh time.
+- OpenAI-compatible mode by default, Anthropic-compatible mode on request.
+- Kimi K2.6 reasoning level mapping for Pi's reasoning controls.
+- Stream cleanup for Kimi's thinking-only placeholder text.
+- Optional `moonshot_search` and `moonshot_fetch` tools via `/kimi-settings`.
+- No build step; Pi loads the TypeScript extension directly.
 
 ## Install
 
@@ -57,32 +48,29 @@ pi -e /path/to/pi-provider-kimi-code
 If you prefer not to use npm, download the tarball from the [latest release](https://github.com/Leechael/pi-provider-kimi-code/releases/latest), extract it, and install from the local path:
 
 ```bash
-# Download and extract
 curl -L https://github.com/Leechael/pi-provider-kimi-code/releases/latest/download/pi-provider-kimi-code.tar.gz | tar -xz -C /tmp
-
-# Install from the extracted directory
 pi install /tmp/pi-provider-kimi-code
 ```
 
 ## Sign in
 
-### Browser login
-
 Inside Pi, run:
 
-```
+```text
 /login kimi-coding
 ```
 
-A browser tab opens, you sign into your Kimi account, and credentials are stored at `~/.pi/agent/auth.json`. Tokens refresh automatically.
+A browser tab opens, you sign into your Kimi account, and Pi stores the credential at `~/.pi/agent/auth.json`. Tokens refresh automatically.
 
-### Already logged in via `kimi-cli`?
+If you already use `kimi-cli`, this extension can reuse its credential file:
 
-If `~/.kimi/credentials/kimi-code.json` exists, `/login kimi-coding` reads that file, refreshes the access token if needed, and finishes without opening a browser. The `kimi-cli` credential file is read-only from this extension's perspective — it is never overwritten. Set `KIMI_SHARE_DIR` to point at a non-default location.
+```text
+~/.kimi/credentials/kimi-code.json
+```
 
-### API key
+The file is read-only from this extension's side. Set `KIMI_SHARE_DIR` if your `kimi-cli` share directory lives somewhere else.
 
-For CI or pay-per-token use, set `KIMI_API_KEY`:
+For CI or pay-per-token use, set `KIMI_API_KEY` instead:
 
 ```bash
 KIMI_API_KEY=sk-... pi
@@ -92,13 +80,19 @@ KIMI_API_KEY=sk-... pi
 
 This provider publishes one Pi model ID:
 
-```
+```text
 kimi-coding/kimi-for-coding
 ```
 
-Kimi keeps the Coding model behind aliases, so this provider does not hardcode a long model list. When you log in or refresh your token, it asks Kimi for the current model info and updates what Pi sees. If your account is on a newer rollout or an internal test, Pi can pick up the latest model name and context size without waiting for this package to release.
+Select it inside Pi:
+
+```text
+/model kimi-coding/kimi-for-coding
+```
 
-The fallback values are:
+Kimi keeps Coding models behind aliases. Rather than hardcoding a stale model list, this extension asks Kimi for the current model info when you log in or refresh. If your account is on a newer rollout or internal test, Pi can pick up the latest model name and context size without waiting for a package release.
+
+Fallback values:
 
 - Context window: `262144` tokens
 - Max output: `32000` tokens
@@ -114,12 +108,45 @@ Kimi K2.6 supports Pi's reasoning levels. This provider maps them to Kimi's curr
 
 If Kimi reports a larger context window, the provider uses that value. You can also override the advertised context or model name with `KIMI_MODEL_MAX_CONTEXT_SIZE` / `KIMI_MODEL_NAME`; see [docs/ENV.md](docs/ENV.md).
 
-Select it inside Pi:
+## Optional Moonshot tools
+
+Kimi Coding has server-side search and fetch tools. This extension can expose them to Pi as:
+
+- `moonshot_search`
+- `moonshot_fetch`
 
+They are off by default. Turn them on when you want Kimi's own search/fetch path in the agent loop.
+
+Inside Pi, run:
+
+```text
+/kimi-settings
 ```
-/model kimi-coding/kimi-for-coding
+
+That command shows your current Kimi usage summary and lets you edit the home or project config. Changes apply to the active session tool set.
+
+Config files are JSON:
+
+- Home: `~/.pi/pi-provider-kimi-code.json`
+- Project override: `<cwd>/.pi/pi-provider-kimi-code.json`
+
+Project config overrides home config with a deep merge. Missing files or missing keys mean both tools stay off.
+
+```json
+{
+  "tools": {
+    "moonshot_search": { "enabled": true, "default_collapsed": true },
+    "moonshot_fetch": { "enabled": true, "default_collapsed": true }
+  }
+}
 ```
 
+Both tools require `/login kimi-coding` OAuth credentials. `KIMI_API_KEY` is not used for these tools. Your account also needs access to Moonshot's server-side search/fetch services; if not, the upstream service can return subscription or whitelist errors.
+
+`default_collapsed` controls only the TUI preview. The full tool result still goes to the model; set it to `false` if you want previews expanded by default.
+
+If you already use another search or fetch tool, pick one path for a session. Overlapping tools can make the model choose the wrong one.
+
 ## Common knobs
 
 Most users do not need environment variables. Two are worth knowing:
@@ -127,7 +154,9 @@ 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.
 
-The full list, including base URL overrides, `kimi-cli` path overrides, upload tuning, debug logs, and model metadata overrides, lives in [docs/ENV.md](docs/ENV.md).
+Moonshot search/fetch tools are configured through `/kimi-settings` or JSON config files, not env vars.
+
+The full env list, including base URL overrides, `kimi-cli` path overrides, upload tuning, debug logs, and model metadata overrides, lives in [docs/ENV.md](docs/ENV.md).
 
 ## Notes
 
@@ -170,12 +199,22 @@ Pi runs on Node's `fetch` / undici stack, which handles `http_proxy` / `https_pr
 
 ### `/login kimi-coding` prints a device code but the browser never opens
 
-The login flow always prints a verification URL — opening it is the terminal's job. If your terminal or OS blocks auto-open, copy the URL and paste it into a browser manually.
+The login flow always prints a verification URL. If your terminal or OS blocks auto-open, copy the URL and paste it into a browser manually.
 
 ### "Access denied" or subscription errors after a successful login
 
 Your Moonshot account needs an active Kimi Code subscription for the provider to do anything useful. If the same account works in `kimi-cli`, re-run `/login kimi-coding` to refresh credentials.
 
+### Moonshot tools do not show up
+
+Run `/kimi-settings` and check whether `moonshot_search` / `moonshot_fetch` are enabled in the home or project config. These tools also require `/login kimi-coding`; `KIMI_API_KEY` is not enough.
+
+If you changed the JSON config by hand, reload it through `/kimi-settings` or start a new Pi session.
+
+### Moonshot tools return subscription or whitelist errors
+
+The tools call Moonshot's server-side search/fetch services. Some accounts may not have access even with an active Kimi Code Plan. The error comes from the upstream service.
+
 ### Large images fail with a payload error
 
 This extension uploads images over `KIMI_CODE_UPLOAD_THRESHOLD_BYTES` (default 1 MB) to Kimi's Files API and references them as `ms://`. Set `KIMI_CODE_DEBUG=1` to see upload decisions in the provider logs.

package/index.ts

@@ -19,8 +19,24 @@
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  AuthStorage,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+import os from "node:os";
+import { relative } from "node:path";
 
+import {
+  type KimiCodeConfig,
+  getProjectKimiCodeConfigPath,
+  getGlobalKimiCodeConfigPath,
+  loadHomeKimiCodeConfig,
+  loadKimiCodeConfig,
+  loadProjectKimiCodeConfig,
+  saveHomeKimiCodeConfig,
+  saveProjectKimiCodeConfig,
+} from "./src/config.ts";
 import {
   DEFAULT_KIMI_MODEL_INPUT,
   KIMI_API_TYPE,
@@ -35,8 +51,332 @@ import {
 } from "./src/models.ts";
 import { loginKimiCode, refreshKimiCodeToken } from "./src/oauth.ts";
 import { streamSimpleKimi } from "./src/stream.ts";
+import { buildMoonshotFetchTool, buildMoonshotSearchTool } from "./src/tools/moonshot.ts";
+
+const MOONSHOT_TOOL_NAMES = ["moonshot_search", "moonshot_fetch"] as const;
+type MoonshotToolName = (typeof MOONSHOT_TOOL_NAMES)[number];
+type KimiConfigScope = "project" | "home";
+const MEMBERSHIP_LEVEL_NAMES: Record<string, string> = {
+  LEVEL_FREE: "Free",
+  LEVEL_BASIC: "Adagio",
+  LEVEL_STANDARD: "Moderato",
+  LEVEL_INTERMEDIATE: "Allegretto",
+  LEVEL_ADVANCED: "Allegro",
+  LEVEL_PREMIUM: "Vivace",
+};
+
+interface UsageRow {
+  label: string;
+  used: number;
+  limit: number;
+}
+
+function registerConfiguredMoonshotTools(
+  pi: ExtensionAPI,
+  config: KimiCodeConfig,
+  options: { updateActiveTools: boolean },
+): void {
+  if (config.tools.moonshot_search.enabled) {
+    pi.registerTool(
+      buildMoonshotSearchTool({
+        defaultCollapsed: config.tools.moonshot_search.default_collapsed,
+      }),
+    );
+  }
+  if (config.tools.moonshot_fetch.enabled) {
+    pi.registerTool(
+      buildMoonshotFetchTool({
+        defaultCollapsed: config.tools.moonshot_fetch.default_collapsed,
+      }),
+    );
+  }
+
+  if (!options.updateActiveTools) return;
+
+  const activeTools = new Set(pi.getActiveTools());
+  for (const toolName of MOONSHOT_TOOL_NAMES) {
+    if (config.tools[toolName].enabled) {
+      activeTools.add(toolName);
+    } else {
+      activeTools.delete(toolName);
+    }
+  }
+  pi.setActiveTools([...activeTools]);
+}
+
+function getKimiUsageToken(): string | null {
+  const credential = AuthStorage.create().get(PROVIDER_ID);
+  if (credential?.type === "oauth" && credential.access) return credential.access;
+  const apiKey = process.env.KIMI_API_KEY?.trim();
+  return apiKey || null;
+}
+
+function toNumber(value: unknown): number | null {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function parseUsageRow(value: unknown, fallbackLabel: string): UsageRow | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const limit = toNumber(record.limit);
+  const usedValue = toNumber(record.used);
+  const remaining = toNumber(record.remaining);
+  const used = usedValue ?? (limit !== null && remaining !== null ? limit - remaining : null);
+  if (limit === null && used === null) return null;
+  return {
+    label: String(record.name || record.title || fallbackLabel),
+    used: used ?? 0,
+    limit: limit ?? 0,
+  };
+}
+
+function parseUsageSummary(payload: unknown): string {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return "Usage: unavailable";
+  }
+
+  const record = payload as Record<string, unknown>;
+  const lines: string[] = [];
+  const membership = parseMembership(record);
+  if (membership) lines.push(membership);
+
+  const rows: UsageRow[] = [];
+  const summary = parseUsageRow(record.usage, "Weekly limit");
+  if (summary) rows.push(summary);
+
+  if (Array.isArray(record.limits)) {
+    for (const [index, item] of record.limits.entries()) {
+      const detail =
+        typeof item === "object" && item !== null && !Array.isArray(item)
+          ? ((item as Record<string, unknown>).detail ?? item)
+          : item;
+      const row = parseUsageRow(detail, index === 0 ? "5h rate limit" : `Limit #${index + 1}`);
+      if (row) rows.push(row);
+    }
+  }
+
+  lines.push(...rows.map(formatUsageRow));
+  return lines.length === 0 ? "Usage: no usage data" : lines.join("\n");
+}
+
+function parseMembership(record: Record<string, unknown>): string | null {
+  const user = record.user;
+  if (typeof user !== "object" || user === null || Array.isArray(user)) return null;
+  const membership = (user as Record<string, unknown>).membership;
+  if (typeof membership !== "object" || membership === null || Array.isArray(membership)) {
+    return null;
+  }
+  const level = (membership as Record<string, unknown>).level;
+  if (typeof level !== "string" || !level) return null;
+  const name = MEMBERSHIP_LEVEL_NAMES[level];
+  return name ? `Membership: ${name} (${level})` : `Membership: ${level}`;
+}
+
+function formatUsageRow(row: UsageRow): string {
+  if (row.limit <= 0) return `${row.label}: ${row.used} used`;
+  const remaining = Math.max(0, Math.min(row.limit - row.used, row.limit));
+  const percent = Math.round((remaining / row.limit) * 100);
+  return `${row.label}: ${quotaBar(remaining, row.limit)} ${percent}% left (${remaining}/${row.limit})`;
+}
+
+function quotaBar(remaining: number, limit: number): string {
+  const width = 20;
+  const filled = Math.max(0, Math.min(width, Math.round((remaining / limit) * width)));
+  return `[${"#".repeat(filled)}${"-".repeat(width - filled)}]`;
+}
+
+async function fetchKimiUsageSummary(): Promise<string> {
+  const token = getKimiUsageToken();
+  if (!token) return "Usage: missing credentials. Run /login kimi-coding.";
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15_000);
+  try {
+    const response = await fetch("https://api.kimi.com/coding/v1/usages", {
+      method: "GET",
+      headers: {
+        ...getCommonHeaders(),
+        Authorization: `Bearer ${token}`,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) return `Usage: fetch failed (${response.status})`;
+    return parseUsageSummary(await response.json());
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Usage: fetch failed (${message})`;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function moonshotStatus(config: KimiCodeConfig): string {
+  return MOONSHOT_TOOL_NAMES.map((toolName) => {
+    const tool = config.tools[toolName];
+    const enabled = tool.enabled ? "enabled" : "disabled";
+    const collapsed = tool.default_collapsed ? "collapsed" : "expanded";
+    return `${toolName}: ${enabled}, default ${collapsed}`;
+  }).join("\n");
+}
+
+function toggleEnabled(config: KimiCodeConfig, toolName: MoonshotToolName): KimiCodeConfig {
+  return {
+    tools: {
+      ...config.tools,
+      [toolName]: {
+        ...config.tools[toolName],
+        enabled: !config.tools[toolName].enabled,
+      },
+    },
+  };
+}
+
+function toggleCollapsed(config: KimiCodeConfig, toolName: MoonshotToolName): KimiCodeConfig {
+  return {
+    tools: {
+      ...config.tools,
+      [toolName]: {
+        ...config.tools[toolName],
+        default_collapsed: !config.tools[toolName].default_collapsed,
+      },
+    },
+  };
+}
+
+async function runKimiCommand(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+  let config = loadKimiCodeConfig({ cwd: ctx.cwd, home: os.homedir() });
+  let usage = await fetchKimiUsageSummary();
+  ctx.ui.notify(usage);
+
+  while (true) {
+    const choice = await ctx.ui.select(buildKimiMainTitle(config, ctx.cwd), [
+      `Edit project config (${relative(ctx.cwd, getProjectKimiCodeConfigPath(ctx.cwd))})`,
+      `Edit home config (${homeRelative(getGlobalKimiCodeConfigPath(os.homedir()))})`,
+      "Refresh usage",
+      "Done",
+    ]);
+
+    if (!choice || choice === "Done") return;
+    if (choice === "Refresh usage") {
+      usage = await fetchKimiUsageSummary();
+      ctx.ui.notify(usage);
+      continue;
+    }
+    if (choice.startsWith("Edit project config")) {
+      config = await editConfigScope(pi, ctx, "project");
+    } else if (choice.startsWith("Edit home config")) {
+      config = await editConfigScope(pi, ctx, "home");
+    }
+  }
+}
+
+async function editConfigScope(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  scope: KimiConfigScope,
+): Promise<KimiCodeConfig> {
+  let current = loadScopeKimiCodeConfig(scope, ctx.cwd);
+  while (true) {
+    const choice = await ctx.ui.select(buildConfigScopeTitle(scope, current, ctx.cwd), [
+      toolMenuItem(current, "moonshot_search"),
+      toolMenuItem(current, "moonshot_fetch"),
+      "Back",
+    ]);
+    if (!choice || choice === "Back") {
+      return loadKimiCodeConfig({ cwd: ctx.cwd, home: os.homedir() });
+    }
+    if (choice.startsWith("moonshot_search")) {
+      current = await editMoonshotTool(pi, ctx, scope, current, "moonshot_search");
+    } else if (choice.startsWith("moonshot_fetch")) {
+      current = await editMoonshotTool(pi, ctx, scope, current, "moonshot_fetch");
+    }
+  }
+}
+
+async function editMoonshotTool(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  scope: KimiConfigScope,
+  config: KimiCodeConfig,
+  toolName: MoonshotToolName,
+): Promise<KimiCodeConfig> {
+  let current = config;
+  while (true) {
+    const tool = current.tools[toolName];
+    const choice = await ctx.ui.select(
+      `Edit ${toolName}\n\n${formatToolStatus(current, toolName)}`,
+      [
+        tool.enabled ? `Disable ${toolName}` : `Enable ${toolName}`,
+        tool.default_collapsed ? "Expand previews by default" : "Collapse previews by default",
+        "Back",
+      ],
+    );
+    if (!choice || choice === "Back") return current;
+    if (choice.startsWith("Enable") || choice.startsWith("Disable")) {
+      current = toggleEnabled(current, toolName);
+    } else if (choice.endsWith("previews by default")) {
+      current = toggleCollapsed(current, toolName);
+    }
+    saveScopeKimiCodeConfig(scope, ctx.cwd, current);
+    const effective = loadKimiCodeConfig({ cwd: ctx.cwd, home: os.homedir() });
+    registerConfiguredMoonshotTools(pi, effective, { updateActiveTools: true });
+    ctx.ui.notify(`Saved ${toolName} config`, "info");
+  }
+}
+
+function loadScopeKimiCodeConfig(scope: KimiConfigScope, cwd: string): KimiCodeConfig {
+  if (scope === "project") return loadProjectKimiCodeConfig(cwd);
+  return loadHomeKimiCodeConfig(os.homedir());
+}
+
+function saveScopeKimiCodeConfig(
+  scope: KimiConfigScope,
+  cwd: string,
+  config: KimiCodeConfig,
+): void {
+  if (scope === "project") {
+    saveProjectKimiCodeConfig(cwd, config);
+  } else {
+    saveHomeKimiCodeConfig(os.homedir(), config);
+  }
+}
+
+function buildKimiMainTitle(_config: KimiCodeConfig, _cwd: string): string {
+  return "Kimi settings";
+}
+
+function buildConfigScopeTitle(
+  scope: KimiConfigScope,
+  config: KimiCodeConfig,
+  cwd: string,
+): string {
+  const path =
+    scope === "project"
+      ? relative(cwd, getProjectKimiCodeConfigPath(cwd))
+      : homeRelative(getGlobalKimiCodeConfigPath(os.homedir()));
+  return [`Edit ${scope} config`, `File: ${path}`, "", moonshotStatus(config)].join("\n");
+}
+
+function homeRelative(filePath: string): string {
+  const home = os.homedir();
+  return filePath.startsWith(`${home}/`) ? `~/${filePath.slice(home.length + 1)}` : filePath;
+}
+
+function toolMenuItem(config: KimiCodeConfig, toolName: MoonshotToolName): string {
+  return `${toolName} -> ${formatToolStatus(config, toolName)}`;
+}
+
+function formatToolStatus(config: KimiCodeConfig, toolName: MoonshotToolName): string {
+  const tool = config.tools[toolName];
+  const enabled = tool.enabled ? "enabled" : "disabled";
+  const collapsed = tool.default_collapsed ? "default collapsed" : "default expanded";
+  return `${enabled}, ${collapsed}`;
+}
 
 export default function (pi: ExtensionAPI) {
+  const config = loadKimiCodeConfig({ cwd: process.cwd(), home: os.homedir() });
+
   pi.registerProvider(PROVIDER_ID, {
     baseUrl: getBaseUrl(),
     apiKey: "KIMI_API_KEY",
@@ -76,4 +416,13 @@ export default function (pi: ExtensionAPI) {
       },
     },
   });
+
+  registerConfiguredMoonshotTools(pi, config, { updateActiveTools: false });
+
+  pi.registerCommand("kimi-settings", {
+    description: "Show Kimi usage and configure optional Kimi tools",
+    handler: async (_args, ctx) => {
+      await runKimiCommand(pi, ctx);
+    },
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-provider-kimi-code",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Use Kimi Code in Pi without losing the Kimi-specific bits",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface KimiCodeConfig {
+  tools: {
+    moonshot_search: { enabled: boolean; default_collapsed: boolean };
+    moonshot_fetch: { enabled: boolean; default_collapsed: boolean };
+  };
+}
+
+export interface LoadKimiCodeConfigOptions {
+  cwd: string;
+  home: string;
+}
+
+export const DEFAULT_KIMI_CODE_CONFIG: KimiCodeConfig = {
+  tools: {
+    moonshot_search: { enabled: false, default_collapsed: true },
+    moonshot_fetch: { enabled: false, default_collapsed: true },
+  },
+};
+
+export function getGlobalKimiCodeConfigPath(home: string): string {
+  return join(home, ".pi", "pi-provider-kimi-code.json");
+}
+
+export function getProjectKimiCodeConfigPath(cwd: string): string {
+  return join(cwd, ".pi", "pi-provider-kimi-code.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readConfigFile(path: string): Record<string, unknown> {
+  try {
+    if (!existsSync(path)) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch (error) {
+    console.error(`[kimi-coding] failed to read config file ${path}:`, error);
+    return {};
+  }
+}
+
+function readConfigFileQuiet(path: string): Record<string, unknown> {
+  try {
+    if (!existsSync(path)) return {};
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function mergeConfig(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = result[key];
+    if (isRecord(current) && isRecord(value)) {
+      result[key] = mergeConfig(current, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function readEnabled(config: Record<string, unknown>, toolName: string): boolean {
+  const tools = config.tools;
+  if (!isRecord(tools)) return false;
+  const tool = tools[toolName];
+  if (!isRecord(tool)) return false;
+  return tool.enabled === true;
+}
+
+function readDefaultCollapsed(config: Record<string, unknown>, toolName: string): boolean {
+  const tools = config.tools;
+  if (!isRecord(tools)) return true;
+  const tool = tools[toolName];
+  if (!isRecord(tool)) return true;
+  return tool.default_collapsed !== false;
+}
+
+export function loadKimiCodeConfig(options: LoadKimiCodeConfigOptions): KimiCodeConfig {
+  const globalConfig = readConfigFile(getGlobalKimiCodeConfigPath(options.home));
+  const projectConfig = readConfigFile(getProjectKimiCodeConfigPath(options.cwd));
+  const merged = mergeConfig(globalConfig, projectConfig);
+
+  return {
+    tools: {
+      moonshot_search: {
+        enabled: readEnabled(merged, "moonshot_search"),
+        default_collapsed: readDefaultCollapsed(merged, "moonshot_search"),
+      },
+      moonshot_fetch: {
+        enabled: readEnabled(merged, "moonshot_fetch"),
+        default_collapsed: readDefaultCollapsed(merged, "moonshot_fetch"),
+      },
+    },
+  };
+}
+
+export function loadProjectKimiCodeConfig(cwd: string): KimiCodeConfig {
+  return loadKimiCodeConfigFile(getProjectKimiCodeConfigPath(cwd));
+}
+
+export function loadHomeKimiCodeConfig(home: string): KimiCodeConfig {
+  return loadKimiCodeConfigFile(getGlobalKimiCodeConfigPath(home));
+}
+
+function loadKimiCodeConfigFile(path: string): KimiCodeConfig {
+  const projectConfig = readConfigFileQuiet(path);
+  return {
+    tools: {
+      moonshot_search: {
+        enabled: readEnabled(projectConfig, "moonshot_search"),
+        default_collapsed: readDefaultCollapsed(projectConfig, "moonshot_search"),
+      },
+      moonshot_fetch: {
+        enabled: readEnabled(projectConfig, "moonshot_fetch"),
+        default_collapsed: readDefaultCollapsed(projectConfig, "moonshot_fetch"),
+      },
+    },
+  };
+}
+
+export function saveProjectKimiCodeConfig(cwd: string, config: KimiCodeConfig): void {
+  saveKimiCodeConfigFile(getProjectKimiCodeConfigPath(cwd), config);
+}
+
+export function saveHomeKimiCodeConfig(home: string, config: KimiCodeConfig): void {
+  saveKimiCodeConfigFile(getGlobalKimiCodeConfigPath(home), config);
+}
+
+function saveKimiCodeConfigFile(path: string, config: KimiCodeConfig): void {
+  const raw = readConfigFileQuiet(path);
+  const next = {
+    ...raw,
+    tools: {
+      ...(isRecord(raw.tools) ? raw.tools : {}),
+      moonshot_search: { ...config.tools.moonshot_search },
+      moonshot_fetch: { ...config.tools.moonshot_fetch },
+    },
+  };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+}

package/src/tools/moonshot.ts

@@ -0,0 +1,316 @@
+import { AuthStorage, defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "@earendil-works/pi-ai";
+
+import { PROVIDER_ID } from "../constants.ts";
+import { getCommonHeaders } from "../device.ts";
+
+const MOONSHOT_BASE_V1 = "https://api.kimi.com/coding/v1";
+const MOONSHOT_TIMEOUT_MS = 180_000;
+
+export const moonshotSearchSchema = Type.Object({
+  query: Type.String({ description: "The query text to search for." }),
+  limit: Type.Optional(
+    Type.Number({
+      description: "The number of results to return.",
+      default: 5,
+      minimum: 1,
+      maximum: 20,
+    }),
+  ),
+  include_content: Type.Optional(
+    Type.Boolean({
+      description: "Whether to include fetched page content in the search results.",
+      default: false,
+    }),
+  ),
+});
+
+export const moonshotFetchSchema = Type.Object({
+  url: Type.String({ description: "The URL to fetch content from." }),
+});
+
+export type MoonshotSearchParams = Static<typeof moonshotSearchSchema>;
+export type MoonshotFetchParams = Static<typeof moonshotFetchSchema>;
+
+export interface MoonshotSearchResult {
+  url: string;
+  title: string;
+  snippet: string;
+  content?: string;
+}
+
+export interface MoonshotFetchResult {
+  url: string;
+  content: string;
+}
+
+interface MoonshotToolDeps {
+  fetch: typeof fetch;
+  getAccessToken: () => string | null;
+}
+
+export interface BuildMoonshotToolOptions {
+  deps?: Partial<MoonshotToolDeps>;
+  defaultCollapsed?: boolean;
+}
+
+interface MoonshotSearchResponse {
+  search_results?: unknown;
+}
+
+function defaultGetAccessToken(): string | null {
+  const credential = AuthStorage.create().get(PROVIDER_ID);
+  if (!credential || credential.type !== "oauth") return null;
+  return credential.access;
+}
+
+function buildDeps(options: BuildMoonshotToolOptions = {}): MoonshotToolDeps {
+  return {
+    fetch: options.deps?.fetch ?? fetch,
+    getAccessToken: options.deps?.getAccessToken ?? defaultGetAccessToken,
+  };
+}
+
+function clampLimit(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 5;
+  return Math.max(1, Math.min(20, Math.trunc(value)));
+}
+
+function errorResult<T>(message: string): AgentToolResult<T> {
+  return {
+    content: [{ type: "text", text: message }],
+    details: undefined as T,
+  };
+}
+
+function buildTimeoutSignal(signal: AbortSignal | undefined): {
+  signal: AbortSignal;
+  cleanup: () => void;
+} {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), MOONSHOT_TIMEOUT_MS);
+  const abort = () => controller.abort();
+  if (signal?.aborted) {
+    controller.abort();
+  } else {
+    signal?.addEventListener("abort", abort, { once: true });
+  }
+
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", abort);
+    },
+  };
+}
+
+function buildHeaders(accessToken: string, toolCallId: string): Record<string, string> {
+  return {
+    ...getCommonHeaders(),
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "X-Msh-Tool-Call-Id": toolCallId,
+  };
+}
+
+function stringField(record: Record<string, unknown>, key: string): string {
+  const value = record[key];
+  return typeof value === "string" ? value : "";
+}
+
+function mapSearchResults(value: unknown, includeContent: boolean): MoonshotSearchResult[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null)
+    .map((item) => {
+      const result: MoonshotSearchResult = {
+        url: stringField(item, "url"),
+        title: stringField(item, "title"),
+        snippet: stringField(item, "snippet"),
+      };
+      if (includeContent) {
+        result.content = stringField(item, "content");
+      }
+      return result;
+    });
+}
+
+function searchResultsText(results: MoonshotSearchResult[]): string {
+  if (results.length === 0) return "[]";
+  return JSON.stringify(results, null, 2);
+}
+
+function textComponent(text: string) {
+  return {
+    render: () => text.split("\n"),
+    invalidate: () => {},
+  };
+}
+
+function firstText(result: AgentToolResult<unknown>): string {
+  const first = result.content[0];
+  return first?.type === "text" ? first.text : "";
+}
+
+function shouldCollapse(defaultCollapsed: boolean, expanded: boolean | undefined): boolean {
+  return defaultCollapsed && expanded !== true;
+}
+
+function renderSearchResult(
+  result: AgentToolResult<MoonshotSearchResult[]>,
+  expanded: boolean | undefined,
+  defaultCollapsed: boolean,
+) {
+  if (!Array.isArray(result.details)) {
+    return textComponent(firstText(result));
+  }
+  if (!shouldCollapse(defaultCollapsed, expanded)) {
+    return textComponent(searchResultsText(result.details));
+  }
+
+  const count = result.details.length;
+  const first = result.details[0];
+  const suffix = first ? `; first: ${first.title || first.url}` : "";
+  return textComponent(`moonshot_search returned ${count} result(s)${suffix}`);
+}
+
+function renderFetchResult(
+  result: AgentToolResult<MoonshotFetchResult>,
+  expanded: boolean | undefined,
+  defaultCollapsed: boolean,
+) {
+  if (!result.details) {
+    return textComponent(firstText(result));
+  }
+  if (!shouldCollapse(defaultCollapsed, expanded)) {
+    return textComponent(result.details.content);
+  }
+
+  return textComponent(
+    `moonshot_fetch fetched ${result.details.url} (${result.details.content.length} chars)`,
+  );
+}
+
+async function readErrorBody(response: Response): Promise<string> {
+  return response.text().catch(() => "");
+}
+
+export function buildMoonshotSearchTool(options: BuildMoonshotToolOptions = {}) {
+  const deps = buildDeps(options);
+  const defaultCollapsed = options.defaultCollapsed ?? true;
+
+  return defineTool({
+    name: "moonshot_search",
+    label: "Moonshot Search",
+    description: "Search the web through Kimi Coding's server-side Moonshot search service.",
+    promptSnippet: "Search the web with Kimi Coding's Moonshot search service",
+    parameters: moonshotSearchSchema,
+
+    async execute(toolCallId, params, signal) {
+      const accessToken = deps.getAccessToken();
+      if (!accessToken) {
+        return errorResult<MoonshotSearchResult[]>(
+          "Missing Kimi Code OAuth credentials. Run /login kimi-coding first.",
+        );
+      }
+
+      const limit = clampLimit(params.limit);
+      const includeContent = params.include_content === true;
+      const timeout = buildTimeoutSignal(signal);
+      try {
+        const response = await deps.fetch(`${MOONSHOT_BASE_V1}/search`, {
+          method: "POST",
+          headers: buildHeaders(accessToken, toolCallId),
+          body: JSON.stringify({
+            text_query: params.query,
+            limit,
+            enable_page_crawling: includeContent,
+            timeout_seconds: 30,
+          }),
+          signal: timeout.signal,
+        });
+
+        if (!response.ok) {
+          const body = await readErrorBody(response);
+          return errorResult<MoonshotSearchResult[]>(
+            `Moonshot search failed: ${response.status}${body ? ` ${body}` : ""}`,
+          );
+        }
+
+        const data = (await response.json()) as MoonshotSearchResponse;
+        const results = mapSearchResults(data.search_results, includeContent);
+        return {
+          content: [{ type: "text", text: searchResultsText(results) }],
+          details: results,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult<MoonshotSearchResult[]>(`Moonshot search failed: ${message}`);
+      } finally {
+        timeout.cleanup();
+      }
+    },
+
+    renderResult(result, renderOptions) {
+      return renderSearchResult(result, renderOptions.expanded, defaultCollapsed);
+    },
+  });
+}
+
+export function buildMoonshotFetchTool(options: BuildMoonshotToolOptions = {}) {
+  const deps = buildDeps(options);
+  const defaultCollapsed = options.defaultCollapsed ?? true;
+
+  return defineTool({
+    name: "moonshot_fetch",
+    label: "Moonshot Fetch",
+    description: "Fetch a web page through Kimi Coding's server-side Moonshot fetch service.",
+    promptSnippet: "Fetch a web page with Kimi Coding's Moonshot fetch service",
+    parameters: moonshotFetchSchema,
+
+    async execute(toolCallId, params, signal) {
+      const accessToken = deps.getAccessToken();
+      if (!accessToken) {
+        return errorResult<MoonshotFetchResult>(
+          "Missing Kimi Code OAuth credentials. Run /login kimi-coding first.",
+        );
+      }
+
+      const timeout = buildTimeoutSignal(signal);
+      try {
+        const response = await deps.fetch(`${MOONSHOT_BASE_V1}/fetch`, {
+          method: "POST",
+          headers: {
+            ...buildHeaders(accessToken, toolCallId),
+            Accept: "text/markdown",
+          },
+          body: JSON.stringify({ url: params.url }),
+          signal: timeout.signal,
+        });
+
+        if (!response.ok) {
+          const body = await readErrorBody(response);
+          return errorResult<MoonshotFetchResult>(
+            `Moonshot fetch failed: ${response.status}${body ? ` ${body}` : ""}`,
+          );
+        }
+
+        const content = await response.text();
+        return {
+          content: [{ type: "text", text: content }],
+          details: { url: params.url, content },
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult<MoonshotFetchResult>(`Moonshot fetch failed: ${message}`);
+      } finally {
+        timeout.cleanup();
+      }
+    },
+
+    renderResult(result, renderOptions) {
+      return renderFetchResult(result, renderOptions.expanded, defaultCollapsed);
+    },
+  });
+}