@pragma-sh/kimi-plugin 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pragma-sh/kimi-plugin",
+  "version": "0.1.0-alpha.0",
+  "description": "Kimi Code CLI plugin that reports agent status to Pragma via native hooks.",
+  "license": "AGPL-3.0-only",
+  "files": [
+    "assets",
+    "dist",
+    "hooks",
+    "kimi.plugin.json",
+    "pragma-plugin.json",
+    "scripts",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./pragma-plugin": "./src/pragma-plugin.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/pragma-plugin.ts --outdir dist --format esm --target node --packages bundle && mv dist/pragma-plugin.js dist/pragma-plugin.mjs && bun build scripts/install-local.ts --outfile dist/install.mjs --format esm --target node --packages bundle",
+    "install:local": "bun run build && bun run scripts/install-local.ts",
+    "prepack": "bun run build",
+    "typecheck": "tsc --noEmit",
+    "test": "bun --bun vitest run",
+    "lint": "oxlint ."
+  },
+  "devDependencies": {
+    "@pragma/plugin": "workspace:*",
+    "@pragma/watcher-kit": "workspace:*",
+    "@types/node": "^24.12.3",
+    "bunup": "^0.16.32",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "pragma": {
+    "pluginId": "pragma.kimi",
+    "main": "./dist/pragma-plugin.mjs"
+  }
+}

package/pragma-plugin.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/pragma-sh/pragma/main/packages/plugin-registry/pragma-plugin.schema.json",
+  "name": "Kimi Code CLI",
+  "description": "Launch Kimi Code CLI in Pragma with live status, approvals, questions, subagents, and session naming.",
+  "categories": ["agent-plugin"],
+  "images": [
+    {
+      "url": "https://raw.githubusercontent.com/pragma-sh/pragma/main/packages/kimi-plugin/assets/kimi.png",
+      "alt": "Kimi logo"
+    }
+  ],
+  "install": { "command": "node", "args": ["dist/install.mjs"] },
+  "agentBinary": "kimi"
+}

package/scripts/install-local.ts

@@ -0,0 +1,111 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+interface InstalledPlugin extends Record<string, unknown> {
+  id: string;
+  root: string;
+  source: "local-path";
+  enabled: boolean;
+  installedAt: string;
+  updatedAt: string;
+  originalSource: string;
+}
+
+interface InstalledFile {
+  version: 1;
+  plugins: InstalledPlugin[];
+}
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const RUNTIME_PATHS = ["assets", "dist", "hooks", "kimi.plugin.json", "package.json"];
+
+/** Installs a fresh package snapshot into Kimi's managed plugin store. */
+export function installLocal(
+  kimiHome = process.env.KIMI_CODE_HOME ?? join(homedir(), ".kimi-code"),
+  packageRoot = PACKAGE_ROOT,
+): string {
+  const manifest = JSON.parse(readFileSync(join(packageRoot, "kimi.plugin.json"), "utf8")) as {
+    name?: unknown;
+  };
+  if (typeof manifest.name !== "string" || manifest.name.length === 0) {
+    throw new Error('kimi.plugin.json must contain a non-empty "name"');
+  }
+  for (const relativePath of RUNTIME_PATHS) {
+    if (!existsSync(join(packageRoot, relativePath))) {
+      throw new Error(`Missing runtime path: ${relativePath}`);
+    }
+  }
+
+  const id = manifest.name.toLowerCase();
+  const pluginsDir = join(kimiHome, "plugins");
+  const managedDir = join(pluginsDir, "managed");
+  const target = join(managedDir, id);
+  mkdirSync(managedDir, { recursive: true });
+  const staging = mkdtempSync(join(managedDir, `${id}-`));
+  try {
+    for (const relativePath of RUNTIME_PATHS) {
+      cpSync(join(packageRoot, relativePath), join(staging, relativePath), { recursive: true });
+    }
+    rmSync(target, { recursive: true, force: true });
+    renameSync(staging, target);
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+
+  const installedPath = join(pluginsDir, "installed.json");
+  const installed = readInstalled(installedPath);
+  const existingIndex = installed.plugins.findIndex((plugin) => plugin.id === id);
+  const existing = existingIndex < 0 ? undefined : installed.plugins[existingIndex];
+  const now = new Date().toISOString();
+  const record: InstalledPlugin = {
+    ...existing,
+    id,
+    root: target,
+    source: "local-path",
+    enabled: existing?.enabled ?? true,
+    installedAt:
+      typeof existing?.installedAt === "string" && existing.installedAt.length > 0
+        ? existing.installedAt
+        : now,
+    updatedAt: now,
+    originalSource: packageRoot,
+  };
+  if (existingIndex < 0) installed.plugins.push(record);
+  else installed.plugins[existingIndex] = record;
+
+  const tempPath = `${installedPath}.${process.pid}.tmp`;
+  writeFileSync(tempPath, `${JSON.stringify(installed, null, 2)}\n`);
+  renameSync(tempPath, installedPath);
+  return target;
+}
+
+function readInstalled(path: string): InstalledFile {
+  if (!existsSync(path)) return { version: 1, plugins: [] };
+  const value = JSON.parse(readFileSync(path, "utf8")) as {
+    version?: unknown;
+    plugins?: unknown;
+  };
+  if (value.version !== 1 || !Array.isArray(value.plugins)) {
+    throw new Error(`${path} is not a valid Kimi installed.json file`);
+  }
+  return { version: 1, plugins: value.plugins as InstalledPlugin[] };
+}
+
+const entryPath = process.argv[1];
+if (entryPath !== undefined && resolve(entryPath) === fileURLToPath(import.meta.url)) {
+  const target = installLocal();
+  process.stdout.write(`Installed Pragma Kimi plugin to ${target}.\n`);
+  process.stdout.write("Run `/plugins reload` or start a new Kimi session to load it.\n");
+}

package/src/models.ts

@@ -0,0 +1,94 @@
+import type { AgentModelEntry, PluginContext } from "@pragma/plugin/catalog";
+
+// The official Kimi Code installer puts the CLI in `~/.kimi-code/bin`, which
+// GUI-launched Pragma hosts do not put on the subprocess PATH (see
+// `process_env` in pragma-core). The `||` fallback keeps the loader working on
+// such a host while still preferring a `kimi` the user installed on PATH.
+const KIMI_BIN_DIR = "$HOME/.kimi-code/bin";
+const KIMI_MODELS_COMMAND = `kimi provider list --json || "${KIMI_BIN_DIR}/kimi" provider list --json`;
+const KIMI_DEFAULT_MODEL_COMMAND = `kimi provider list || "${KIMI_BIN_DIR}/kimi" provider list`;
+
+interface KimiConfigModel {
+  provider: string;
+  model: string;
+  displayName?: string;
+}
+
+/** Reads Kimi's model aliases through its supported host CLI. */
+export async function loadKimiModels(ctx: PluginContext): Promise<AgentModelEntry[]> {
+  try {
+    const results = await ctx.sdk.exec.run({
+      cwd: ctx.project?.path ?? "/tmp",
+      commands: [KIMI_MODELS_COMMAND, KIMI_DEFAULT_MODEL_COMMAND],
+    });
+    return kimiModelsFromConfig(
+      parseKimiProviderModels(results[0]?.stdout ?? ""),
+      parseKimiDefaultModel(results[1]?.stdout ?? ""),
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Maps Kimi's config record to launcher model entries, preferring the
+ * configured default and otherwise preserving declaration order.
+ */
+export function kimiModelsFromConfig(
+  config: Record<string, KimiConfigModel>,
+  defaultModel?: string,
+): AgentModelEntry[] {
+  const entries = Object.entries(config).map(([id, model]) => ({
+    id,
+    name: model.displayName ?? model.model,
+  }));
+  const defaultIndex = entries.findIndex((entry) => entry.id === defaultModel);
+  if (defaultIndex > 0) {
+    const [entry] = entries.splice(defaultIndex, 1);
+    if (entry !== undefined) entries.unshift(entry);
+  }
+  return entries;
+}
+
+/**
+ * Parses `kimi provider list --json` without retaining provider credentials,
+ * skipping aliases Kimi reports as disabled.
+ */
+export function parseKimiProviderModels(output: string): Record<string, KimiConfigModel> {
+  let value: unknown;
+  try {
+    value = JSON.parse(output);
+  } catch {
+    return {};
+  }
+  const models = recordValue(recordValue(value)?.models);
+  if (models === undefined) return {};
+
+  const parsed: Record<string, KimiConfigModel> = {};
+  for (const [alias, candidate] of Object.entries(models)) {
+    const model = recordValue(candidate);
+    if (model === undefined || typeof model.model !== "string" || model.model.length === 0) {
+      continue;
+    }
+    // A disabled alias is rejected by Kimi at launch, so it must never reach the picker.
+    if (model.disabled === true) continue;
+    parsed[alias] = {
+      provider: typeof model.provider === "string" ? model.provider : "",
+      model: model.model,
+      ...(typeof model.displayName === "string" ? { displayName: model.displayName } : {}),
+    };
+  }
+  return parsed;
+}
+
+/** Reads the optional default alias from human-readable `kimi provider list`. */
+export function parseKimiDefaultModel(output: string): string | undefined {
+  const match = /^Default model:\s*(.+)$/m.exec(output);
+  return match?.[1]?.trim() || undefined;
+}
+
+function recordValue(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}

package/src/pragma-plugin.ts

@@ -0,0 +1,103 @@
+import { defineAgent, definePlugin, type PluginDefinition } from "@pragma/plugin/catalog";
+import { createTuiWatcher } from "@pragma/watcher-kit";
+
+import { loadKimiModels } from "./models";
+
+/** Lets Kimi's paste-aware composer commit interjected text before Enter. */
+const INTERJECT_SUBMIT_DELAY_MS = 200;
+/** Kimi paints its TUI within a couple of seconds of launch; type after it. */
+const PREFILL_DELAY_MS = 2500;
+
+const baseWatcher = createTuiWatcher({
+  agent: "kimi",
+  // Kimi command approvals cannot be brokered, but AskUserQuestion is reported
+  // by the hook and answered through Kimi's native question dialog.
+  handleDecisions: false,
+  handleQuestionAnswers: true,
+  questionFinalizeKeys: "1",
+  interjectSubmitDelayMs: INTERJECT_SUBMIT_DELAY_MS,
+});
+
+/**
+ * Pragma plugin for the Kimi Code CLI, bundled to `dist/pragma-plugin.mjs`.
+ *
+ * Lifecycle reporting is a declarative hook bundle (`kimi.plugin.json` ->
+ * `hooks/report.sh`) installed into Kimi through its own `/plugins install`
+ * mechanism, because Kimi loads no in-process JavaScript plugin and its only
+ * live extension point is shell-command hooks. This module contributes only
+ * the Pragma-side launcher, model provider and watcher.
+ */
+export const kimiAgentPlugin: PluginDefinition = definePlugin({
+  name: "Kimi Code",
+  description: "Launch Kimi Code from Pragma.",
+  watchers: [
+    {
+      agent: "kimi",
+      async watch(ctx) {
+        try {
+          await baseWatcher.watch(ctx);
+        } finally {
+          // `SessionEnd` already clears a graceful exit; this covers a session
+          // killed hard enough that no hook runs.
+          try {
+            await ctx.sdk.agents.report({
+              agent: ctx.agentId,
+              tabId: ctx.session.tabId,
+              worktreeId: ctx.session.worktreeId,
+              status: "cleared",
+              attentionKind: null,
+            });
+          } catch {
+            // Session-exit cleanup must never disrupt watcher shutdown.
+          }
+        }
+      },
+    },
+  ],
+  agents: [
+    defineAgent({
+      id: "kimi",
+      name: "Kimi Code",
+      icon: () => null,
+      iconPath: "assets/kimi.png",
+      // `-y` (yolo) is the default launch: Kimi's manual mode gates Bash behind
+      // a TUI approval prompt, so a plain `kimi` never completes a safe shell
+      // command headlessly (`pragma-cli agent verify` `command-no-permission`).
+      // Baking `-y` into the base command mirrors Claude Code's
+      // `--permission-mode auto`; the mode selector below is declared for when
+      // the host wires it up (then this base and the per-mode args must be
+      // reconciled).
+      launch: { command: ["kimi", "-y"] },
+      prefillDelayMs: PREFILL_DELAY_MS,
+      prefillMode: "plain",
+      prefillSubmit: "\r",
+      models: loadKimiModels,
+      // First entry is the default; it matches the `-y` baked into `launch`.
+      // These are the real launch flags that change how much Kimi asks for.
+      permissionModes: [
+        { id: "yolo", name: "Auto-approve tools" },
+        { id: "default", name: "Ask for approval" },
+        { id: "auto", name: "Fully autonomous" },
+        { id: "plan", name: "Plan mode" },
+      ],
+      // `commandApproval`: Kimi's permission-request hook is fire-and-forget,
+      // so Pragma cannot approve on the agent's behalf.
+      excludeFeatures: ["commandApproval"],
+      args: {
+        model: (modelId: string) => ["-m", modelId],
+        reasoning: () => [],
+        permissionMode: (permissionModeId: string) => {
+          if (permissionModeId === "yolo") {
+            return [];
+          }
+          if (permissionModeId === "auto") {
+            return ["--auto"];
+          }
+          return permissionModeId === "plan" ? ["--plan"] : [];
+        },
+      },
+    }),
+  ],
+});
+
+export default kimiAgentPlugin;