Skip to content

The open-source app everyone uses to manage agents at work

feat: add kimi-local adapter for Kimi Code CLI (CLI + ACP engines) (#9967)

David V233c12f029de
diff --git a/Dockerfile b/Dockerfile
index 109305a323..4e3a271529 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -33,6 +33,7 @@ COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/
COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
COPY packages/adapters/grok-local/package.json packages/adapters/grok-local/
+COPY packages/adapters/kimi-local/package.json packages/adapters/kimi-local/
COPY packages/adapters/hermes/package.json packages/adapters/hermes/
COPY packages/adapters/hermes-gateway/package.json packages/adapters/hermes-gateway/
COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
@@ -86,7 +87,7 @@ WORKDIR /app
# (the single most expensive layer: four CLI toolchains + apt, per arch) can
# never hit the layer cache and rebuilds on every build.
RUN echo "cli-tools-epoch: ${CLI_TOOLS_CACHE_EPOCH}" \
- && npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai @google/gemini-cli@latest \
+ && npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai @google/gemini-cli@latest @moonshot-ai/kimi-code@latest \
&& apt-get update \
&& apt-get install -y --no-install-recommends openssh-client jq \
&& rm -rf /var/lib/apt/lists/* \
diff --git a/cli/package.json b/cli/package.json
index 6d5cc10a21..9be7fa2c04 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -43,6 +43,7 @@
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-gemini-local": "workspace:*",
"@paperclipai/adapter-grok-local": "workspace:*",
+ "@paperclipai/adapter-kimi-local": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
"@paperclipai/adapter-pi-local": "workspace:*",
"@paperclipai/adapter-openclaw-gateway": "workspace:*",
diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.ts
index f30e32eafb..7dfa12db95 100644
--- a/cli/src/adapters/registry.ts
+++ b/cli/src/adapters/registry.ts
@@ -5,6 +5,7 @@ import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";
import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
import { printGrokStreamEvent } from "@paperclipai/adapter-grok-local/cli";
+import { printKimiStreamEvent } from "@paperclipai/adapter-kimi-local/cli";
import { formatStdoutEvent as printHermesGatewayStreamEvent } from "@paperclipai/hermes-paperclip-adapter/gateway/cli";
import { printHermesStreamEvent } from "@paperclipai/hermes-paperclip-adapter/cli";
import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
@@ -53,6 +54,11 @@ const grokLocalCLIAdapter: CLIAdapterModule = {
formatStdoutEvent: printGrokStreamEvent,
};
+const kimiLocalCLIAdapter: CLIAdapterModule = {
+ type: "kimi_local",
+ formatStdoutEvent: printKimiStreamEvent,
+};
+
const hermesGatewayCLIAdapter: CLIAdapterModule = {
type: "hermes_gateway",
formatStdoutEvent: printHermesGatewayStreamEvent,
@@ -78,6 +84,7 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
cursorCloudCLIAdapter,
geminiLocalCLIAdapter,
grokLocalCLIAdapter,
+ kimiLocalCLIAdapter,
hermesGatewayCLIAdapter,
hermesLocalCLIAdapter,
openclawGatewayCLIAdapter,
diff --git a/cli/src/commands/client/agent.ts b/cli/src/commands/client/agent.ts
index 6d6677e424..3f81da6c6b 100644
--- a/cli/src/commands/client/agent.ts
+++ b/cli/src/commands/client/agent.ts
@@ -93,7 +93,7 @@ interface CreatedAgentKey {
}
interface SkillsInstallSummary {
- tool: "codex" | "claude";
+ tool: "codex" | "claude" | "kimi";
target: string;
linked: string[];
removed: string[];
@@ -115,10 +115,16 @@ function claudeSkillsHome(): string {
return path.join(base, "skills");
}
+function kimiSkillsHome(): string {
+ const fromEnv = process.env.KIMI_CODE_HOME?.trim();
+ const base = fromEnv && fromEnv.length > 0 ? fromEnv : path.join(os.homedir(), ".kimi-code");
+ return path.join(base, "skills");
+}
+
async function installSkillsForTarget(
sourceSkillsDir: string,
targetSkillsDir: string,
- tool: "codex" | "claude",
+ tool: "codex" | "claude" | "kimi",
): Promise<SkillsInstallSummary> {
const summary: SkillsInstallSummary = {
tool,
@@ -771,7 +777,7 @@ export function registerAgentCommands(program: Command): void {
.option("--key-name <name>", "API key label", "local-cli")
.option(
"--no-install-skills",
- "Skip installing Paperclip skills into ~/.codex/skills and ~/.claude/skills",
+ "Skip installing Paperclip skills into ~/.codex/skills, ~/.claude/skills, and ~/.kimi-code/skills",
)
.action(async (agentRef: string, opts: AgentLocalCliOptions) => {
try {
@@ -803,6 +809,7 @@ export function registerAgentCommands(program: Command): void {
installSummaries.push(
await installSkillsForTarget(skillsDir, codexSkillsHome(), "codex"),
await installSkillsForTarget(skillsDir, claudeSkillsHome(), "claude"),
+ await installSkillsForTarget(skillsDir, kimiSkillsHome(), "kimi"),
);
}
diff --git a/docs/adapters/kimi-local.md b/docs/adapters/kimi-local.md
new file mode 100644
index 0000000000..78cf7cba81
--- /dev/null
+++ b/docs/adapters/kimi-local.md
@@ -0,0 +1,84 @@
+---
+title: Kimi Code CLI
+summary: Kimi Code CLI local adapter setup and configuration
+---
+
+The `kimi_local` adapter runs the Kimi Code CLI (`kimi`) locally. It has two execution engines: the default **ACP engine** (`kimi acp`, streaming transcript with live tool status, matching `claude_local`/`gemini_local`) and a **CLI lane** (`kimi -p --output-format stream-json`) used as an automatic fallback. It supports session persistence, per-run skill delivery via `--skills-dir`, thinking-effort control, and structured output parsing.
+
+## Prerequisites
+
+- Kimi Code CLI installed (`kimi` command available; npm package `@moonshot-ai/kimi-code`)
+- Authentication configured via one of:
+ - `kimi login` (OAuth device flow; credentials stored under `$KIMI_CODE_HOME`, default `~/.kimi-code/`)
+ - A provider configured in Kimi's `config.toml` (`[providers.<name>]`)
+ - The `KIMI_MODEL_NAME` + `KIMI_MODEL_API_KEY` environment pair (optionally `KIMI_MODEL_BASE_URL`, `KIMI_MODEL_PROVIDER_TYPE`), set in the adapter env or server shell
+
+## Configuration Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `engine` | string | No | Execution engine: `acp` (default; streaming ACP lane via `kimi acp`), `cli` (headless `kimi -p` lane), or unset/`auto` (ACP with automatic CLI fallback when ACP prerequisites fail). |
+| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
+| `model` | string | No | Kimi model alias (`provider/model`). Defaults to `kimi-code/kimi-for-coding`. When empty, Kimi uses `default_model` from its own `config.toml`. |
+| `promptTemplate` | string | No | Prompt used for all runs |
+| `instructionsFilePath` | string | No | Markdown instructions file prepended to the prompt. Sibling files in the same directory (`HEARTBEAT.md`, `SOUL.md`, `TOOLS.md`) are made readable via `--add-dir` on local runs. |
+| `effort` | string | No | Thinking effort (`low` \| `medium` \| `high` \| `max`). **CLI lane only**: forwarded as `KIMI_MODEL_THINKING_EFFORT` for effort-capable models (currently `kimi-code/k3`); `medium` maps to `high` since Kimi has no medium tier. Ignored for models without `support_efforts`, and not forwarded on the default ACP engine lane — pin `engine: cli` when effort control matters. |
+| `command` | string | No | CLI command override. Defaults to `kimi`. |
+| `extraArgs` | string[] | No | Additional CLI arguments appended to every run |
+| `env` | object | No | Environment variables (supports secret refs) |
+| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
+| `graceSec` | number | No | Grace period before force-kill |
+
+## Execution Engine
+
+By default the adapter runs Kimi through the **ACP engine** (`kimi acp`, an Agent Client Protocol server over stdio), the same shared engine used by `claude_local`, `codex_local`, and `gemini_local`. ACP streams the transcript live: assistant text arrives as deltas and tool calls report a `pending`/`completed` status, so the issue thread updates continuously instead of in bursts.
+
+Engine selection (`engine` config field):
+
+- unset or `auto`: use ACP when its prerequisites pass (Node >= 20, resolvable `kimi acp` command, a bidirectional process target), otherwise fall back to the CLI lane with a diagnostic note.
+- `acp`: require ACP; startup failures surface as run errors rather than falling back.
+- `cli`: pin the headless CLI lane described below.
+
+The ACP lane reuses the shared acpx session codec, transcript parser, and CLI event formatter, so sessions, transcripts, and logs render identically to the other ACP adapters.
+
+## Headless Execution (CLI lane)
+
+Runs execute as `kimi -p <prompt> --output-format stream-json` (plus `-m <model>` when configured and `-r <sessionId>` when resuming). On local runs the adapter also passes `--add-dir <instructions-dir>` so the agent can read sibling instruction files, and `--skills-dir <dir>` when skills are desired (see below). The prompt is passed as an argument, not stdin. The adapter sets a headless-safe environment (`CI=1`, `NO_COLOR=1`, `KIMI_CODE_NO_AUTO_UPDATE=1`, and `TERM=dumb` when unset) so unattended heartbeats never block on interactive prompts, theme detection, or update preflight; user-configured env values always win.
+
+## Instructions Bundle
+
+When `instructionsFilePath` points at a managed instruction bundle, the entry file (e.g. `AGENTS.md`) is prepended to the prompt along with a directive that names its sibling files (`HEARTBEAT.md`, `SOUL.md`, `TOOLS.md`). On local runs the containing directory is exposed to Kimi via `--add-dir`, so the agent can actually open those companion files instead of only seeing the entry file.
+
+## Thinking Effort
+
+The `effort` field applies to the **headless CLI lane only** (`engine: cli`, or the automatic fallback when ACP prerequisites fail). On the default ACP engine lane it is currently **not forwarded**: Kimi's ACP interface exposes a separate `thinking` config option that Paperclip does not wire yet, so an effort configured on an ACP-lane agent leaves Kimi's own default behavior in place. Pin `engine: cli` when thinking-effort control matters. On the CLI lane, `effort` is forwarded as the `KIMI_MODEL_THINKING_EFFORT` operational override, which applies to Kimi providers including managed OAuth models. Kimi has no per-invocation effort flag and no `medium` tier, so `medium` is mapped to `high`; `low`, `high`, and `max` pass through. Effort is only sent for models that advertise `support_efforts` (currently `kimi-code/k3`) to avoid provider rejections; extend `EFFORT_CAPABLE_MODELS` in the adapter as more models gain support.
+
+## Session Persistence
+
+The adapter captures the Kimi session id from the trailing `session.resume_hint` meta event and persists it between heartbeats. On the next wake, it resumes the existing conversation with `-r <session_id>` so the agent retains context.
+
+Session resume is cwd-aware: if the working directory changed since the last run, a fresh session starts instead.
+
+If resume fails with an unknown/unrecoverable session error, the adapter automatically retries with a fresh session.
+
+## Skills Delivery
+
+Desired Paperclip skills are delivered from a dedicated per-run directory passed via `--skills-dir`, so skills load reliably and in isolation without writing into the shared `~/.kimi-code/skills` home. On remote runs the skills snapshot is synced to the target and `--skills-dir` points at that isolated copy — Paperclip never overwrites `$KIMI_CODE_HOME/skills`, so skills installed by the operator or other agents are left intact. `--skills-dir` is only passed when at least one skill is desired, so unconfigured agents keep Kimi's default skill discovery.
+
+### Control-plane skill
+
+`paperclipai agent local-cli <agentRef> -C <companyId>` installs the Paperclip control-plane skills into `~/.kimi-code/skills` (honoring `KIMI_CODE_HOME`), alongside the existing `~/.codex/skills` and `~/.claude/skills` targets. Kimi auto-discovers this home on every run, so the agent has the control-plane API reference (issue/comment/interaction routes) from turn one rather than rediscovering endpoints by trial and error. Pass `--no-install-skills` to skip. This is independent of the per-run `--skills-dir` delivery above, which only applies when an agent has explicitly configured skills.
+
+## Environment Test
+
+Use the "Test Environment" button in the UI to validate the adapter config. It checks:
+
+- Kimi CLI is installed and accessible (`kimi --version`)
+- Working directory is absolute and available (auto-created if missing and permitted)
+- Auth availability (OAuth credential/config files under `$KIMI_CODE_HOME`, or the `KIMI_MODEL_NAME` + `KIMI_MODEL_API_KEY` env pair)
+- A live hello probe (`kimi -p "Respond with hello." --output-format stream-json`) to verify CLI readiness
+
+## Notes
+
+- Both execution engines are supported: the ACP engine (`kimi acp`, default) and the headless CLI lane (fallback / `engine=cli`).
+- Available model aliases on a standard install: `kimi-code/kimi-for-coding` (K2.7 Coding), `kimi-code/kimi-for-coding-highspeed` (K2.7 Coding Highspeed), `kimi-code/k3` (K3).
diff --git a/docs/adapters/overview.md b/docs/adapters/overview.md
index 6fdf1723f3..55b0dcc525 100644
--- a/docs/adapters/overview.md
+++ b/docs/adapters/overview.md
@@ -21,6 +21,7 @@ When a heartbeat fires, Paperclip:
| [Claude Code](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally, with a native ACP engine when available |
| [Codex](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally, with a native ACP engine when available |
| [Gemini CLI](/adapters/gemini-local) | `gemini_local` | Runs Gemini CLI locally (experimental — adapter package exists, not yet in stable type enum) |
+| [Kimi Code CLI](/adapters/kimi-local) | `kimi_local` | Runs Kimi Code CLI locally through ACP, with headless `-p` mode as a fallback |
| OpenCode | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
| Cursor | `cursor` | Runs Cursor in background mode |
| Pi | `pi_local` | Runs an embedded Pi agent locally |
diff --git a/packages/adapter-utils/src/acpx-engine/constants.ts b/packages/adapter-utils/src/acpx-engine/constants.ts
index 86368f5f97..11f3aa2249 100644
--- a/packages/adapter-utils/src/acpx-engine/constants.ts
+++ b/packages/adapter-utils/src/acpx-engine/constants.ts
@@ -9,6 +9,7 @@ export const ACPX_ADAPTER_AGENT_IDS = {
claude_local: "claude",
codex_local: "codex",
gemini_local: "gemini",
+ kimi_local: "kimi",
custom_acp: "custom",
} as const;
diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.ts
index cf12a37efb..fc3aa6ffd5 100644
--- a/packages/adapter-utils/src/acpx-engine/execute.ts
+++ b/packages/adapter-utils/src/acpx-engine/execute.ts
@@ -642,6 +642,11 @@ async function resolveBuiltInAgentCommand(input: {
if (agent === "gemini") {
return { command: "gemini --acp", shellCommand: "gemini --acp" };
}
+ if (agent === "kimi") {
+ // Kimi Code exposes its ACP server via the `kimi acp` subcommand (stdio),
+ // rather than a flag (gemini) or a dedicated bin (claude/codex).
+ return { command: "kimi acp", shellCommand: "kimi acp" };
+ }
const binName = agent === "claude" ? "claude-agent-acp" : agent === "codex" ? "codex-acp" : null;
if (!binName) return null;
if (executionTargetIsRemote) {
diff --git a/packages/adapter-utils/src/session-compaction.ts b/packages/adapter-utils/src/session-compaction.ts
index 1e7dd6ac47..3764155c40 100644
--- a/packages/adapter-utils/src/session-compaction.ts
+++ b/packages/adapter-utils/src/session-compaction.ts
@@ -43,6 +43,7 @@ export const LEGACY_SESSIONED_ADAPTER_TYPES = new Set([
"cursor",
"gemini_local",
"hermes_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]);
@@ -73,6 +74,11 @@ export const ADAPTER_SESSION_MANAGEMENT: Record<string, AdapterSessionManagement
nativeContextManagement: "unknown",
defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
},
+ kimi_local: {
+ supportsSessionResume: true,
+ nativeContextManagement: "unknown",
+ defaultSessionCompaction: DEFAULT_SESSION_COMPACTION_POLICY,
+ },
opencode_local: {
supportsSessionResume: true,
nativeContextManagement: "unknown",
diff --git a/packages/adapters/kimi-local/package.json b/packages/adapters/kimi-local/package.json
new file mode 100644
index 0000000000..5c6379e723
--- /dev/null
+++ b/packages/adapters/kimi-local/package.json
@@ -0,0 +1,60 @@
+{
+ "name": "@paperclipai/adapter-kimi-local",
+ "version": "0.3.1",
+ "license": "MIT",
+ "homepage": "https://github.com/paperclipai/paperclip",
+ "bugs": {
+ "url": "https://github.com/paperclipai/paperclip/issues"
+ },
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/paperclipai/paperclip",
+ "directory": "packages/adapters/kimi-local"
+ },
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts",
+ "./server": "./src/server/index.ts",
+ "./ui": "./src/ui/index.ts",
+ "./cli": "./src/cli/index.ts"
+ },
+ "publishConfig": {
+ "access": "public",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ },
+ "./server": {
+ "types": "./dist/server/index.d.ts",
+ "import": "./dist/server/index.js"
+ },
+ "./ui": {
+ "types": "./dist/ui/index.d.ts",
+ "import": "./dist/ui/index.js"
+ },
+ "./cli": {
+ "types": "./dist/cli/index.d.ts",
+ "import": "./dist/cli/index.js"
+ }
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts"
+ },
+ "files": [
+ "dist"
+ ],
+ "scripts": {
+ "build": "tsc",
+ "clean": "rm -rf dist",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@paperclipai/adapter-utils": "workspace:*",
+ "picocolors": "^1.1.1"
+ },
+ "devDependencies": {
+ "@types/node": "^22.19.21",
+ "typescript": "^5.7.3"
+ }
+}
diff --git a/packages/adapters/kimi-local/src/cli/format-event.ts b/packages/adapters/kimi-local/src/cli/format-event.ts
new file mode 100644
index 0000000000..4911ac6d18
--- /dev/null
+++ b/packages/adapters/kimi-local/src/cli/format-event.ts
@@ -0,0 +1,94 @@
+import pc from "picocolors";
+import { printAcpxStreamEvent } from "@paperclipai/adapter-utils/acpx-engine/cli";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function stringifyUnknown(value: unknown): string {
+ if (typeof value === "string") return value;
+ if (value === null || value === undefined) return "";
+ try {
+ return JSON.stringify(value, null, 2);
+ } catch {
+ return String(value);
+ }
+}
+
+export function printKimiStreamEvent(raw: string, _debug: boolean): void {
+ const line = raw.trim();
+ if (!line) return;
+
+ let parsed: Record<string, unknown> | null = null;
+ try {
+ parsed = JSON.parse(line) as Record<string, unknown>;
+ } catch {
+ console.log(line);
+ return;
+ }
+
+ if (asString(parsed.type).startsWith("acpx.")) {
+ printAcpxStreamEvent(line, _debug);
+ return;
+ }
+
+ const role = asString(parsed.role).trim().toLowerCase();
+
+ if (role === "assistant") {
+ const content = asString(parsed.content).trim();
+ if (content) console.log(pc.green(`assistant: ${content}`));
+ const toolCalls = Array.isArray(parsed.tool_calls) ? parsed.tool_calls : [];
+ for (const callRaw of toolCalls) {
+ const call = asRecord(callRaw);
+ if (!call) continue;
+ const fn = asRecord(call.function);
+ const name = asString(fn?.name, asString(call.name, "tool")).trim() || "tool";
+ console.log(pc.yellow(`tool_call: ${name}`));
+ const argsRaw = fn?.arguments ?? call.arguments;
+ if (argsRaw === undefined) continue;
+ if (typeof argsRaw === "string") {
+ try {
+ console.log(pc.gray(stringifyUnknown(JSON.parse(argsRaw))));
+ } catch {
+ console.log(pc.gray(argsRaw));
+ }
+ } else {
+ console.log(pc.gray(stringifyUnknown(argsRaw)));
+ }
+ }
+ return;
+ }
+
+ if (role === "tool") {
+ console.log(pc.cyan("tool_result"));
+ const content = asString(parsed.content) || stringifyUnknown(parsed.content);
+ if (content) console.log(pc.gray(content));
+ return;
+ }
+
+ if (role === "meta") {
+ const type = asString(parsed.type).trim();
+ if (type === "session.resume_hint") {
+ const sessionId = asString(parsed.session_id).trim();
+ if (sessionId) console.log(pc.blue(`Kimi session: ${sessionId}`));
+ }
+ return;
+ }
+
+ if (role === "error" || asString(parsed.type).trim().toLowerCase() === "error") {
+ const text =
+ asString(parsed.content) ||
+ asString(parsed.message) ||
+ asString(parsed.error) ||
+ "Kimi error";
+ console.log(pc.red(`error: ${text}`));
+ return;
+ }
+
+ console.log(line);
+}
diff --git a/packages/adapters/kimi-local/src/cli/index.ts b/packages/adapters/kimi-local/src/cli/index.ts
new file mode 100644
index 0000000000..d3b8f24b6f
--- /dev/null
+++ b/packages/adapters/kimi-local/src/cli/index.ts
@@ -0,0 +1 @@
+export { printKimiStreamEvent } from "./format-event.js";
diff --git a/packages/adapters/kimi-local/src/index.ts b/packages/adapters/kimi-local/src/index.ts
new file mode 100644
index 0000000000..a27aded28a
--- /dev/null
+++ b/packages/adapters/kimi-local/src/index.ts
@@ -0,0 +1,84 @@
+import { buildSandboxNpmInstallCommand } from "@paperclipai/adapter-utils";
+
+export const type = "kimi_local";
+export const label = "Kimi Code CLI (local)";
+
+export const SANDBOX_INSTALL_COMMAND = buildSandboxNpmInstallCommand("@moonshot-ai/kimi-code");
+
+export const DEFAULT_KIMI_LOCAL_MODEL = "kimi-code/kimi-for-coding";
+
+export const models = [
+ { id: DEFAULT_KIMI_LOCAL_MODEL, label: "K2.7 Coding" },
+ { id: "kimi-code/kimi-for-coding-highspeed", label: "K2.7 Coding Highspeed" },
+ { id: "kimi-code/k3", label: "K3" },
+];
+
+/**
+ * Kimi thinking-effort tiers. Kimi's catalog exposes these via each model's
+ * `support_efforts`; note there is no "medium" tier (Kimi collapses it onto
+ * "high"). Sending an effort a model does not support makes the provider
+ * reject the request, so effort is only forwarded for effort-capable models.
+ */
+export const KIMI_SUPPORTED_EFFORTS = ["low", "high", "max"] as const;
+export type KimiEffort = (typeof KIMI_SUPPORTED_EFFORTS)[number];
+
+/**
+ * Models that advertise `support_efforts` in Kimi's model catalog. Keep in
+ * sync with `models` above; only these accept KIMI_MODEL_THINKING_EFFORT.
+ */
+export const EFFORT_CAPABLE_MODELS = new Set<string>(["kimi-code/k3"]);
+
+export function modelSupportsEffort(model: string): boolean {
+ return EFFORT_CAPABLE_MODELS.has(model.trim());
+}
+
+/**
+ * Map a Paperclip effort value onto Kimi's supported thinking-effort set.
+ * Returns null for values Kimi cannot honor so the caller leaves Kimi's own
+ * default_effort in place instead of forwarding an invalid tier.
+ */
+export function resolveKimiThinkingEffort(effort: string): KimiEffort | null {
+ const normalized = effort.trim().toLowerCase();
+ if (!normalized) return null;
+ if (normalized === "medium") return "high";
+ return (KIMI_SUPPORTED_EFFORTS as readonly string[]).includes(normalized)
+ ? (normalized as KimiEffort)
+ : null;
+}
+
+export const agentConfigurationDoc = `# kimi_local agent configuration
+
+Adapter: kimi_local
+
+Use when:
+- You want Paperclip to run the Kimi Code CLI (kimi) locally on the host machine
+- You want Kimi sessions resumed across heartbeats with -r
+- You want Paperclip skills injected into the Kimi skills home without polluting the agent workspace
+
+Don't use when:
+- You need webhook-style external invocation (use http or openclaw_gateway)
+- You only need a one-shot script without an AI coding agent loop (use process)
+- Kimi Code CLI is not installed on the machine that runs Paperclip
+
+Core fields:
+- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
+- instructionsFilePath (string, optional): absolute path to a markdown instructions file prepended to the run prompt. Sibling files in the same directory (HEARTBEAT.md, SOUL.md, TOOLS.md) are made readable via --add-dir for local runs.
+- promptTemplate (string, optional): run prompt template
+- model (string, optional): Kimi model alias (provider/model). Defaults to kimi-code/kimi-for-coding.
+- effort (string, optional): thinking effort (low | medium | high | max). CLI lane only (engine=cli or the automatic fallback): forwarded as KIMI_MODEL_THINKING_EFFORT for effort-capable models (currently kimi-code/k3); "medium" maps to "high" since Kimi has no medium tier. Ignored for models without support_efforts, and NOT forwarded on the default ACP engine lane (Kimi ACP exposes a separate "thinking" option that is not wired yet) — pin engine=cli when effort control matters.
+- command (string, optional): defaults to "kimi"
+- extraArgs (string[], optional): additional CLI args
+- env (object, optional): KEY=VALUE environment variables
+
+Operational fields:
+- timeoutSec (number, optional): run timeout in seconds
+- graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- The adapter defaults to the ACP engine (\`kimi acp\`) and falls back to the headless CLI lane when ACP prerequisites are unavailable. Set \`engine\` to \`acp\` or \`cli\` to require a specific lane.
+- CLI-lane runs use \`kimi -p\` with \`--output-format stream-json\` for non-interactive headless execution; the prompt is passed as an argument, not stdin.
+- The adapter sets a headless-safe environment (CI=1, NO_COLOR=1, KIMI_CODE_NO_AUTO_UPDATE=1) so unattended runs never wait on interactive prompts or update preflight.
+- Sessions resume with \`-r <session_id>\` when the stored session cwd matches the current cwd; the session id is captured from the trailing session.resume_hint meta event.
+- Desired Paperclip skills are delivered to local runs via \`--skills-dir\` pointing at a per-run managed directory, so skills load reliably without polluting the user's \`~/.kimi-code/skills\` home. Remote runs sync skills into the remote skills home.
+- Authentication uses \`kimi login\` (OAuth device flow), providers configured in Kimi's config.toml, or the KIMI_MODEL_NAME + KIMI_MODEL_API_KEY environment pair.
+`;
diff --git a/packages/adapters/kimi-local/src/server/acp.test.ts b/packages/adapters/kimi-local/src/server/acp.test.ts
new file mode 100644
index 0000000000..b88c66cd13
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/acp.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest";
+import {
+ buildKimiAcpConfig,
+ nodeVersionMeetsKimiAcpMinimum,
+ resolveKimiExecutionEngine,
+} from "./acp.js";
+
+describe("resolveKimiExecutionEngine", () => {
+ it("defaults to ACP (non-explicit) when engine is unset", () => {
+ expect(resolveKimiExecutionEngine({})).toEqual({ engine: "acp", explicit: false });
+ });
+
+ it("honors an explicit engine=acp", () => {
+ expect(resolveKimiExecutionEngine({ engine: "acp" })).toEqual({ engine: "acp", explicit: true });
+ });
+
+ it("honors an explicit engine=cli", () => {
+ expect(resolveKimiExecutionEngine({ engine: "CLI" })).toEqual({ engine: "cli", explicit: true });
+ });
+
+ it("treats unknown values as the non-explicit ACP default", () => {
+ expect(resolveKimiExecutionEngine({ engine: "nonsense" })).toEqual({ engine: "acp", explicit: false });
+ });
+});
+
+describe("buildKimiAcpConfig", () => {
+ it("targets the kimi agent and derives the `kimi acp` server command from `command`", () => {
+ const out = buildKimiAcpConfig({ command: "kimi", cwd: "/work" });
+ expect(out.agent).toBe("kimi");
+ expect(out.agentCommand).toBe("kimi acp");
+ expect(out.mode).toBe("persistent");
+ expect(out.cwd).toBe("/work");
+ });
+
+ it("prefers an explicit agentCommand override", () => {
+ const out = buildKimiAcpConfig({ command: "kimi", agentCommand: "/opt/kimi acp --foo" });
+ expect(out.agentCommand).toBe("/opt/kimi acp --foo");
+ });
+
+ it("drops the model when it equals the default so ACP uses the agent default", () => {
+ const out = buildKimiAcpConfig({ model: "kimi-code/kimi-for-coding" });
+ expect("model" in out).toBe(false);
+ });
+
+ it("keeps a non-default model", () => {
+ const out = buildKimiAcpConfig({ model: "kimi-code/k3" });
+ expect(out.model).toBe("kimi-code/k3");
+ });
+
+ it("strips CLI-lane effort so ACP is not sent the unsupported `effort` control", () => {
+ const out = buildKimiAcpConfig({ model: "kimi-code/k3", effort: "high", thinkingEffort: "high" });
+ expect("effort" in out).toBe(false);
+ expect("thinkingEffort" in out).toBe(false);
+ });
+
+ it("opts into the shared engine's verbose-backend handling", () => {
+ const out = buildKimiAcpConfig({ command: "kimi" });
+ expect(out.summaryStrategy).toBe("lastOutputSegment");
+ expect(out.coalescePlaceholderToolUpdates).toBe(true);
+ });
+});
+
+describe("nodeVersionMeetsKimiAcpMinimum", () => {
+ it("accepts Node >= 20", () => {
+ expect(nodeVersionMeetsKimiAcpMinimum("v22.0.0")).toBe(true);
+ expect(nodeVersionMeetsKimiAcpMinimum("v20.0.0")).toBe(true);
+ });
+ it("rejects Node < 20", () => {
+ expect(nodeVersionMeetsKimiAcpMinimum("v18.19.0")).toBe(false);
+ });
+});
diff --git a/packages/adapters/kimi-local/src/server/acp.ts b/packages/adapters/kimi-local/src/server/acp.ts
new file mode 100644
index 0000000000..e6a8b8b523
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/acp.ts
@@ -0,0 +1,392 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+ AdapterEnvironmentCheck,
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+ AdapterExecutionContext,
+ AdapterExecutionResult,
+} from "@paperclipai/adapter-utils";
+import {
+ ensureAdapterExecutionTargetCommandResolvable,
+ readAdapterExecutionTarget,
+ resolveAdapterExecutionTargetCwd,
+} from "@paperclipai/adapter-utils/execution-target";
+import {
+ DEFAULT_ACP_ENGINE_MODE,
+ DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS,
+ DEFAULT_ACP_ENGINE_PERMISSION_MODE,
+ DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS,
+} from "@paperclipai/adapter-utils/acpx-engine/constants";
+import type { AcpxEngineExecutorOptions } from "@paperclipai/adapter-utils/acpx-engine/execute";
+import {
+ asNumber,
+ asString,
+ parseObject,
+} from "@paperclipai/adapter-utils/server-utils";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "../index.js";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const packageRootDir = path.resolve(moduleDir, "../..");
+const MIN_ACP_NODE_VERSION = "20.0.0";
+
+export type KimiExecutionEngine = "cli" | "acp";
+
+export interface KimiEngineSelection {
+ engine: KimiExecutionEngine;
+ explicit: boolean;
+ fallbackReason?: string;
+}
+
+type KimiEngineResolutionInput =
+ Pick<AdapterExecutionContext, "config"> &
+ Partial<Pick<AdapterExecutionContext, "executionTarget" | "executionTransport">>;
+
+type KimiAcpExecutorOptions = Omit<
+ AcpxEngineExecutorOptions,
+ "adapterType" | "moduleDir" | "packageRootDir"
+>;
+
+type KimiAcpExecutor = (ctx: AdapterExecutionContext) => Promise<AdapterExecutionResult>;
+
+function normalizeEngine(value: unknown): KimiEngineSelection {
+ const raw = typeof value === "string" ? value.trim().toLowerCase() : "";
+ if (raw === "acp") return { engine: "acp", explicit: true };
+ if (raw === "cli") return { engine: "cli", explicit: true };
+ return { engine: "acp", explicit: false };
+}
+
+export function resolveKimiExecutionEngine(config: Record<string, unknown>): KimiEngineSelection {
+ return normalizeEngine(config.engine);
+}
+
+export async function resolveKimiExecutionEngineForRun(
+ input: KimiEngineResolutionInput,
+): Promise<KimiEngineSelection> {
+ const selection = normalizeEngine(input.config.engine);
+ if (selection.explicit || selection.engine !== "acp") return selection;
+
+ const fallbackReason = await defaultKimiAcpFallbackReason(input);
+ if (!fallbackReason) return selection;
+ return { engine: "cli", explicit: false, fallbackReason };
+}
+
+export function formatKimiAcpFallbackMessage(reason: string): string {
+ return `[paperclip] Kimi ACP default unavailable; falling back to Kimi CLI. ${reason} Set engine=acp to require ACP or engine=cli to silence this fallback.\n`;
+}
+
+function firstNonEmptyString(...values: unknown[]): string | undefined {
+ for (const value of values) {
+ if (typeof value !== "string") continue;
+ const trimmed = value.trim();
+ if (trimmed.length > 0) return trimmed;
+ }
+ return undefined;
+}
+
+export function buildKimiAcpConfig(config: Record<string, unknown>): Record<string, unknown> {
+ const configuredAgentCommand = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+ const configuredKimiCommand = firstNonEmptyString(config.command);
+ const agentCommand = configuredAgentCommand ?? (configuredKimiCommand ? `${configuredKimiCommand} acp` : undefined);
+ const stateDir = firstNonEmptyString(config.stateDir, config.acpStateDir);
+ const mode = firstNonEmptyString(config.mode, config.acpMode) ?? DEFAULT_ACP_ENGINE_MODE;
+ const permissionMode =
+ firstNonEmptyString(config.permissionMode, config.acpPermissionMode) ??
+ DEFAULT_ACP_ENGINE_PERMISSION_MODE;
+ const nonInteractivePermissions =
+ firstNonEmptyString(config.nonInteractivePermissions, config.acpNonInteractivePermissions) ??
+ DEFAULT_ACP_ENGINE_NON_INTERACTIVE_PERMISSIONS;
+ const warmHandleIdleMs =
+ config.warmHandleIdleMs ??
+ config.acpWarmHandleIdleMs ??
+ DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS;
+
+ const next: Record<string, unknown> = {
+ ...config,
+ agent: "kimi",
+ mode,
+ permissionMode,
+ nonInteractivePermissions,
+ warmHandleIdleMs,
+ ...(agentCommand ? { agentCommand } : {}),
+ ...(stateDir ? { stateDir } : {}),
+ };
+ const model = asString(next.model, "").trim();
+ if (!model || model === DEFAULT_KIMI_LOCAL_MODEL) delete next.model;
+ // Kimi's ACP backend advertises a `thinking` config option, not `effort`.
+ // The shared acpx engine only knows the `effort` control key, which Kimi
+ // rejects with ACP_BACKEND_UNSUPPORTED_CONTROL and fails the session. Drop
+ // the CLI-lane effort fields so the ACP session is not configured with an
+ // unsupported control; thinking-effort control remains available on the CLI
+ // lane via KIMI_MODEL_THINKING_EFFORT.
+ delete next.effort;
+ delete next.thinkingEffort;
+ // Kimi streams ~16k text deltas and one tool_call update per argument token
+ // per run (~50x a comparable Claude run). Opt into the shared engine's
+ // verbose-backend handling: the auto-posted run summary becomes the last
+ // output segment instead of the full narration dump, and placeholder-titled
+ // in-progress tool updates are coalesced out of the run log.
+ next.summaryStrategy = "lastOutputSegment";
+ next.coalescePlaceholderToolUpdates = true;
+ return next;
+}
+
+function withKimiAcpDefaults(options: KimiAcpExecutorOptions): AcpxEngineExecutorOptions {
+ return {
+ ...options,
+ adapterType: "kimi_local",
+ moduleDir,
+ packageRootDir,
+ };
+}
+
+export function createKimiAcpExecutor(options: KimiAcpExecutorOptions = {}): KimiAcpExecutor {
+ let executor: KimiAcpExecutor | null = null;
+ return async (ctx) => {
+ let currentExecutor = executor;
+ if (!currentExecutor) {
+ const { createAcpxEngineExecutor } = await import("@paperclipai/adapter-utils/acpx-engine/execute");
+ currentExecutor = createAcpxEngineExecutor(withKimiAcpDefaults(options));
+ executor = currentExecutor;
+ }
+ return currentExecutor({
+ ...ctx,
+ config: buildKimiAcpConfig(ctx.config),
+ });
+ };
+}
+
+function parseVersion(version: string): [number, number, number] {
+ const match = version.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+ if (!match) return [0, 0, 0];
+ return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+export function nodeVersionMeetsKimiAcpMinimum(version = process.version): boolean {
+ const [major, minor, patch] = parseVersion(version);
+ const [minMajor, minMinor, minPatch] = parseVersion(MIN_ACP_NODE_VERSION);
+ if (major !== minMajor) return major > minMajor;
+ if (minor !== minMinor) return minor > minMinor;
+ return patch >= minPatch;
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+ return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+function hasPathSeparator(command: string): boolean {
+ return command.includes("/") || command.includes("\\");
+}
+
+function firstShellToken(command: string): string | null {
+ const trimmed = command.trim();
+ if (!trimmed) return null;
+ if (trimmed.startsWith("'") || trimmed.startsWith("\"")) return null;
+ return trimmed.split(/\s+/, 1)[0] ?? null;
+}
+
+async function findCommandOnPath(binName: string, pathValue = process.env.PATH ?? ""): Promise<string | null> {
+ for (const segment of pathValue.split(path.delimiter)) {
+ if (!segment) continue;
+ const candidate = path.join(segment, binName);
+ if (await pathExists(candidate)) return candidate;
+ }
+ return null;
+}
+
+function resolveConfigPath(config: Record<string, unknown>): string {
+ const envConfig = parseObject(config.env);
+ return typeof envConfig.PATH === "string" && envConfig.PATH.trim().length > 0
+ ? envConfig.PATH
+ : process.env.PATH ?? "";
+}
+
+async function commandIsResolvable(
+ command: string,
+ pathValue = process.env.PATH ?? "",
+ input?: KimiEngineResolutionInput,
+): Promise<boolean> {
+ const token = firstShellToken(command);
+ if (!token) return true;
+ const target = readAdapterExecutionTarget({
+ executionTarget: input?.executionTarget,
+ legacyRemoteExecution: input?.executionTransport?.remoteExecution,
+ });
+ if (target?.kind === "remote") {
+ try {
+ await ensureAdapterExecutionTargetCommandResolvable(
+ token,
+ target,
+ resolveAdapterExecutionTargetCwd(target, asString(input?.config.cwd, ""), process.cwd()),
+ process.env,
+ );
+ return true;
+ } catch {
+ return false;
+ }
+ }
+ if (path.isAbsolute(token) || hasPathSeparator(token)) return pathExists(token);
+ return (await findCommandOnPath(token, pathValue)) !== null;
+}
+
+function resolveKimiAcpCommand(config: Record<string, unknown>): string {
+ const configured = firstNonEmptyString(config.agentCommand, config.acpAgentCommand);
+ if (configured) return configured;
+ const kimiCommand = firstNonEmptyString(config.command) ?? "kimi";
+ return `${kimiCommand} acp`;
+}
+
+function sandboxTargetHasProcessSessionBridge(
+ target: ReturnType<typeof readAdapterExecutionTarget>,
+): boolean {
+ return target?.kind === "remote" && target.transport === "sandbox" && Boolean(target.runner);
+}
+
+async function defaultKimiAcpFallbackReason(
+ input: KimiEngineResolutionInput,
+): Promise<string | null> {
+ const target = readAdapterExecutionTarget({
+ executionTarget: input.executionTarget,
+ legacyRemoteExecution: input.executionTransport?.remoteExecution,
+ });
+ if (target?.kind === "remote" && !sandboxTargetHasProcessSessionBridge(target)) {
+ if (target.transport === "sandbox") {
+ return "Kimi ACP requires a bidirectional remote process target; this sandbox exposes only one-shot command execution.";
+ }
+ return "Kimi ACP supports sandbox remote targets only; this run targets a non-sandbox remote environment.";
+ }
+ if (!nodeVersionMeetsKimiAcpMinimum()) {
+ return `Node ${process.version} does not satisfy Kimi ACP's Node >=${MIN_ACP_NODE_VERSION} prerequisite.`;
+ }
+ const command = resolveKimiAcpCommand(input.config);
+ if (!(await commandIsResolvable(command, resolveConfigPath(input.config), input))) {
+ return `Kimi ACP command is not available: ${command}.`;
+ }
+ return null;
+}
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+ if (checks.some((check) => check.level === "error")) return "fail";
+ if (checks.some((check) => check.level === "warn")) return "warn";
+ return "pass";
+}
+
+function isNonEmpty(value: unknown): value is string {
+ return typeof value === "string" && value.trim().length > 0;
+}
+
+export async function testKimiAcpEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const checks: AdapterEnvironmentCheck[] = [];
+ const config = parseObject(ctx.config);
+ const target = ctx.executionTarget ?? null;
+ const targetIsRemote = target?.kind === "remote";
+
+ checks.push({
+ code: "kimi_engine_selected",
+ level: "info",
+ message: "Execution engine selected: ACP.",
+ hint: "Set engine=cli to use the existing Kimi CLI lane.",
+ });
+
+ if (targetIsRemote) {
+ checks.push({
+ code: "kimi_acp_remote_target",
+ level: "info",
+ message: "Kimi ACP will run against the remote execution environment.",
+ hint: "Remote ACP requires a bidirectional process target such as SSH or Paperclip's sandbox process-session bridge.",
+ });
+ }
+
+ const cwd = asString(config.cwd, process.cwd());
+ try {
+ await fs.mkdir(cwd, { recursive: true });
+ checks.push({
+ code: "kimi_acp_cwd_valid",
+ level: "info",
+ message: `Working directory is valid: ${cwd}`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "kimi_acp_cwd_invalid",
+ level: "error",
+ message: err instanceof Error ? err.message : "Invalid working directory",
+ detail: cwd,
+ });
+ }
+
+ checks.push({
+ code: nodeVersionMeetsKimiAcpMinimum() ? "kimi_acp_node_supported" : "kimi_acp_node_unsupported",
+ level: nodeVersionMeetsKimiAcpMinimum() ? "info" : "error",
+ message: nodeVersionMeetsKimiAcpMinimum()
+ ? `Node ${process.version} satisfies ACP runtime requirements.`
+ : `Node ${process.version} does not satisfy ACP runtime requirements.`,
+ hint: nodeVersionMeetsKimiAcpMinimum()
+ ? undefined
+ : `Run Kimi ACP with Node >=${MIN_ACP_NODE_VERSION} or switch engine=cli.`,
+ });
+
+ const command = resolveKimiAcpCommand(config);
+ const commandResolvable = await commandIsResolvable(command, resolveConfigPath(config), {
+ config,
+ executionTarget: ctx.executionTarget,
+ });
+ checks.push({
+ code: commandResolvable ? "kimi_acp_command_resolvable" : "kimi_acp_command_missing",
+ level: commandResolvable ? "info" : "error",
+ message: commandResolvable
+ ? `Kimi ACP command is executable: ${command}`
+ : `Kimi ACP command is not available: ${command}`,
+ hint: commandResolvable
+ ? undefined
+ : "Install the Kimi Code CLI with ACP support, or set agentCommand to a valid Kimi ACP server command.",
+ });
+
+ const envConfig = parseObject(config.env);
+ const considerHostEnv = !targetIsRemote;
+ const configModelName = envConfig.KIMI_MODEL_NAME;
+ const hostModelName = considerHostEnv ? process.env.KIMI_MODEL_NAME : undefined;
+ const configModelKey = envConfig.KIMI_MODEL_API_KEY;
+ const hostModelKey = considerHostEnv ? process.env.KIMI_MODEL_API_KEY : undefined;
+ if (
+ (isNonEmpty(configModelName) && isNonEmpty(configModelKey)) ||
+ (isNonEmpty(hostModelName) && isNonEmpty(hostModelKey))
+ ) {
+ const source =
+ isNonEmpty(configModelName) && isNonEmpty(configModelKey) ? "adapter config env" : "server environment";
+ checks.push({
+ code: "kimi_acp_credentials_detected",
+ level: "info",
+ message: "Kimi credentials are set for ACP authentication.",
+ detail: `KIMI_MODEL_NAME + KIMI_MODEL_API_KEY detected in ${source}.`,
+ });
+ } else if (!targetIsRemote) {
+ checks.push({
+ code: "kimi_acp_credentials_not_detected",
+ level: "warn",
+ message: "No Kimi ACP credentials were detected.",
+ hint: "Run `kimi login` (OAuth) or set the KIMI_MODEL_NAME + KIMI_MODEL_API_KEY environment pair before starting a Kimi ACP agent.",
+ });
+ }
+
+ const mode = firstNonEmptyString(config.mode, config.acpMode) ?? DEFAULT_ACP_ENGINE_MODE;
+ const warmHandleIdleMs = asNumber(
+ config.warmHandleIdleMs ?? config.acpWarmHandleIdleMs,
+ DEFAULT_ACP_ENGINE_WARM_HANDLE_IDLE_MS,
+ );
+ checks.push({
+ code: "kimi_acp_runtime_scaffold",
+ level: "info",
+ message: "Kimi ACP runtime execution is available through the shared ACP engine.",
+ detail: `mode=${mode}; warmHandleIdleMs=${warmHandleIdleMs}`,
+ });
+
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/kimi-local/src/server/execute.test.ts b/packages/adapters/kimi-local/src/server/execute.test.ts
new file mode 100644
index 0000000000..dafbc212b5
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/execute.test.ts
@@ -0,0 +1,412 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+
+const ensureRuntimeInstalledMock = vi.hoisted(() => vi.fn(async () => {}));
+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));
+const prepareRuntimeMock = vi.hoisted(() => vi.fn(async () => ({
+ workspaceRemoteDir: null,
+ restoreWorkspace: async () => {},
+})));
+const resolveCommandForLogsMock = vi.hoisted(() => vi.fn(async () => "kimi"));
+const runProcessMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
+ adapterExecutionTargetIsRemote: () => false,
+ adapterExecutionTargetRemoteCwd: (_target: unknown, cwd: string) => cwd,
+ overrideAdapterExecutionTargetRemoteCwd: (target: unknown, _cwd: string) => target,
+ adapterExecutionTargetSessionIdentity: () => ({ kind: "local" }),
+ adapterExecutionTargetSessionMatches: () => true,
+ adapterExecutionTargetUsesManagedHome: () => false,
+ adapterExecutionTargetUsesPaperclipBridge: () => false,
+ describeAdapterExecutionTarget: () => "local",
+ ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,
+ ensureAdapterExecutionTargetRuntimeCommandInstalled: ensureRuntimeInstalledMock,
+ prepareAdapterExecutionTargetRuntime: prepareRuntimeMock,
+ readAdapterExecutionTarget: ({ executionTarget }: { executionTarget?: unknown }) => executionTarget ?? { kind: "local" },
+ readAdapterExecutionTargetHomeDir: async () => null,
+ resolveAdapterExecutionTargetCommandForLogs: resolveCommandForLogsMock,
+ resolveAdapterExecutionTargetTimeoutSec: (_target: unknown, timeoutSec: number) => timeoutSec,
+ runAdapterExecutionTargetProcess: runProcessMock,
+ runAdapterExecutionTargetShellCommand: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+ startAdapterExecutionTargetPaperclipBridge: async () => null,
+}));
+
+import { execute } from "./execute.js";
+
+const tempRoots: string[] = [];
+
+async function makeTempRoot() {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-kimi-local-"));
+ tempRoots.push(root);
+ return root;
+}
+
+function makeContext(root: string, overrides: Partial<AdapterExecutionContext> = {}): AdapterExecutionContext {
+ const ctx: AdapterExecutionContext = {
+ runId: "run-1",
+ agent: {
+ id: "agent-1",
+ companyId: "company-1",
+ name: "Kimi Agent",
+ adapterType: "kimi_local",
+ adapterConfig: {},
+ },
+ runtime: {
+ sessionId: null,
+ sessionParams: null,
+ sessionDisplayId: null,
+ taskKey: null,
+ },
+ config: { cwd: root },
+ context: {},
+ authToken: "run-token",
+ onLog: async () => {},
+ ...overrides,
+ };
+ // Default these CLI-lane tests to the CLI engine so they never depend on
+ // whether `kimi` is resolvable on PATH (ACP is the runtime default). Tests
+ // that need ACP can set engine explicitly in their config override.
+ ctx.config = { engine: "cli", ...ctx.config };
+ return ctx;
+}
+
+const KIMI_STDOUT = [
+ JSON.stringify({ role: "assistant", content: "done" }),
+ JSON.stringify({
+ role: "meta",
+ type: "session.resume_hint",
+ session_id: "session_abc-123",
+ command: "kimi -r session_abc-123",
+ }),
+].join("\n");
+
+describe("kimi_local execute", () => {
+ beforeEach(() => {
+ ensureRuntimeInstalledMock.mockClear();
+ ensureCommandMock.mockClear();
+ prepareRuntimeMock.mockClear();
+ resolveCommandForLogsMock.mockClear();
+ runProcessMock.mockReset();
+ });
+
+ afterEach(async () => {
+ await Promise.all(tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+ });
+
+ it("runs kimi headless with stream-json and captures the session id from the meta event", async () => {
+ const root = await makeTempRoot();
+ let seenArgs: string[] = [];
+ let seenEnv: Record<string, string> = {};
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args, options) => {
+ seenArgs = args;
+ seenEnv = options.env;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ const result = await execute(makeContext(root));
+
+ expect(seenArgs[0]).toBe("--output-format");
+ expect(seenArgs[1]).toBe("stream-json");
+ expect(seenArgs).not.toContain("-m");
+ expect(seenArgs).not.toContain("-r");
+ expect(seenArgs[seenArgs.length - 2]).toBe("-p");
+ expect(seenEnv.CI).toBe("1");
+ expect(seenEnv.NO_COLOR).toBe("1");
+ expect(seenEnv.KIMI_CODE_NO_AUTO_UPDATE).toBe("1");
+ expect(result).toMatchObject({
+ exitCode: 0,
+ errorMessage: null,
+ summary: "done",
+ sessionId: "session_abc-123",
+ sessionDisplayId: "session_abc-123",
+ });
+ expect(result.sessionParams).toMatchObject({
+ sessionId: "session_abc-123",
+ cwd: root,
+ });
+ });
+
+ it("forwards streamed stdout lines to onEvent as assistant + tool_call runtime events", async () => {
+ const root = await makeTempRoot();
+ const events: Array<{ eventType: string; message?: string; payload?: Record<string, unknown> }> = [];
+ const stream =
+ `${JSON.stringify({ role: "assistant", content: "Here is my plan" })}\n` +
+ `${JSON.stringify({
+ role: "assistant",
+ content: "running",
+ tool_calls: [{ type: "function", id: "t1", function: { name: "Bash", arguments: "{}" } }],
+ })}\n`;
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ // Split mid-line so the wrapper's newline buffering is exercised across chunks.
+ await options.onLog("stdout", stream.slice(0, 20));
+ await options.onLog("stdout", stream.slice(20));
+ return { exitCode: 0, signal: null, timedOut: false, stdout: stream, stderr: "" };
+ });
+
+ await execute(makeContext(root, { onEvent: async (event) => { events.push(event); } }));
+
+ expect(events).toContainEqual({
+ eventType: "assistant",
+ stream: "stdout",
+ message: "Here is my plan",
+ payload: { content: "Here is my plan" },
+ });
+ expect(events).toContainEqual({ eventType: "tool_call", stream: "stdout", payload: { toolName: "Bash" } });
+ });
+
+ it("forwards the final stdout line to onEvent even without a trailing newline", async () => {
+ const root = await makeTempRoot();
+ const events: Array<{ eventType: string; payload?: Record<string, unknown> }> = [];
+ // Kimi can close stdout after a valid event with no trailing newline; the
+ // forwarder must flush it so the last tool call reaches live status.
+ const stream = `${JSON.stringify({
+ role: "assistant",
+ tool_calls: [{ type: "function", id: "t9", function: { name: "Read", arguments: "{}" } }],
+ })}`;
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ await options.onLog("stdout", stream);
+ return { exitCode: 0, signal: null, timedOut: false, stdout: stream, stderr: "" };
+ });
+
+ await execute(makeContext(root, { onEvent: async (event) => { events.push(event); } }));
+
+ expect(events).toContainEqual({ eventType: "tool_call", stream: "stdout", payload: { toolName: "Read" } });
+ });
+
+ it("passes -m only when a model is configured", async () => {
+ const root = await makeTempRoot();
+ let seenArgs: string[] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgs = args;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, { config: { cwd: root, model: "kimi-code/k3" } }));
+
+ expect(seenArgs).toContain("-m");
+ expect(seenArgs[seenArgs.indexOf("-m") + 1]).toBe("kimi-code/k3");
+ });
+
+ it("resumes with -r when the stored session cwd matches the run cwd", async () => {
+ const root = await makeTempRoot();
+ let seenArgs: string[] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgs = args;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, {
+ runtime: {
+ sessionId: "session_abc-123",
+ sessionParams: { sessionId: "session_abc-123", cwd: root },
+ sessionDisplayId: "session_abc-123",
+ taskKey: null,
+ },
+ }));
+
+ expect(seenArgs).toContain("-r");
+ expect(seenArgs[seenArgs.indexOf("-r") + 1]).toBe("session_abc-123");
+ });
+
+ it("starts a fresh session when the stored session cwd differs", async () => {
+ const root = await makeTempRoot();
+ let seenArgs: string[] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgs = args;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, {
+ runtime: {
+ sessionId: "session_abc-123",
+ sessionParams: { sessionId: "session_abc-123", cwd: "/some/other/dir" },
+ sessionDisplayId: "session_abc-123",
+ taskKey: null,
+ },
+ }));
+
+ expect(seenArgs).not.toContain("-r");
+ });
+
+ it("retries fresh when the resume session is unrecoverable", async () => {
+ const root = await makeTempRoot();
+ const seenArgLists: string[][] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgLists.push(args);
+ if (seenArgLists.length === 1) {
+ return { exitCode: 1, signal: null, timedOut: false, stdout: "", stderr: "Error: unknown session 'session_stale'" };
+ }
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ const result = await execute(makeContext(root, {
+ runtime: {
+ sessionId: "session_stale",
+ sessionParams: { sessionId: "session_stale", cwd: root },
+ sessionDisplayId: "session_stale",
+ taskKey: null,
+ },
+ }));
+
+ expect(runProcessMock).toHaveBeenCalledTimes(2);
+ expect(seenArgLists[0]).toContain("-r");
+ expect(seenArgLists[1]).not.toContain("-r");
+ expect(result).toMatchObject({ exitCode: 0, sessionId: "session_abc-123" });
+ });
+
+ it("maps auth failures to the kimi_auth_required error code", async () => {
+ const root = await makeTempRoot();
+ runProcessMock.mockImplementation(async () => ({
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "Error: 401 Unauthorized — run kimi login to authenticate",
+ }));
+
+ const result = await execute(makeContext(root));
+
+ expect(result.exitCode).toBe(1);
+ expect(result.errorCode).toBe("kimi_auth_required");
+ expect(result.errorMessage).toBeTruthy();
+ });
+
+ it("reports a timeout when the process exceeds timeoutSec", async () => {
+ const root = await makeTempRoot();
+ runProcessMock.mockImplementation(async () => ({
+ exitCode: null,
+ signal: "SIGTERM",
+ timedOut: true,
+ stdout: "",
+ stderr: "",
+ }));
+
+ const result = await execute(makeContext(root, { config: { cwd: root, timeoutSec: 5 } }));
+
+ expect(result.timedOut).toBe(true);
+ expect(result.errorMessage).toContain("5s");
+ });
+
+ it("reports failure when the process is killed by a signal without timing out", async () => {
+ const root = await makeTempRoot();
+ runProcessMock.mockImplementation(async () => ({
+ exitCode: null,
+ signal: "SIGKILL",
+ timedOut: false,
+ stdout: "",
+ stderr: "",
+ }));
+
+ const result = await execute(makeContext(root));
+
+ expect(result.timedOut).toBe(false);
+ expect(result.errorMessage).toContain("SIGKILL");
+ expect(result.errorMessage).not.toBeNull();
+ });
+
+ it("preserves user-configured headless env values", async () => {
+ const root = await makeTempRoot();
+ let seenEnv: Record<string, string> = {};
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ seenEnv = options.env;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, {
+ config: {
+ cwd: root,
+ env: {
+ CI: "0",
+ NO_COLOR: "0",
+ KIMI_CODE_NO_AUTO_UPDATE: "0",
+ TERM: "xterm-256color",
+ },
+ },
+ }));
+
+ expect(seenEnv.CI).toBe("0");
+ expect(seenEnv.NO_COLOR).toBe("0");
+ expect(seenEnv.KIMI_CODE_NO_AUTO_UPDATE).toBe("0");
+ expect(seenEnv.TERM).toBe("xterm-256color");
+ });
+
+ it("forwards configured effort as KIMI_MODEL_THINKING_EFFORT for effort-capable models", async () => {
+ const root = await makeTempRoot();
+ let seenEnv: Record<string, string> = {};
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ seenEnv = options.env;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, { config: { cwd: root, model: "kimi-code/k3", effort: "high" } }));
+
+ expect(seenEnv.KIMI_MODEL_THINKING_EFFORT).toBe("high");
+ });
+
+ it("maps the medium effort tier onto high since Kimi has no medium", async () => {
+ const root = await makeTempRoot();
+ let seenEnv: Record<string, string> = {};
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ seenEnv = options.env;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, { config: { cwd: root, model: "kimi-code/k3", effort: "medium" } }));
+
+ expect(seenEnv.KIMI_MODEL_THINKING_EFFORT).toBe("high");
+ });
+
+ it("does not forward effort for models without support_efforts", async () => {
+ const root = await makeTempRoot();
+ let seenEnv: Record<string, string> = {};
+ runProcessMock.mockImplementation(async (_runId, _target, _command, _args, options) => {
+ seenEnv = options.env;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, {
+ config: { cwd: root, model: "kimi-code/kimi-for-coding", effort: "high" },
+ }));
+
+ expect(seenEnv.KIMI_MODEL_THINKING_EFFORT).toBeUndefined();
+ });
+
+ it("adds --add-dir for the instructions directory and names sibling files in the prompt", async () => {
+ const root = await makeTempRoot();
+ const instructionsDir = path.join(root, "instructions");
+ await fs.mkdir(instructionsDir, { recursive: true });
+ const instructionsFilePath = path.join(instructionsDir, "AGENTS.md");
+ await fs.writeFile(instructionsFilePath, "# Role\nYou are the lead agent.\n");
+
+ let seenArgs: string[] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgs = args;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, { config: { cwd: root, instructionsFilePath } }));
+
+ expect(seenArgs).toContain("--add-dir");
+ expect(seenArgs[seenArgs.indexOf("--add-dir") + 1]).toBe(instructionsDir);
+ const prompt = seenArgs[seenArgs.length - 1];
+ expect(prompt).toContain("./HEARTBEAT.md");
+ expect(prompt).toContain("./SOUL.md");
+ expect(prompt).toContain("./TOOLS.md");
+ });
+
+ it("does not pass --skills-dir when no skills are desired", async () => {
+ const root = await makeTempRoot();
+ let seenArgs: string[] = [];
+ runProcessMock.mockImplementation(async (_runId, _target, _command, args) => {
+ seenArgs = args;
+ return { exitCode: 0, signal: null, timedOut: false, stdout: KIMI_STDOUT, stderr: "" };
+ });
+
+ await execute(makeContext(root, { config: { cwd: root, model: "kimi-code/k3" } }));
+
+ expect(seenArgs).not.toContain("--skills-dir");
+ });
+});
diff --git a/packages/adapters/kimi-local/src/server/execute.ts b/packages/adapters/kimi-local/src/server/execute.ts
new file mode 100644
index 0000000000..1b6f332db9
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/execute.ts
@@ -0,0 +1,726 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import {
+ adapterExecutionTargetIsRemote,
+ adapterExecutionTargetRemoteCwd,
+ overrideAdapterExecutionTargetRemoteCwd,
+ adapterExecutionTargetSessionIdentity,
+ adapterExecutionTargetSessionMatches,
+ adapterExecutionTargetUsesManagedHome,
+ adapterExecutionTargetUsesPaperclipBridge,
+ describeAdapterExecutionTarget,
+ ensureAdapterExecutionTargetCommandResolvable,
+ ensureAdapterExecutionTargetRuntimeCommandInstalled,
+ prepareAdapterExecutionTargetRuntime,
+ readAdapterExecutionTarget,
+ resolveAdapterExecutionTargetTimeoutSec,
+ resolveAdapterExecutionTargetCommandForLogs,
+ runAdapterExecutionTargetProcess,
+ startAdapterExecutionTargetPaperclipBridge,
+} from "@paperclipai/adapter-utils/execution-target";
+import {
+ asNumber,
+ asString,
+ asStringArray,
+ buildPaperclipEnv,
+ buildInvocationEnvForLogs,
+ ensureAbsoluteDirectory,
+ joinPromptSections,
+ ensurePathInEnv,
+ refreshPaperclipWorkspaceEnvForExecution,
+ readPaperclipRuntimeSkillEntries,
+ readPaperclipIssueWorkModeFromContext,
+ resolvePaperclipDesiredSkillNames,
+ parseObject,
+ renderTemplate,
+ renderPaperclipWakePrompt,
+ isPaperclipRecoveryWakePayload,
+ stringifyPaperclipWakePayload,
+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+} from "@paperclipai/adapter-utils/server-utils";
+import {
+ SANDBOX_INSTALL_COMMAND,
+ modelSupportsEffort,
+ resolveKimiThinkingEffort,
+} from "../index.js";
+import {
+ describeKimiFailure,
+ detectKimiAuthRequired,
+ extractKimiRuntimeEvents,
+ isKimiSessionUnrecoverableError,
+ isKimiTransientNetworkError,
+ parseKimiJsonl,
+} from "./parse.js";
+import {
+ createKimiAcpExecutor,
+ formatKimiAcpFallbackMessage,
+ resolveKimiExecutionEngineForRun,
+} from "./acp.js";
+import { firstNonEmptyLine } from "./utils.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+const executeKimiAcp = createKimiAcpExecutor();
+
+/**
+ * Wrap `onLog` so each complete kimi stream-json stdout line is also mapped to
+ * `onEvent` runtime events (assistant snippet, tool name). This keeps the raw
+ * run log intact while lighting up the issue-thread activity indicator, which
+ * reads `currentToolName` / `lastAssistantSnippet` / `lastEventAt` derived from
+ * `onEvent` rather than from the raw log stream. Stdout arrives in arbitrary
+ * chunks, so lines are buffered and split on newlines. `flush` must be called
+ * once the process exits so the final line reaches `onEvent` even when kimi
+ * closes stdout without a trailing newline (otherwise the last assistant
+ * message or tool call would be missing from live status).
+ */
+function createKimiEventForwardingLog(
+ onLog: AdapterExecutionContext["onLog"],
+ onEvent: AdapterExecutionContext["onEvent"],
+): { log: AdapterExecutionContext["onLog"]; flush: () => Promise<void> } {
+ if (!onEvent) return { log: onLog, flush: async () => {} };
+ let buffer = "";
+ const emitLine = async (raw: string): Promise<void> => {
+ const line = raw.trim();
+ if (!line) return;
+ for (const event of extractKimiRuntimeEvents(line)) {
+ await onEvent({ eventType: event.eventType, stream: "stdout", message: event.message, payload: event.payload });
+ }
+ };
+ return {
+ log: async (stream, chunk) => {
+ await onLog(stream, chunk);
+ if (stream !== "stdout") return;
+ buffer += chunk;
+ let newlineIndex: number;
+ while ((newlineIndex = buffer.indexOf("\n")) !== -1) {
+ const line = buffer.slice(0, newlineIndex);
+ buffer = buffer.slice(newlineIndex + 1);
+ await emitLine(line);
+ }
+ },
+ flush: async () => {
+ const remaining = buffer;
+ buffer = "";
+ await emitLine(remaining);
+ },
+ };
+}
+
+function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
+ const raw = env[key];
+ return typeof raw === "string" && raw.trim().length > 0;
+}
+
+function resolveKimiBillingType(env: Record<string, string>): "api" | "subscription" {
+ return hasNonEmptyEnvValue(env, "KIMI_MODEL_API_KEY") ? "api" : "subscription";
+}
+
+/**
+ * Headless-safe environment for unattended `kimi -p` runs. CI=1 disables
+ * theme detection, NO_COLOR=1 keeps stdout parseable, and
+ * KIMI_CODE_NO_AUTO_UPDATE=1 skips the update preflight. User-configured
+ * values always win.
+ */
+function buildKimiHeadlessEnv(env: Record<string, string>): Record<string, string> {
+ const next = { ...env };
+ if (!next.CI?.trim()) next.CI = "1";
+ if (!next.NO_COLOR?.trim()) next.NO_COLOR = "1";
+ if (!next.KIMI_CODE_NO_AUTO_UPDATE?.trim()) next.KIMI_CODE_NO_AUTO_UPDATE = "1";
+ if (!next.TERM?.trim()) next.TERM = "dumb";
+ return next;
+}
+
+function buildKimiRuntimeEnv(env: Record<string, string>): Record<string, string> {
+ return Object.fromEntries(
+ Object.entries(ensurePathInEnv({ ...process.env, ...buildKimiHeadlessEnv(env) })).filter(
+ (entry): entry is [string, string] => typeof entry[1] === "string",
+ ),
+ );
+}
+
+function renderPaperclipEnvNote(env: Record<string, string>): string {
+ const paperclipKeys = Object.keys(env)
+ .filter((key) => key.startsWith("PAPERCLIP_"))
+ .sort();
+ if (paperclipKeys.length === 0) return "";
+ return [
+ "Paperclip runtime note:",
+ `The following PAPERCLIP_* environment variables are available in this run: ${paperclipKeys.join(", ")}`,
+ "Do not assume these variables are missing without checking your shell environment.",
+ "",
+ "",
+ ].join("\n");
+}
+
+function renderApiAccessNote(env: Record<string, string>): string {
+ if (!hasNonEmptyEnvValue(env, "PAPERCLIP_API_URL") || !hasNonEmptyEnvValue(env, "PAPERCLIP_API_KEY")) return "";
+ return [
+ "Paperclip API access note:",
+ "Use shell commands with curl to make Paperclip API requests when needed.",
+ "Include X-Paperclip-Run-Id on mutating requests.",
+ "",
+ "",
+ ].join("\n");
+}
+
+async function buildKimiSkillsDir(
+ config: Record<string, unknown>,
+): Promise<string> {
+ const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-kimi-skills-"));
+ const target = path.join(tmp, "skills");
+ await fs.mkdir(target, { recursive: true });
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));
+ for (const entry of availableEntries) {
+ if (!desiredNames.has(entry.key)) continue;
+ await fs.symlink(entry.source, path.join(target, entry.runtimeName));
+ }
+ return target;
+}
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+ const engineSelection = await resolveKimiExecutionEngineForRun(ctx);
+ if (engineSelection.engine === "acp") {
+ try {
+ return await executeKimiAcp(ctx);
+ } catch (err) {
+ // An explicitly requested ACP engine surfaces its failure; the default
+ // (auto) selection falls back to the CLI lane with a diagnostic note.
+ if (engineSelection.explicit) throw err;
+ const reason = err instanceof Error ? err.message : String(err);
+ await ctx.onLog("stderr", formatKimiAcpFallbackMessage(`Kimi ACP startup failed: ${reason}`));
+ }
+ } else if (!engineSelection.explicit && engineSelection.fallbackReason) {
+ await ctx.onLog("stderr", formatKimiAcpFallbackMessage(engineSelection.fallbackReason));
+ }
+
+ const { runId, agent, runtime, config, context, onLog, onMeta, onEvent, onSpawn, authToken } = ctx;
+ const executionTarget = readAdapterExecutionTarget({
+ executionTarget: ctx.executionTarget,
+ legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
+ });
+ const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
+
+ const promptTemplate = asString(
+ config.promptTemplate,
+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+ );
+ const command = asString(config.command, "kimi");
+ const model = asString(config.model, "").trim();
+
+ const workspaceContext = parseObject(context.paperclipWorkspace);
+ const workspaceCwd = asString(workspaceContext.cwd, "");
+ const workspaceSource = asString(workspaceContext.source, "");
+ const workspaceId = asString(workspaceContext.workspaceId, "");
+ const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+ const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+ const agentHome = asString(workspaceContext.agentHome, "");
+ const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+ ? context.paperclipWorkspaces.filter(
+ (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
+ )
+ : [];
+ const configuredCwd = asString(config.cwd, "");
+ const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+ const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+ const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+ let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+ await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+ const kimiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredKimiSkillNames = resolvePaperclipDesiredSkillNames(config, kimiSkillEntries);
+ const envConfig = parseObject(config.env);
+
+ const hasExplicitApiKey =
+ typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
+ const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+ env.PAPERCLIP_RUN_ID = runId;
+ const wakeTaskId =
+ (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
+ (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
+ null;
+ const wakeReason =
+ typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
+ ? context.wakeReason.trim()
+ : null;
+ const wakeCommentId =
+ (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
+ (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
+ null;
+ const approvalId =
+ typeof context.approvalId === "string" && context.approvalId.trim().length > 0
+ ? context.approvalId.trim()
+ : null;
+ const approvalStatus =
+ typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
+ ? context.approvalStatus.trim()
+ : null;
+ const linkedIssueIds = Array.isArray(context.issueIds)
+ ? context.issueIds.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+ : [];
+ const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+ const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
+ if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+ if (issueWorkMode) env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
+ if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
+ if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+ if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
+ if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+ if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+ if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
+ refreshPaperclipWorkspaceEnvForExecution({
+ env,
+ envConfig,
+ workspaceCwd: effectiveWorkspaceCwd,
+ workspaceSource,
+ workspaceId,
+ workspaceRepoUrl,
+ workspaceRepoRef,
+ workspaceHints,
+ agentHome,
+ executionTargetIsRemote,
+ executionCwd: effectiveExecutionCwd,
+ });
+ if (!hasExplicitApiKey && authToken) {
+ env.PAPERCLIP_API_KEY = authToken;
+ }
+ // Forward configured thinking effort as KIMI_MODEL_THINKING_EFFORT. Kimi has
+ // no per-invocation effort flag; this env var is an operational override that
+ // applies to Kimi providers (managed OAuth models included). Only send it for
+ // models that advertise support_efforts, and never clobber an explicit value.
+ const configuredEffort = asString(config.effort, "").trim();
+ if (configuredEffort && modelSupportsEffort(model) && !hasNonEmptyEnvValue(env, "KIMI_MODEL_THINKING_EFFORT")) {
+ const kimiEffort = resolveKimiThinkingEffort(configuredEffort);
+ if (kimiEffort) env.KIMI_MODEL_THINKING_EFFORT = kimiEffort;
+ }
+ const runtimeEnv = buildKimiRuntimeEnv(env);
+ const billingType = resolveKimiBillingType(runtimeEnv);
+ const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(
+ executionTarget,
+ asNumber(config.timeoutSec, 0),
+ );
+ const graceSec = asNumber(config.graceSec, 20);
+ await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+ runId,
+ target: executionTarget,
+ installCommand: ctx.runtimeCommandSpec?.installCommand,
+ detectCommand: ctx.runtimeCommandSpec?.detectCommand,
+ cwd,
+ env: runtimeEnv,
+ timeoutSec,
+ graceSec,
+ onLog,
+ });
+ await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
+ installCommand: SANDBOX_INSTALL_COMMAND,
+ timeoutSec,
+ });
+ const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
+ const extraArgs = (() => {
+ const fromExtraArgs = asStringArray(config.extraArgs);
+ if (fromExtraArgs.length > 0) return fromExtraArgs;
+ return asStringArray(config.args);
+ })();
+ let restoreRemoteWorkspace: (() => Promise<void>) | null = null;
+ let localSkillsDir: string | null = null;
+ let remoteSkillsDir: string | null = null;
+ let remoteRuntimeRootDir: string | null = null;
+ let paperclipBridge: Awaited<ReturnType<typeof startAdapterExecutionTargetPaperclipBridge>> = null;
+
+ if (executionTargetIsRemote) {
+ try {
+ localSkillsDir = await buildKimiSkillsDir(config);
+ await onLog(
+ "stdout",
+ `[paperclip] Syncing workspace and Kimi runtime assets to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
+ );
+ const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
+ runId,
+ target: executionTarget,
+ adapterKey: "kimi",
+ timeoutSec,
+ workspaceLocalDir: cwd,
+ installCommand: SANDBOX_INSTALL_COMMAND,
+ detectCommand: command,
+ onProgress: (line) => onLog("stdout", line),
+ onRuntimeProgress: ctx.onRuntimeProgress,
+ assets: [{
+ key: "skills",
+ localDir: localSkillsDir,
+ followSymlinks: true,
+ }],
+ });
+ restoreRemoteWorkspace = () =>
+ preparedExecutionTargetRuntime.restoreWorkspace((line) => onLog("stdout", line));
+ effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
+ refreshPaperclipWorkspaceEnvForExecution({
+ env,
+ envConfig,
+ workspaceCwd: effectiveWorkspaceCwd,
+ workspaceSource,
+ workspaceId,
+ workspaceRepoUrl,
+ workspaceRepoRef,
+ workspaceHints,
+ agentHome,
+ executionTargetIsRemote,
+ executionCwd: effectiveExecutionCwd,
+ });
+ remoteRuntimeRootDir = preparedExecutionTargetRuntime.runtimeRootDir;
+ const managedHome = adapterExecutionTargetUsesManagedHome(executionTarget);
+ const managedRemoteHomeDir =
+ managedHome && preparedExecutionTargetRuntime.runtimeRootDir
+ ? preparedExecutionTargetRuntime.runtimeRootDir
+ : null;
+ if (managedRemoteHomeDir) {
+ env.HOME = managedRemoteHomeDir;
+ }
+ // Deliver the synced skills snapshot via --skills-dir (see buildArgs)
+ // from its isolated per-run location instead of copying it over the
+ // shared $KIMI_CODE_HOME/skills home. Overwriting the shared home would
+ // delete Kimi skills installed by the operator or other agents that
+ // Paperclip does not own.
+ if (desiredKimiSkillNames.length > 0 && preparedExecutionTargetRuntime.assetDirs.skills) {
+ remoteSkillsDir = preparedExecutionTargetRuntime.assetDirs.skills;
+ }
+ } catch (error) {
+ await Promise.allSettled([
+ restoreRemoteWorkspace?.(),
+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
+ ]);
+ throw error;
+ }
+ }
+ const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
+ if (executionTargetIsRemote && adapterExecutionTargetUsesPaperclipBridge(executionTarget)) {
+ paperclipBridge = await startAdapterExecutionTargetPaperclipBridge({
+ runId,
+ target: runtimeExecutionTarget,
+ runtimeRootDir: remoteRuntimeRootDir,
+ adapterKey: "kimi",
+ timeoutSec,
+ hostApiToken: env.PAPERCLIP_API_KEY,
+ onLog,
+ });
+ if (paperclipBridge) {
+ Object.assign(env, paperclipBridge.env);
+ }
+ }
+
+ // Local runs deliver desired skills via `--skills-dir` (see buildArgs) from a
+ // dedicated per-run directory, rather than symlinking into the user's
+ // ~/.kimi-code/skills home. This keeps skill loading reliable and isolated
+ // without polluting the operator's Kimi install. Remote runs sync skills into
+ // the remote skills home above, so this only applies to local execution.
+ if (!executionTargetIsRemote && desiredKimiSkillNames.length > 0) {
+ localSkillsDir = await buildKimiSkillsDir(config);
+ await onLog(
+ "stderr",
+ `[paperclip] Prepared ${desiredKimiSkillNames.length} Kimi skill(s) for --skills-dir delivery.\n`,
+ );
+ }
+
+ const runtimeSessionParams = parseObject(runtime.sessionParams);
+ const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+ const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+ const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
+ const canResumeSession =
+ runtimeSessionId.length > 0 &&
+ (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
+ adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
+ const sessionId = canResumeSession ? runtimeSessionId : null;
+ if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
+ await onLog(
+ "stdout",
+ `[paperclip] Kimi session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
+ );
+ } else if (runtimeSessionId && !canResumeSession) {
+ await onLog(
+ "stdout",
+ `[paperclip] Kimi session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
+ );
+ }
+
+ const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+ const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
+ let instructionsPrefix = "";
+ if (instructionsFilePath) {
+ try {
+ const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
+ instructionsPrefix =
+ `${instructionsContents}\n\n` +
+ `The above agent instructions were loaded from ${instructionsFilePath}. ` +
+ `Resolve any relative file references from ${instructionsDir}. ` +
+ `This base directory is authoritative for sibling instruction files such as ` +
+ `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.\n\n`;
+ } catch (err) {
+ const reason = err instanceof Error ? err.message : String(err);
+ await onLog(
+ "stdout",
+ `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
+ );
+ }
+ }
+ const commandNotes = (() => {
+ const notes: string[] = ["Prompt is passed to Kimi via -p for non-interactive execution."];
+ notes.push("Added --output-format stream-json for structured headless output.");
+ notes.push("Set headless env (CI=1, NO_COLOR=1, KIMI_CODE_NO_AUTO_UPDATE=1) so unattended runs skip interactive prompts and update preflight.");
+ if (hasNonEmptyEnvValue(env, "KIMI_MODEL_THINKING_EFFORT")) {
+ notes.push(`Set KIMI_MODEL_THINKING_EFFORT=${env.KIMI_MODEL_THINKING_EFFORT} for model ${model}.`);
+ }
+ const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
+ if (effectiveSkillsDir) {
+ notes.push(`Loading ${desiredKimiSkillNames.length} desired skill(s) via --skills-dir ${effectiveSkillsDir}.`);
+ }
+ if (!executionTargetIsRemote && instructionsFilePath) {
+ notes.push(`Added --add-dir ${path.dirname(instructionsFilePath)} so sibling instruction files are readable.`);
+ }
+ if (!instructionsFilePath) return notes;
+ if (instructionsPrefix.length > 0) {
+ notes.push(
+ `Loaded agent instructions from ${instructionsFilePath}`,
+ `Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
+ );
+ return notes;
+ }
+ notes.push(
+ `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
+ );
+ return notes;
+ })();
+
+ const bootstrapPromptTemplate = asString(config.bootstrapPromptTemplate, "");
+ const templateData = {
+ agentId: agent.id,
+ companyId: agent.companyId,
+ runId,
+ company: { id: agent.companyId },
+ agent,
+ run: { id: runId, source: "on_demand" },
+ context,
+ };
+ const renderedBootstrapPrompt =
+ !sessionId && bootstrapPromptTemplate.trim().length > 0
+ ? renderTemplate(bootstrapPromptTemplate, templateData).trim()
+ : "";
+ const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, { resumedSession: Boolean(sessionId) });
+ const shouldUseResumeDeltaPrompt = Boolean(sessionId) && wakePrompt.length > 0;
+ const renderedPrompt = shouldUseResumeDeltaPrompt || isPaperclipRecoveryWakePayload(context.paperclipWake)
+ ? ""
+ : renderTemplate(promptTemplate, templateData);
+ const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+ const paperclipEnvNote = renderPaperclipEnvNote(env);
+ const apiAccessNote = renderApiAccessNote(env);
+ const prompt = joinPromptSections([
+ instructionsPrefix,
+ renderedBootstrapPrompt,
+ wakePrompt,
+ sessionHandoffNote,
+ paperclipEnvNote,
+ apiAccessNote,
+ renderedPrompt,
+ ]);
+ const promptMetrics = {
+ promptChars: prompt.length,
+ instructionsChars: instructionsPrefix.length,
+ bootstrapPromptChars: renderedBootstrapPrompt.length,
+ wakePromptChars: wakePrompt.length,
+ sessionHandoffChars: sessionHandoffNote.length,
+ runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
+ heartbeatPromptChars: renderedPrompt.length,
+ };
+
+ const buildArgs = (resumeSessionId: string | null) => {
+ const args = ["--output-format", "stream-json"];
+ if (resumeSessionId) args.push("-r", resumeSessionId);
+ if (model) args.push("-m", model);
+ // Make the agent instructions directory readable so Kimi can open sibling
+ // instruction files (./HEARTBEAT.md, ./SOUL.md, ./TOOLS.md) referenced by
+ // the prepended entry file. Local-only: the directory is a host path that
+ // is not synced to remote execution targets.
+ if (!executionTargetIsRemote && instructionsFilePath) {
+ args.push("--add-dir", path.dirname(instructionsFilePath));
+ }
+ // Load desired Paperclip skills from the dedicated per-run directory
+ // (local snapshot, or the synced remote snapshot) instead of the shared
+ // skills home. Only passed when skills are desired so unconfigured agents
+ // keep Kimi's default skill discovery.
+ const effectiveSkillsDir = executionTargetIsRemote ? remoteSkillsDir : localSkillsDir;
+ if (effectiveSkillsDir) {
+ args.push("--skills-dir", effectiveSkillsDir);
+ }
+ if (extraArgs.length > 0) args.push(...extraArgs);
+ args.push("-p", prompt);
+ return args;
+ };
+
+ const runAttempt = async (resumeSessionId: string | null) => {
+ const args = buildArgs(resumeSessionId);
+ const invocationEnv = buildKimiHeadlessEnv(env);
+ const invocationRuntimeEnv = buildKimiRuntimeEnv(env);
+ const loggedEnv = buildInvocationEnvForLogs(invocationEnv, {
+ runtimeEnv: invocationRuntimeEnv,
+ includeRuntimeKeys: ["HOME"],
+ resolvedCommand,
+ });
+ if (onMeta) {
+ await onMeta({
+ adapterType: "kimi_local",
+ command: resolvedCommand,
+ cwd: effectiveExecutionCwd,
+ commandNotes,
+ commandArgs: args.map((value, index) => (
+ index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
+ )),
+ env: loggedEnv,
+ prompt,
+ promptMetrics,
+ context,
+ });
+ }
+
+ const eventForwarder = createKimiEventForwardingLog(onLog, onEvent);
+ const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
+ cwd,
+ env: invocationEnv,
+ timeoutSec,
+ graceSec,
+ onSpawn,
+ onRuntimeProgress: ctx.onRuntimeProgress,
+ onLog: eventForwarder.log,
+ runLogTail: paperclipBridge?.runLogTail,
+ });
+ await eventForwarder.flush();
+ return {
+ proc,
+ parsed: parseKimiJsonl(proc.stdout),
+ };
+ };
+
+ const toResult = (
+ attempt: {
+ proc: {
+ exitCode: number | null;
+ signal: string | null;
+ timedOut: boolean;
+ stdout: string;
+ stderr: string;
+ };
+ parsed: ReturnType<typeof parseKimiJsonl>;
+ },
+ clearSessionOnMissingSession = false,
+ isRetry = false,
+ ): AdapterExecutionResult => {
+ const authMeta = detectKimiAuthRequired({
+ stdout: attempt.proc.stdout,
+ stderr: attempt.proc.stderr,
+ });
+ const networkUnavailable = isKimiTransientNetworkError(attempt.proc.stdout, attempt.proc.stderr);
+
+ if (attempt.proc.timedOut) {
+ return {
+ exitCode: attempt.proc.exitCode,
+ signal: attempt.proc.signal,
+ timedOut: true,
+ errorMessage: `Timed out after ${timeoutSec}s`,
+ errorCode: authMeta.requiresAuth
+ ? "kimi_auth_required"
+ : networkUnavailable
+ ? "kimi_network_unavailable"
+ : null,
+ clearSession: clearSessionOnMissingSession,
+ };
+ }
+
+ const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
+ const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+ const structuredFailure = describeKimiFailure({
+ errorMessage: attempt.parsed.errorMessage,
+ stderr: attempt.proc.stderr,
+ });
+ const fallbackErrorMessage =
+ parsedError ||
+ structuredFailure ||
+ stderrLine ||
+ (attempt.proc.signal
+ ? `Kimi was terminated by signal ${attempt.proc.signal}`
+ : `Kimi exited with code ${attempt.proc.exitCode ?? -1}`);
+ // A null exit code means the process never exited normally (e.g. killed by
+ // a signal). Timeouts are handled earlier; treat any other non-zero or
+ // null exit as a failure so a signaled kill is never reported as success.
+ const failed = attempt.proc.exitCode === null || attempt.proc.exitCode !== 0;
+
+ // On retry, don't fall back to old session ID — the old session was stale
+ const canFallbackToRuntimeSession = !isRetry;
+ const resolvedSessionId = attempt.parsed.sessionId
+ ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
+ const resolvedSessionParams = resolvedSessionId
+ ? ({
+ sessionId: resolvedSessionId,
+ cwd: effectiveExecutionCwd,
+ ...(workspaceId ? { workspaceId } : {}),
+ ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
+ ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
+ ...(executionTargetIsRemote
+ ? {
+ remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
+ }
+ : {}),
+ } as Record<string, unknown>)
+ : null;
+ const resultJson: Record<string, unknown> = {
+ toolCalls: attempt.parsed.toolCalls,
+ toolResults: attempt.parsed.toolResults,
+ ...(failed ? { stderr: attempt.proc.stderr } : {}),
+ };
+
+ return {
+ exitCode: attempt.proc.exitCode,
+ signal: attempt.proc.signal,
+ timedOut: false,
+ errorMessage: failed ? fallbackErrorMessage : null,
+ errorCode: failed && authMeta.requiresAuth
+ ? "kimi_auth_required"
+ : failed && networkUnavailable
+ ? "kimi_network_unavailable"
+ : null,
+ sessionId: resolvedSessionId,
+ sessionParams: resolvedSessionParams,
+ sessionDisplayId: resolvedSessionId,
+ provider: "moonshot",
+ biller: "moonshot",
+ model: model || null,
+ billingType,
+ resultJson,
+ summary: attempt.parsed.summary,
+ clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
+ };
+ };
+
+ try {
+ const initial = await runAttempt(sessionId);
+ if (
+ sessionId &&
+ !initial.proc.timedOut &&
+ (initial.proc.exitCode ?? 0) !== 0 &&
+ isKimiSessionUnrecoverableError(initial.proc.stdout, initial.proc.stderr)
+ ) {
+ await onLog(
+ "stdout",
+ `[paperclip] Kimi resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+ );
+ const retry = await runAttempt(null);
+ return toResult(retry, true, true);
+ }
+
+ return toResult(initial);
+ } finally {
+ await Promise.all([
+ paperclipBridge?.stop(),
+ restoreRemoteWorkspace?.(),
+ localSkillsDir ? fs.rm(path.dirname(localSkillsDir), { recursive: true, force: true }).catch(() => undefined) : Promise.resolve(),
+ ]);
+ }
+}
diff --git a/packages/adapters/kimi-local/src/server/index.ts b/packages/adapters/kimi-local/src/server/index.ts
new file mode 100644
index 0000000000..e9c968f4f8
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/index.ts
@@ -0,0 +1,76 @@
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+import { sessionCodec as acpxSessionCodec } from "@paperclipai/adapter-utils/acpx-engine/session-codec";
+
+function readNonEmptyString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+ deserialize(raw: unknown) {
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+ const record = raw as Record<string, unknown>;
+ const sessionId =
+ readNonEmptyString(record.sessionId) ??
+ readNonEmptyString(record.session_id) ??
+ readNonEmptyString(record.sessionID);
+ if (!sessionId) return acpxSessionCodec.deserialize(raw);
+ const cwd =
+ readNonEmptyString(record.cwd) ??
+ readNonEmptyString(record.workdir) ??
+ readNonEmptyString(record.folder);
+ const workspaceId = readNonEmptyString(record.workspaceId) ?? readNonEmptyString(record.workspace_id);
+ const repoUrl = readNonEmptyString(record.repoUrl) ?? readNonEmptyString(record.repo_url);
+ const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
+ return {
+ sessionId,
+ ...(cwd ? { cwd } : {}),
+ ...(workspaceId ? { workspaceId } : {}),
+ ...(repoUrl ? { repoUrl } : {}),
+ ...(repoRef ? { repoRef } : {}),
+ };
+ },
+ serialize(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ const sessionId =
+ readNonEmptyString(params.sessionId) ??
+ readNonEmptyString(params.session_id) ??
+ readNonEmptyString(params.sessionID);
+ if (!sessionId) return acpxSessionCodec.serialize(params);
+ const cwd =
+ readNonEmptyString(params.cwd) ??
+ readNonEmptyString(params.workdir) ??
+ readNonEmptyString(params.folder);
+ const workspaceId = readNonEmptyString(params.workspaceId) ?? readNonEmptyString(params.workspace_id);
+ const repoUrl = readNonEmptyString(params.repoUrl) ?? readNonEmptyString(params.repo_url);
+ const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
+ return {
+ sessionId,
+ ...(cwd ? { cwd } : {}),
+ ...(workspaceId ? { workspaceId } : {}),
+ ...(repoUrl ? { repoUrl } : {}),
+ ...(repoRef ? { repoRef } : {}),
+ };
+ },
+ getDisplayId(params: Record<string, unknown> | null) {
+ if (!params) return null;
+ return (
+ readNonEmptyString(params.sessionId) ??
+ readNonEmptyString(params.session_id) ??
+ readNonEmptyString(params.sessionID) ??
+ acpxSessionCodec.getDisplayId?.(params) ??
+ null
+ );
+ },
+};
+
+export * from "./acp.js";
+export { execute } from "./execute.js";
+export { listKimiSkills, syncKimiSkills } from "./skills.js";
+export { testEnvironment } from "./test.js";
+export {
+ parseKimiJsonl,
+ isKimiSessionUnrecoverableError,
+ isKimiTransientNetworkError,
+ describeKimiFailure,
+ detectKimiAuthRequired,
+} from "./parse.js";
diff --git a/packages/adapters/kimi-local/src/server/parse.test.ts b/packages/adapters/kimi-local/src/server/parse.test.ts
new file mode 100644
index 0000000000..6ddf80dc2e
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/parse.test.ts
@@ -0,0 +1,198 @@
+import { describe, expect, it } from "vitest";
+import {
+ buildKimiRunSummary,
+ detectKimiAuthRequired,
+ extractKimiRuntimeEvents,
+ isKimiSessionUnrecoverableError,
+ isKimiTransientNetworkError,
+ parseKimiJsonl,
+} from "./parse.js";
+
+describe("extractKimiRuntimeEvents", () => {
+ it("maps assistant content to an assistant snippet event", () => {
+ const events = extractKimiRuntimeEvents('{"role":"assistant","content":"Here is my plan"}');
+ expect(events).toEqual([
+ { eventType: "assistant", message: "Here is my plan", payload: { content: "Here is my plan" } },
+ ]);
+ });
+
+ it("maps tool_calls to tool_call events carrying the tool name", () => {
+ const line =
+ '{"role":"assistant","content":"running","tool_calls":[{"type":"function","id":"t1","function":{"name":"Bash","arguments":"{}"}}]}';
+ const events = extractKimiRuntimeEvents(line);
+ expect(events).toEqual([
+ { eventType: "assistant", message: "running", payload: { content: "running" } },
+ { eventType: "tool_call", payload: { toolName: "Bash" } },
+ ]);
+ });
+
+ it("emits nothing for tool results, meta, and malformed lines", () => {
+ expect(extractKimiRuntimeEvents('{"role":"tool","tool_call_id":"t1","content":"done"}')).toEqual([]);
+ expect(extractKimiRuntimeEvents('{"role":"meta","type":"session.resume_hint","session_id":"s"}')).toEqual([]);
+ expect(extractKimiRuntimeEvents("not json")).toEqual([]);
+ });
+});
+
+describe("parseKimiJsonl", () => {
+ it("collects assistant text from content events", () => {
+ const stdout = [
+ '{"role":"assistant","content":"PAPERCLIP_ADAPTER_TEST_OK"}',
+ '{"role":"meta","type":"session.resume_hint","session_id":"session_769ddab9-0a25-4edd-99f4-cdfebdc90879","command":"kimi -r session_769ddab9-0a25-4edd-99f4-cdfebdc90879","content":"To resume this session: kimi -r session_769ddab9-0a25-4edd-99f4-cdfebdc90879"}',
+ ].join("\n");
+
+ const parsed = parseKimiJsonl(stdout);
+
+ expect(parsed.summary).toBe("PAPERCLIP_ADAPTER_TEST_OK");
+ expect(parsed.sessionId).toBe("session_769ddab9-0a25-4edd-99f4-cdfebdc90879");
+ expect(parsed.errorMessage).toBeNull();
+ });
+
+ it("parses tool calls with JSON-encoded arguments strings", () => {
+ const stdout = [
+ '{"role":"assistant","tool_calls":[{"type":"function","id":"tool_8c1OWyRBe68OMTbWY6NqnkMm","function":{"name":"Read","arguments":"{\\"path\\":\\"probe.txt\\"}"}}]}',
+ ].join("\n");
+
+ const parsed = parseKimiJsonl(stdout);
+
+ expect(parsed.toolCalls).toEqual([
+ { id: "tool_8c1OWyRBe68OMTbWY6NqnkMm", name: "Read", arguments: { path: "probe.txt" } },
+ ]);
+ expect(parsed.summary).toBe("");
+ });
+
+ it("keeps raw arguments when the string is not valid JSON", () => {
+ const stdout = [
+ '{"role":"assistant","tool_calls":[{"type":"function","id":"tool_1","function":{"name":"Bash","arguments":"not json"}}]}',
+ ].join("\n");
+
+ const parsed = parseKimiJsonl(stdout);
+
+ expect(parsed.toolCalls).toEqual([
+ { id: "tool_1", name: "Bash", arguments: "not json" },
+ ]);
+ });
+
+ it("collects tool results keyed by tool_call_id", () => {
+ const stdout = [
+ '{"role":"assistant","tool_calls":[{"type":"function","id":"tool_8c1OWyRBe68OMTbWY6NqnkMm","function":{"name":"Read","arguments":"{\\"path\\":\\"probe.txt\\"}"}}]}',
+ '{"role":"tool","tool_call_id":"tool_8c1OWyRBe68OMTbWY6NqnkMm","content":"1\\thello paperclip"}',
+ ].join("\n");
+
+ const parsed = parseKimiJsonl(stdout);
+
+ expect(parsed.toolResults).toEqual([
+ { toolCallId: "tool_8c1OWyRBe68OMTbWY6NqnkMm", content: "1\thello paperclip" },
+ ]);
+ });
+
+ it("captures the session id from the trailing meta resume hint", () => {
+ const stdout = [
+ '{"role":"assistant","content":"done"}',
+ '{"role":"meta","type":"session.resume_hint","session_id":"session_abc","command":"kimi -r session_abc","content":"To resume this session: kimi -r session_abc"}',
+ ].join("\n");
+
+ expect(parseKimiJsonl(stdout).sessionId).toBe("session_abc");
+ });
+
+ it("uses only the last assistant content as the run summary", () => {
+ // Intermediate "thinking out loud" lines must not be auto-posted as issue comments.
+ const stdout = [
+ '{"role":"assistant","content":"Let me get oriented and check the PRs…"}',
+ '{"role":"assistant","tool_calls":[{"type":"function","id":"t1","function":{"name":"Bash","arguments":"{}"}}]}',
+ '{"role":"tool","tool_call_id":"t1","content":"ok"}',
+ '{"role":"assistant","content":"## Update\\n\\n- Merged PR #25\\n- Burn-in continues"}',
+ ].join("\n");
+
+ expect(parseKimiJsonl(stdout).summary).toBe("## Update\n\n- Merged PR #25\n- Burn-in continues");
+ });
+
+ it("buildKimiRunSummary picks the last non-empty message", () => {
+ expect(buildKimiRunSummary(["first", "second", ""])).toBe("second");
+ expect(buildKimiRunSummary([])).toBe("");
+ });
+
+ it("skips malformed lines without failing the parse", () => {
+ const stdout = [
+ "not json at all",
+ '{"role":"assistant","content":"visible"}',
+ "{broken json",
+ "",
+ ].join("\n");
+
+ const parsed = parseKimiJsonl(stdout);
+
+ expect(parsed.summary).toBe("visible");
+ expect(parsed.sessionId).toBeNull();
+ });
+
+ it("ignores meta events without a session id", () => {
+ const stdout = '{"role":"meta","type":"some.other_meta","content":"noise"}';
+ expect(parseKimiJsonl(stdout).sessionId).toBeNull();
+ });
+});
+
+describe("detectKimiAuthRequired", () => {
+ it("flags device-flow login hints", () => {
+ const result = detectKimiAuthRequired({
+ stdout: "",
+ stderr: "Not authenticated. Run `kimi login` to authenticate with a device code.",
+ });
+ expect(result.requiresAuth).toBe(true);
+ });
+
+ it("flags 401 unauthorized responses", () => {
+ const result = detectKimiAuthRequired({
+ stdout: "",
+ stderr: "Error: 401 Unauthorized",
+ });
+ expect(result.requiresAuth).toBe(true);
+ });
+
+ it("does not flag ordinary output", () => {
+ const result = detectKimiAuthRequired({
+ stdout: '{"role":"assistant","content":"hello"}',
+ stderr: "",
+ });
+ expect(result.requiresAuth).toBe(false);
+ });
+});
+
+describe("isKimiTransientNetworkError", () => {
+ it("matches DNS failures", () => {
+ expect(isKimiTransientNetworkError("", "Error: getaddrinfo ENOTFOUND api.moonshot.cn")).toBe(true);
+ });
+
+ it("matches EAI_AGAIN", () => {
+ expect(isKimiTransientNetworkError("", "getaddrinfo EAI_AGAIN api.moonshot.cn")).toBe(true);
+ });
+
+ it("matches fetch failed", () => {
+ expect(isKimiTransientNetworkError("", "TypeError: fetch failed")).toBe(true);
+ });
+
+ it("does not match unrelated stderr", () => {
+ expect(isKimiTransientNetworkError("", "Some other error")).toBe(false);
+ });
+});
+
+describe("isKimiSessionUnrecoverableError", () => {
+ it("matches unknown session", () => {
+ expect(isKimiSessionUnrecoverableError("", "Error: unknown session 'session_abc'")).toBe(true);
+ });
+
+ it("matches session not found", () => {
+ expect(isKimiSessionUnrecoverableError("", "session session_abc not found on disk")).toBe(true);
+ });
+
+ it("matches failed to resume", () => {
+ expect(isKimiSessionUnrecoverableError("", "failed to resume session session_abc")).toBe(true);
+ });
+
+ it("does not match unrelated stderr", () => {
+ expect(isKimiSessionUnrecoverableError("", "Some other error")).toBe(false);
+ });
+
+ it("does not match transient network errors (those go to isKimiTransientNetworkError)", () => {
+ expect(isKimiSessionUnrecoverableError("", "Error: getaddrinfo ENOTFOUND api.moonshot.cn")).toBe(false);
+ });
+});
diff --git a/packages/adapters/kimi-local/src/server/parse.ts b/packages/adapters/kimi-local/src/server/parse.ts
new file mode 100644
index 0000000000..007e79d6a8
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/parse.ts
@@ -0,0 +1,236 @@
+import { asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";
+
+export interface ParsedKimiToolCall {
+ id: string | null;
+ name: string;
+ arguments: unknown;
+}
+
+export interface ParsedKimiToolResult {
+ toolCallId: string | null;
+ content: string;
+}
+
+export interface ParsedKimiJsonl {
+ sessionId: string | null;
+ summary: string;
+ toolCalls: ParsedKimiToolCall[];
+ toolResults: ParsedKimiToolResult[];
+ errorMessage: string | null;
+}
+
+/**
+ * Kimi tool_call `function.arguments` is a JSON-encoded string. Parse it when
+ * possible so downstream consumers see structured input; fall back to the raw
+ * string when it is not valid JSON.
+ */
+function parseToolCallArguments(value: unknown): unknown {
+ if (typeof value !== "string") return value ?? {};
+ const trimmed = value.trim();
+ if (!trimmed) return {};
+ try {
+ return JSON.parse(trimmed);
+ } catch {
+ return value;
+ }
+}
+
+function errorText(value: unknown): string {
+ if (typeof value === "string") return value;
+ const rec = parseObject(value);
+ const message =
+ asString(rec.message, "").trim() ||
+ asString(rec.error, "").trim() ||
+ asString(rec.detail, "").trim() ||
+ asString(rec.code, "").trim();
+ if (message) return message;
+ try {
+ return JSON.stringify(rec);
+ } catch {
+ return "";
+ }
+}
+
+/**
+ * Build the run summary that Paperclip may auto-post as an issue comment.
+ *
+ * Kimi emits many intermediate assistant content lines during a multi-step
+ * agent loop ("Let me check…", tool plans, etc.). Joining all of them produced
+ * 50k+ character issue dumps. Prefer the last non-empty assistant content —
+ * typically the final board-facing wrap-up after the last tool turn.
+ */
+export function buildKimiRunSummary(assistantContents: string[]): string {
+ for (let i = assistantContents.length - 1; i >= 0; i -= 1) {
+ const text = (assistantContents[i] ?? "").trim();
+ if (text) return text;
+ }
+ return "";
+}
+
+/**
+ * Parse `kimi -p ... --output-format stream-json` stdout.
+ *
+ * Verified event shapes (kimi 0.27.0):
+ * - {"role":"assistant","content":"..."}
+ * - {"role":"assistant","tool_calls":[{"type":"function","id":"...","function":{"name":"...","arguments":"{...}"}}]}
+ * - {"role":"tool","tool_call_id":"...","content":"..."}
+ * - {"role":"meta","type":"session.resume_hint","session_id":"...","command":"kimi -r ...","content":"..."}
+ */
+export function parseKimiJsonl(stdout: string): ParsedKimiJsonl {
+ let sessionId: string | null = null;
+ let errorMessage: string | null = null;
+ const textParts: string[] = [];
+ const toolCalls: ParsedKimiToolCall[] = [];
+ const toolResults: ParsedKimiToolResult[] = [];
+
+ for (const rawLine of stdout.split(/\r?\n/)) {
+ const line = rawLine.trim();
+ if (!line) continue;
+
+ const event = parseJson(line);
+ if (!event) continue;
+
+ const role = asString(event.role, "").trim().toLowerCase();
+
+ if (role === "assistant") {
+ const content = asString(event.content, "").trim();
+ if (content) textParts.push(content);
+ const calls = Array.isArray(event.tool_calls) ? event.tool_calls : [];
+ for (const callRaw of calls) {
+ const call = parseObject(callRaw);
+ const fn = parseObject(call.function);
+ const name = asString(fn.name, asString(call.name, "")).trim();
+ if (!name) continue;
+ toolCalls.push({
+ id: asString(call.id, "").trim() || null,
+ name,
+ arguments: parseToolCallArguments(fn.arguments ?? call.arguments),
+ });
+ }
+ continue;
+ }
+
+ if (role === "tool") {
+ toolResults.push({
+ toolCallId: asString(event.tool_call_id, "").trim() || null,
+ content: asString(event.content, ""),
+ });
+ continue;
+ }
+
+ if (role === "meta") {
+ const type = asString(event.type, "").trim();
+ if (type === "session.resume_hint") {
+ sessionId = asString(event.session_id, "").trim() || sessionId;
+ }
+ continue;
+ }
+
+ // Defensive: kimi has no dedicated error event in the verified schema, but
+ // tolerate {"role":"error"} / {"type":"error"} lines if they ever appear.
+ const type = asString(event.type, "").trim().toLowerCase();
+ if (role === "error" || type === "error") {
+ const text = errorText(event.error ?? event.message ?? event.content ?? event.detail).trim();
+ if (text) errorMessage = text;
+ }
+ }
+
+ return {
+ sessionId,
+ summary: buildKimiRunSummary(textParts),
+ toolCalls,
+ toolResults,
+ errorMessage,
+ };
+}
+
+export interface KimiRuntimeEvent {
+ eventType: string;
+ message?: string;
+ payload?: Record<string, unknown>;
+}
+
+/**
+ * Map a single `kimi -p ... --output-format stream-json` line to live runtime
+ * events for `onEvent`, which drive the issue-thread activity indicator
+ * (`currentToolName` / `lastAssistantSnippet` / `lastEventAt`).
+ *
+ * Kimi emits complete messages in bursts with no token-level streaming, so
+ * without this the issue thread never sees a tool name or assistant snippet and
+ * sits on a stale "no output for N s" line while the model thinks. Tool results
+ * are intentionally omitted so the last meaningful "Using X" / assistant snippet
+ * is not overwritten by a generic label; the raw run-log stream keeps the
+ * activity timer fresh across tool execution.
+ */
+export function extractKimiRuntimeEvents(line: string): KimiRuntimeEvent[] {
+ const event = parseJson(line);
+ if (!event) return [];
+ const role = asString(event.role, "").trim().toLowerCase();
+ if (role !== "assistant") return [];
+
+ const events: KimiRuntimeEvent[] = [];
+ const content = asString(event.content, "").trim();
+ if (content) {
+ events.push({ eventType: "assistant", message: content, payload: { content } });
+ }
+ const calls = Array.isArray(event.tool_calls) ? event.tool_calls : [];
+ for (const callRaw of calls) {
+ const call = parseObject(callRaw);
+ const fn = parseObject(call.function);
+ const name = asString(fn.name, asString(call.name, "")).trim();
+ if (name) {
+ events.push({ eventType: "tool_call", payload: { toolName: name } });
+ }
+ }
+ return events;
+}
+
+function normalizedHaystack(stdout: string, stderr: string): string {
+ return `${stdout}\n${stderr}`
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .filter(Boolean)
+ .join("\n");
+}
+
+export function isKimiSessionUnrecoverableError(stdout: string, stderr: string): boolean {
+ return /unknown\s+session|session(?:\s+.*)?\s+not\s+found|resume\s+.*\s+not\s+found|cannot\s+resume|failed\s+to\s+resume|invalid\s+session/i.test(
+ normalizedHaystack(stdout, stderr),
+ );
+}
+
+export function isKimiTransientNetworkError(stdout: string, stderr: string): boolean {
+ return /ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT|fetch\s+failed|socket\s+hang\s+up/i.test(
+ normalizedHaystack(stdout, stderr),
+ );
+}
+
+export function describeKimiFailure(input: {
+ errorMessage?: string | null;
+ stderr?: string;
+}): string | null {
+ const detail =
+ (typeof input.errorMessage === "string" ? input.errorMessage.trim() : "") ||
+ (input.stderr ?? "")
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean) ||
+ "";
+ if (!detail) return null;
+ const clean = detail.replace(/\s+/g, " ").trim();
+ const max = 240;
+ return `Kimi run failed: ${clean.length > max ? `${clean.slice(0, max - 1)}…` : clean}`;
+}
+
+const KIMI_AUTH_REQUIRED_RE =
+ /(?:\bkimi\s+login\b|\blogin\s+required\b|not\s+(?:logged\s+in|authenticated)|\b401\b|unauthorized|device\s+code|authentication\s+(?:required|failed)|invalid\s+api[_ ]?key)/i;
+
+export function detectKimiAuthRequired(input: {
+ stdout: string;
+ stderr: string;
+}): { requiresAuth: boolean } {
+ const requiresAuth = normalizedHaystack(input.stdout, input.stderr)
+ .split(/\r?\n/)
+ .some((line) => KIMI_AUTH_REQUIRED_RE.test(line));
+ return { requiresAuth };
+}
diff --git a/packages/adapters/kimi-local/src/server/skills.ts b/packages/adapters/kimi-local/src/server/skills.ts
new file mode 100644
index 0000000000..5938b96315
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/skills.ts
@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+ AdapterSkillContext,
+ AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+ buildPersistentSkillSnapshot,
+ ensurePaperclipSkillSymlink,
+ readPaperclipRuntimeSkillEntries,
+ readInstalledSkillTargets,
+ resolvePaperclipDesiredSkillNames,
+} from "@paperclipai/adapter-utils/server-utils";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Resolve the Kimi skills home, honoring KIMI_CODE_HOME (adapter config env
+ * first, then the server process env) and falling back to ~/.kimi-code/skills.
+ */
+function resolveKimiSkillsHome(config: Record<string, unknown>) {
+ const env =
+ typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+ ? (config.env as Record<string, unknown>)
+ : {};
+ const kimiCodeHome = asString(env.KIMI_CODE_HOME) ?? asString(process.env.KIMI_CODE_HOME);
+ if (kimiCodeHome) return path.join(path.resolve(kimiCodeHome), "skills");
+ const configuredHome = asString(env.HOME);
+ const home = configuredHome ? path.resolve(configuredHome) : os.homedir();
+ return path.join(home, ".kimi-code", "skills");
+}
+
+async function buildKimiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
+ const skillsHome = resolveKimiSkillsHome(config);
+ const installed = await readInstalledSkillTargets(skillsHome);
+ return buildPersistentSkillSnapshot({
+ adapterType: "kimi_local",
+ availableEntries,
+ desiredSkills,
+ installed,
+ skillsHome,
+ locationLabel: "~/.kimi-code/skills",
+ missingDetail: "Configured but not currently linked into the Kimi skills home.",
+ externalConflictDetail: "Skill name is occupied by an external installation.",
+ externalDetail: "Installed outside Paperclip management.",
+ });
+}
+
+export async function listKimiSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+ return buildKimiSkillSnapshot(ctx.config);
+}
+
+export async function syncKimiSkills(
+ ctx: AdapterSkillContext,
+ desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+ const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
+ const desiredSet = new Set(desiredSkills);
+ const skillsHome = resolveKimiSkillsHome(ctx.config);
+ await fs.mkdir(skillsHome, { recursive: true });
+ const installed = await readInstalledSkillTargets(skillsHome);
+ const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
+
+ for (const available of availableEntries) {
+ if (!desiredSet.has(available.key)) continue;
+ const target = path.join(skillsHome, available.runtimeName);
+ await ensurePaperclipSkillSymlink(available.source, target);
+ }
+
+ for (const [name, installedEntry] of installed.entries()) {
+ const available = availableByRuntimeName.get(name);
+ if (!available) continue;
+ if (desiredSet.has(available.key)) continue;
+ if (installedEntry.targetPath !== available.source) continue;
+ await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+ }
+
+ return buildKimiSkillSnapshot(ctx.config);
+}
diff --git a/packages/adapters/kimi-local/src/server/test.test.ts b/packages/adapters/kimi-local/src/server/test.test.ts
new file mode 100644
index 0000000000..b6e96bf53f
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/test.test.ts
@@ -0,0 +1,165 @@
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+const ensureDirectoryMock = vi.hoisted(() => vi.fn(async () => {}));
+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));
+const maybeInstallMock = vi.hoisted(() => vi.fn(async () => null));
+const runProcessMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
+ describeAdapterExecutionTarget: () => "local",
+ ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,
+ ensureAdapterExecutionTargetDirectory: ensureDirectoryMock,
+ maybeRunSandboxInstallCommand: maybeInstallMock,
+ resolveAdapterExecutionTargetCwd: (_target: unknown, configuredCwd: string, fallbackCwd: string) =>
+ configuredCwd || fallbackCwd,
+ runAdapterExecutionTargetProcess: runProcessMock,
+}));
+
+import { testEnvironment } from "./test.js";
+
+describe("kimi_local testEnvironment", () => {
+ beforeEach(() => {
+ ensureDirectoryMock.mockClear();
+ ensureCommandMock.mockClear();
+ maybeInstallMock.mockClear();
+ runProcessMock.mockReset();
+ // Keep auth detection deterministic on hosts that really have kimi set up.
+ vi.stubEnv("KIMI_MODEL_NAME", "");
+ vi.stubEnv("KIMI_MODEL_API_KEY", "");
+ vi.stubEnv("KIMI_CODE_HOME", "");
+ });
+
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ });
+
+ it("reports a healthy host with a working version and hello probe", async () => {
+ runProcessMock
+ .mockResolvedValueOnce({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: "kimi 0.27.0\n",
+ stderr: "",
+ })
+ .mockResolvedValueOnce({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: [
+ JSON.stringify({ role: "assistant", content: "hello" }),
+ JSON.stringify({ role: "meta", type: "session.resume_hint", session_id: "session_1" }),
+ ].join("\n"),
+ stderr: "",
+ });
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "kimi_local",
+ config: {
+ engine: "cli",
+ command: "kimi",
+ cwd: "/tmp/project",
+ env: {
+ KIMI_MODEL_NAME: "kimi-code/kimi-for-coding",
+ KIMI_MODEL_API_KEY: "test-key",
+ },
+ },
+ });
+
+ expect(result.status).toBe("pass");
+ expect(result.checks.map((check: { code: string }) => check.code)).toEqual(
+ expect.arrayContaining([
+ "kimi_command_resolvable",
+ "kimi_version_detected",
+ "kimi_auth_detected",
+ "kimi_hello_probe_passed",
+ ]),
+ );
+ expect(runProcessMock).toHaveBeenNthCalledWith(
+ 1,
+ expect.any(String),
+ null,
+ "kimi",
+ ["--version"],
+ expect.any(Object),
+ );
+ expect(runProcessMock).toHaveBeenNthCalledWith(
+ 2,
+ expect.any(String),
+ null,
+ "kimi",
+ expect.arrayContaining([
+ "--output-format",
+ "stream-json",
+ "-p",
+ "Respond with hello.",
+ ]),
+ expect.any(Object),
+ );
+ });
+
+ it("passes -m to the hello probe when a model is configured", async () => {
+ runProcessMock
+ .mockResolvedValueOnce({ exitCode: 0, signal: null, timedOut: false, stdout: "kimi 0.27.0\n", stderr: "" })
+ .mockResolvedValueOnce({
+ exitCode: 0,
+ signal: null,
+ timedOut: false,
+ stdout: JSON.stringify({ role: "assistant", content: "hello" }),
+ stderr: "",
+ });
+
+ await testEnvironment({
+ companyId: "company-1",
+ adapterType: "kimi_local",
+ config: {
+ engine: "cli",
+ command: "kimi",
+ cwd: "/tmp/project",
+ model: "kimi-code/k3",
+ env: { KIMI_MODEL_NAME: "kimi-code/k3", KIMI_MODEL_API_KEY: "test-key" },
+ },
+ });
+
+ expect(runProcessMock).toHaveBeenNthCalledWith(
+ 2,
+ expect.any(String),
+ null,
+ "kimi",
+ expect.arrayContaining(["-m", "kimi-code/k3"]),
+ expect.any(Object),
+ );
+ });
+
+ it("downgrades missing auth and auth probe failures to warnings", async () => {
+ runProcessMock
+ .mockResolvedValueOnce({ exitCode: 0, signal: null, timedOut: false, stdout: "kimi 0.27.0\n", stderr: "" })
+ .mockResolvedValueOnce({
+ exitCode: 1,
+ signal: null,
+ timedOut: false,
+ stdout: "",
+ stderr: "Not authenticated. Run `kimi login` to authenticate with a device code.",
+ });
+
+ const result = await testEnvironment({
+ companyId: "company-1",
+ adapterType: "kimi_local",
+ config: {
+ engine: "cli",
+ command: "kimi",
+ cwd: "/tmp/project",
+ env: { KIMI_CODE_HOME: "/nonexistent-kimi-home-for-test" },
+ },
+ });
+
+ expect(result.status).toBe("warn");
+ expect(result.checks.map((check: { code: string }) => check.code)).toEqual(
+ expect.arrayContaining([
+ "kimi_auth_missing",
+ "kimi_hello_probe_auth_required",
+ ]),
+ );
+ });
+});
diff --git a/packages/adapters/kimi-local/src/server/test.ts b/packages/adapters/kimi-local/src/server/test.ts
new file mode 100644
index 0000000000..551194d655
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/test.ts
@@ -0,0 +1,342 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type {
+ AdapterEnvironmentCheck,
+ AdapterEnvironmentTestContext,
+ AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+ asNumber,
+ asString,
+ asStringArray,
+ ensurePathInEnv,
+ parseObject,
+} from "@paperclipai/adapter-utils/server-utils";
+import {
+ ensureAdapterExecutionTargetCommandResolvable,
+ maybeRunSandboxInstallCommand,
+ ensureAdapterExecutionTargetDirectory,
+ runAdapterExecutionTargetProcess,
+ describeAdapterExecutionTarget,
+ resolveAdapterExecutionTargetCwd,
+} from "@paperclipai/adapter-utils/execution-target";
+import { SANDBOX_INSTALL_COMMAND } from "../index.js";
+import { resolveKimiExecutionEngineForRun, testKimiAcpEnvironment } from "./acp.js";
+import { detectKimiAuthRequired, parseKimiJsonl } from "./parse.js";
+import { firstNonEmptyLine } from "./utils.js";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+ if (checks.some((check) => check.level === "error")) return "fail";
+ if (checks.some((check) => check.level === "warn")) return "warn";
+ return "pass";
+}
+
+function isNonEmpty(value: unknown): value is string {
+ return typeof value === "string" && value.trim().length > 0;
+}
+
+function commandLooksLike(command: string, expected: string): boolean {
+ const base = path.basename(command).toLowerCase();
+ return base === expected || base === `${expected}.cmd` || base === `${expected}.exe`;
+}
+
+function summarizeProbeDetail(stdout: string, stderr: string, parsedError: string | null): string | null {
+ const raw = parsedError?.trim() || firstNonEmptyLine(stderr) || firstNonEmptyLine(stdout);
+ if (!raw) return null;
+ const clean = raw.replace(/\s+/g, " ").trim();
+ const max = 240;
+ return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+ return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+/**
+ * config.toml exists on any configured install and is not by itself proof of
+ * auth material. Only treat it as such when a [providers.*] table carries a
+ * non-empty api_key (direct API-key auth) — the OAuth dirs are checked
+ * separately.
+ */
+const PROVIDERS_TABLE_RE = /^\s*\[providers\.[^\]]+\]/m;
+const PROVIDER_API_KEY_RE = /^\s*api_key\s*=\s*"[^"]+"/m;
+
+async function configTomlHasProviderKey(configPath: string): Promise<boolean> {
+ try {
+ const contents = await fs.readFile(configPath, "utf8");
+ return PROVIDERS_TABLE_RE.test(contents) && PROVIDER_API_KEY_RE.test(contents);
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Detect Kimi authentication material on the local host: OAuth credentials
+ * under $KIMI_CODE_HOME (default ~/.kimi-code) or a config.toml with a keyed
+ * provider, plus the KIMI_MODEL_NAME + KIMI_MODEL_API_KEY env pair (config
+ * env or server env).
+ */
+async function detectLocalKimiAuth(env: Record<string, string>): Promise<string | null> {
+ if (
+ (isNonEmpty(env.KIMI_MODEL_NAME) || isNonEmpty(process.env.KIMI_MODEL_NAME)) &&
+ (isNonEmpty(env.KIMI_MODEL_API_KEY) || isNonEmpty(process.env.KIMI_MODEL_API_KEY))
+ ) {
+ return "KIMI_MODEL_NAME + KIMI_MODEL_API_KEY environment";
+ }
+ const kimiCodeHome =
+ (isNonEmpty(env.KIMI_CODE_HOME) && env.KIMI_CODE_HOME.trim()) ||
+ (isNonEmpty(process.env.KIMI_CODE_HOME) && process.env.KIMI_CODE_HOME.trim()) ||
+ path.join(os.homedir(), ".kimi-code");
+ for (const candidate of [path.join(kimiCodeHome, "credentials"), path.join(kimiCodeHome, "oauth")]) {
+ if (await pathExists(candidate)) {
+ return `${candidate} (kimi login OAuth)`;
+ }
+ }
+ const configPath = path.join(kimiCodeHome, "config.toml");
+ if (await configTomlHasProviderKey(configPath)) {
+ return `${configPath} ([providers.*] api_key)`;
+ }
+ return null;
+}
+
+export async function testEnvironment(
+ ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+ const engineSelection = await resolveKimiExecutionEngineForRun({
+ config: parseObject(ctx.config),
+ executionTarget: ctx.executionTarget,
+ });
+ if (engineSelection.engine === "acp") {
+ return testKimiAcpEnvironment(ctx);
+ }
+
+ const checks: AdapterEnvironmentCheck[] = [];
+ if (!engineSelection.explicit && engineSelection.fallbackReason) {
+ checks.push({
+ code: "kimi_acp_default_fallback",
+ level: "warn",
+ message: "Kimi ACP default is unavailable; testing the Kimi CLI fallback lane.",
+ detail: engineSelection.fallbackReason,
+ hint: "Fix the ACP prerequisite to use the default ACP lane, or set engine=cli to pin the CLI lane.",
+ });
+ }
+ const config = parseObject(ctx.config);
+ const command = asString(config.command, "kimi");
+ const target = ctx.executionTarget ?? null;
+ const targetIsRemote = target?.kind === "remote";
+ const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
+ const targetLabel = targetIsRemote
+ ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
+ : null;
+ const runId = `kimi-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+ if (targetLabel) {
+ checks.push({
+ code: "kimi_environment_target",
+ level: "info",
+ message: `Probing inside environment: ${targetLabel}`,
+ });
+ }
+
+ try {
+ await ensureAdapterExecutionTargetDirectory(runId, target, cwd, {
+ cwd,
+ env: {},
+ createIfMissing: true,
+ });
+ checks.push({
+ code: "kimi_cwd_valid",
+ level: "info",
+ message: `Working directory is valid: ${cwd}`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "kimi_cwd_invalid",
+ level: "error",
+ message: err instanceof Error ? err.message : "Invalid working directory",
+ detail: cwd,
+ });
+ }
+
+ const envConfig = parseObject(config.env);
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(envConfig)) {
+ if (typeof value === "string") env[key] = value;
+ }
+ const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+ const installCheck = await maybeRunSandboxInstallCommand({
+ runId,
+ target,
+ adapterKey: "kimi",
+ installCommand: SANDBOX_INSTALL_COMMAND,
+ detectCommand: command,
+ env,
+ });
+ if (installCheck) checks.push(installCheck);
+ try {
+ await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
+ checks.push({
+ code: "kimi_command_resolvable",
+ level: "info",
+ message: `Command is executable: ${command}`,
+ });
+ } catch (err) {
+ checks.push({
+ code: "kimi_command_unresolvable",
+ level: "error",
+ message: err instanceof Error ? err.message : "Command is not executable",
+ detail: command,
+ });
+ }
+
+ const canRunProbe =
+ checks.every((check) => check.code !== "kimi_cwd_invalid" && check.code !== "kimi_command_unresolvable");
+
+ if (canRunProbe && commandLooksLike(command, "kimi")) {
+ const versionProbe = await runAdapterExecutionTargetProcess(
+ runId,
+ target,
+ command,
+ ["--version"],
+ {
+ cwd,
+ env,
+ timeoutSec: 15,
+ graceSec: 5,
+ onLog: async () => {},
+ },
+ );
+ const versionLine = firstNonEmptyLine(versionProbe.stdout) || firstNonEmptyLine(versionProbe.stderr);
+ if (!versionProbe.timedOut && (versionProbe.exitCode ?? 1) === 0) {
+ checks.push({
+ code: "kimi_version_detected",
+ level: "info",
+ message: `Kimi CLI detected${versionLine ? `: ${versionLine.replace(/\s+/g, " ").trim().slice(0, 120)}` : "."}`,
+ });
+ } else {
+ checks.push({
+ code: "kimi_version_probe_failed",
+ level: "warn",
+ message: versionProbe.timedOut
+ ? "`kimi --version` timed out."
+ : "`kimi --version` did not exit cleanly.",
+ ...(versionLine ? { detail: versionLine } : {}),
+ });
+ }
+ }
+
+ const authSource = targetIsRemote
+ ? ((isNonEmpty(env.KIMI_MODEL_NAME) && isNonEmpty(env.KIMI_MODEL_API_KEY))
+ ? "KIMI_MODEL_NAME + KIMI_MODEL_API_KEY adapter env"
+ : null)
+ : await detectLocalKimiAuth(env);
+ if (authSource) {
+ checks.push({
+ code: "kimi_auth_detected",
+ level: "info",
+ message: "Kimi authentication material detected.",
+ detail: `Source: ${authSource}.`,
+ });
+ } else {
+ checks.push({
+ code: "kimi_auth_missing",
+ level: "warn",
+ message: "No Kimi authentication detected.",
+ hint: "Run `kimi login` (OAuth device flow) on the target host, or set KIMI_MODEL_NAME + KIMI_MODEL_API_KEY in the adapter env.",
+ });
+ }
+
+ if (canRunProbe) {
+ if (!commandLooksLike(command, "kimi")) {
+ checks.push({
+ code: "kimi_hello_probe_skipped_custom_command",
+ level: "info",
+ message: "Skipped hello probe because command is not `kimi`.",
+ detail: command,
+ hint: "Use the `kimi` CLI command to run the automatic installation and auth probe.",
+ });
+ } else {
+ const model = asString(config.model, "").trim();
+ const helloProbeTimeoutSec = Math.max(1, asNumber(config.helloProbeTimeoutSec, 60));
+ const extraArgs = (() => {
+ const fromExtraArgs = asStringArray(config.extraArgs);
+ if (fromExtraArgs.length > 0) return fromExtraArgs;
+ return asStringArray(config.args);
+ })();
+
+ const args = ["--output-format", "stream-json"];
+ if (model) args.push("-m", model);
+ if (extraArgs.length > 0) args.push(...extraArgs);
+ args.push("-p", "Respond with hello.");
+
+ const probe = await runAdapterExecutionTargetProcess(
+ runId,
+ target,
+ command,
+ args,
+ {
+ cwd,
+ env,
+ timeoutSec: helloProbeTimeoutSec,
+ graceSec: 5,
+ onLog: async () => {},
+ },
+ );
+ const parsed = parseKimiJsonl(probe.stdout);
+ const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
+ const authMeta = detectKimiAuthRequired({
+ stdout: probe.stdout,
+ stderr: probe.stderr,
+ });
+
+ if (probe.timedOut) {
+ checks.push({
+ code: "kimi_hello_probe_timed_out",
+ level: "warn",
+ message: "Kimi hello probe timed out.",
+ hint: "Retry the probe. If this persists, verify Kimi can run `kimi -p \"Respond with hello.\"` from this directory manually.",
+ });
+ } else if ((probe.exitCode ?? 1) === 0) {
+ const summary = parsed.summary.trim();
+ const hasHello = /\bhello\b/i.test(summary);
+ checks.push({
+ code: hasHello ? "kimi_hello_probe_passed" : "kimi_hello_probe_unexpected_output",
+ level: hasHello ? "info" : "warn",
+ message: hasHello
+ ? "Kimi hello probe succeeded."
+ : "Kimi probe ran but did not return `hello` as expected.",
+ ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
+ ...(hasHello
+ ? {}
+ : {
+ hint: "Try `kimi -p \"Respond with hello.\" --output-format stream-json` manually to inspect full output.",
+ }),
+ });
+ } else if (authMeta.requiresAuth) {
+ checks.push({
+ code: "kimi_hello_probe_auth_required",
+ level: "warn",
+ message: "Kimi CLI is installed, but authentication is not ready.",
+ ...(detail ? { detail } : {}),
+ hint: "Run `kimi login` or configure KIMI_MODEL_NAME + KIMI_MODEL_API_KEY in adapter env/shell, then retry the probe.",
+ });
+ } else {
+ checks.push({
+ code: "kimi_hello_probe_failed",
+ level: "error",
+ message: "Kimi hello probe failed.",
+ ...(detail ? { detail } : {}),
+ hint: "Run `kimi -p \"Respond with hello.\" --output-format stream-json` manually in this working directory to debug.",
+ });
+ }
+ }
+ }
+
+ return {
+ adapterType: ctx.adapterType,
+ status: summarizeStatus(checks),
+ checks,
+ testedAt: new Date().toISOString(),
+ };
+}
diff --git a/packages/adapters/kimi-local/src/server/utils.ts b/packages/adapters/kimi-local/src/server/utils.ts
new file mode 100644
index 0000000000..a4fdc6a39b
--- /dev/null
+++ b/packages/adapters/kimi-local/src/server/utils.ts
@@ -0,0 +1,8 @@
+export function firstNonEmptyLine(text: string): string {
+ return (
+ text
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean) ?? ""
+ );
+}
diff --git a/packages/adapters/kimi-local/src/ui/build-config.test.ts b/packages/adapters/kimi-local/src/ui/build-config.test.ts
new file mode 100644
index 0000000000..5c1ee34e21
--- /dev/null
+++ b/packages/adapters/kimi-local/src/ui/build-config.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import { buildKimiLocalConfig } from "./build-config.js";
+
+function makeValues(overrides: Partial<CreateConfigValues> = {}): CreateConfigValues {
+ return {
+ adapterType: "kimi_local",
+ cwd: "",
+ instructionsFilePath: "",
+ promptTemplate: "",
+ model: "",
+ thinkingEffort: "",
+ chrome: false,
+ dangerouslySkipPermissions: true,
+ search: false,
+ fastMode: false,
+ dangerouslyBypassSandbox: false,
+ command: "",
+ args: "",
+ extraArgs: "",
+ envVars: "",
+ envBindings: {},
+ url: "",
+ bootstrapPrompt: "",
+ payloadTemplateJson: "",
+ workspaceStrategyType: "project_primary",
+ workspaceBaseRef: "",
+ workspaceBranchTemplate: "",
+ worktreeParentDir: "",
+ runtimeServicesJson: "",
+ maxTurnsPerRun: 1000,
+ heartbeatEnabled: false,
+ intervalSec: 300,
+ ...overrides,
+ };
+}
+
+describe("buildKimiLocalConfig", () => {
+ it("defaults the model to kimi-code/kimi-for-coding when unset", () => {
+ const config = buildKimiLocalConfig(makeValues());
+
+ expect(config.model).toBe("kimi-code/kimi-for-coding");
+ expect(config.timeoutSec).toBe(0);
+ expect(config.graceSec).toBe(15);
+ });
+
+ it("persists an explicit model and command", () => {
+ const config = buildKimiLocalConfig(makeValues({
+ model: "kimi-code/k3",
+ command: "/usr/local/bin/kimi",
+ }));
+
+ expect(config.model).toBe("kimi-code/k3");
+ expect(config.command).toBe("/usr/local/bin/kimi");
+ });
+
+ it("persists cwd, instructionsFilePath, and extra args", () => {
+ const config = buildKimiLocalConfig(makeValues({
+ cwd: "/tmp/project",
+ instructionsFilePath: "/tmp/project/AGENTS.md",
+ extraArgs: "--add-dir /tmp/other, --plan",
+ }));
+
+ expect(config.cwd).toBe("/tmp/project");
+ expect(config.instructionsFilePath).toBe("/tmp/project/AGENTS.md");
+ expect(config.extraArgs).toEqual(["--add-dir /tmp/other", "--plan"]);
+ });
+
+ it("merges legacy env vars with secret bindings", () => {
+ const config = buildKimiLocalConfig(makeValues({
+ envVars: "KIMI_MODEL_NAME=kimi-code/k3\n# comment\nINVALID LINE",
+ envBindings: {
+ KIMI_MODEL_API_KEY: { type: "secret_ref", secretId: "secret-1" },
+ },
+ }));
+
+ expect(config.env).toEqual({
+ KIMI_MODEL_NAME: { type: "plain", value: "kimi-code/k3" },
+ KIMI_MODEL_API_KEY: { type: "secret_ref", secretId: "secret-1" },
+ });
+ });
+});
diff --git a/packages/adapters/kimi-local/src/ui/build-config.ts b/packages/adapters/kimi-local/src/ui/build-config.ts
new file mode 100644
index 0000000000..dc51828c9e
--- /dev/null
+++ b/packages/adapters/kimi-local/src/ui/build-config.ts
@@ -0,0 +1,73 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "../index.js";
+
+function parseCommaArgs(value: string): string[] {
+ return value
+ .split(",")
+ .map((item) => item.trim())
+ .filter(Boolean);
+}
+
+function parseEnvVars(text: string): Record<string, string> {
+ const env: Record<string, string> = {};
+ for (const line of text.split(/\r?\n/)) {
+ const trimmed = line.trim();
+ if (!trimmed || trimmed.startsWith("#")) continue;
+ const eq = trimmed.indexOf("=");
+ if (eq <= 0) continue;
+ const key = trimmed.slice(0, eq).trim();
+ const value = trimmed.slice(eq + 1);
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ env[key] = value;
+ }
+ return env;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+ if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+ const env: Record<string, unknown> = {};
+ for (const [key, raw] of Object.entries(bindings)) {
+ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+ if (typeof raw === "string") {
+ env[key] = { type: "plain", value: raw };
+ continue;
+ }
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+ const rec = raw as Record<string, unknown>;
+ if (rec.type === "plain" && typeof rec.value === "string") {
+ env[key] = { type: "plain", value: rec.value };
+ continue;
+ }
+ if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+ env[key] = {
+ type: "secret_ref",
+ secretId: rec.secretId,
+ ...(typeof rec.version === "number" || rec.version === "latest"
+ ? { version: rec.version }
+ : {}),
+ };
+ }
+ }
+ return env;
+}
+
+export function buildKimiLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+ const ac: Record<string, unknown> = {};
+ if (v.cwd) ac.cwd = v.cwd;
+ if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
+ ac.model = v.model || DEFAULT_KIMI_LOCAL_MODEL;
+ ac.timeoutSec = 0;
+ ac.graceSec = 15;
+ const env = parseEnvBindings(v.envBindings);
+ const legacy = parseEnvVars(v.envVars);
+ for (const [key, value] of Object.entries(legacy)) {
+ if (!Object.prototype.hasOwnProperty.call(env, key)) {
+ env[key] = { type: "plain", value };
+ }
+ }
+ if (Object.keys(env).length > 0) ac.env = env;
+
+ if (v.command) ac.command = v.command;
+ if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+ return ac;
+}
diff --git a/packages/adapters/kimi-local/src/ui/index.ts b/packages/adapters/kimi-local/src/ui/index.ts
new file mode 100644
index 0000000000..ce2757e132
--- /dev/null
+++ b/packages/adapters/kimi-local/src/ui/index.ts
@@ -0,0 +1,2 @@
+export { parseKimiStdoutLine } from "./parse-stdout.js";
+export { buildKimiLocalConfig } from "./build-config.js";
diff --git a/packages/adapters/kimi-local/src/ui/parse-stdout.test.ts b/packages/adapters/kimi-local/src/ui/parse-stdout.test.ts
new file mode 100644
index 0000000000..d071bb1d1e
--- /dev/null
+++ b/packages/adapters/kimi-local/src/ui/parse-stdout.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import { parseKimiStdoutLine } from "./parse-stdout.js";
+
+const ts = "2026-07-19T00:00:00.000Z";
+
+describe("parseKimiStdoutLine ACP delegation", () => {
+ it("delegates acpx.* events to the shared acpx transcript parser", () => {
+ const line = JSON.stringify({ type: "acpx.tool_call", name: "Terminal", status: "pending", text: "Terminal (pending)" });
+ const entries = parseKimiStdoutLine(line, ts);
+ // The shared parser produces a structured entry, not the raw stdout fallback.
+ expect(entries.length).toBeGreaterThan(0);
+ expect(entries.every((e) => e.kind !== "stdout")).toBe(true);
+ });
+
+ it("still parses native kimi role events (no acpx type)", () => {
+ const line = JSON.stringify({ role: "assistant", content: "hi" });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([{ kind: "assistant", ts, text: "hi" }]);
+ });
+});
+
+describe("parseKimiStdoutLine", () => {
+ it("renders assistant content as an assistant transcript entry", () => {
+ const line = JSON.stringify({
+ role: "assistant",
+ content: "PAPERCLIP_ADAPTER_TEST_OK",
+ });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([
+ { kind: "assistant", ts, text: "PAPERCLIP_ADAPTER_TEST_OK" },
+ ]);
+ });
+
+ it("renders assistant tool_calls with parsed arguments", () => {
+ const line = JSON.stringify({
+ role: "assistant",
+ tool_calls: [{
+ type: "function",
+ id: "tool_8c1OWyRBe68OMTbWY6NqnkMm",
+ function: { name: "Read", arguments: "{\"path\":\"probe.txt\"}" },
+ }],
+ });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([
+ {
+ kind: "tool_call",
+ ts,
+ name: "Read",
+ input: { path: "probe.txt" },
+ toolUseId: "tool_8c1OWyRBe68OMTbWY6NqnkMm",
+ },
+ ]);
+ });
+
+ it("renders tool results as tool_result entries", () => {
+ const line = JSON.stringify({
+ role: "tool",
+ tool_call_id: "tool_8c1OWyRBe68OMTbWY6NqnkMm",
+ content: "1\thello paperclip",
+ });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([
+ {
+ kind: "tool_result",
+ ts,
+ toolUseId: "tool_8c1OWyRBe68OMTbWY6NqnkMm",
+ content: "1\thello paperclip",
+ isError: false,
+ },
+ ]);
+ });
+
+ it("surfaces the meta session resume hint as session info", () => {
+ const line = JSON.stringify({
+ role: "meta",
+ type: "session.resume_hint",
+ session_id: "session_769ddab9-0a25-4edd-99f4-cdfebdc90879",
+ command: "kimi -r session_769ddab9-0a25-4edd-99f4-cdfebdc90879",
+ content: "To resume this session: kimi -r session_769ddab9-0a25-4edd-99f4-cdfebdc90879",
+ });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([
+ { kind: "system", ts, text: "session: session_769ddab9-0a25-4edd-99f4-cdfebdc90879" },
+ ]);
+ });
+
+ it("ignores unrecognized meta lines", () => {
+ const line = JSON.stringify({ role: "meta", type: "progress", content: "working" });
+ expect(parseKimiStdoutLine(line, ts)).toEqual([]);
+ });
+
+ it("passes non-JSON lines through as stdout", () => {
+ expect(parseKimiStdoutLine("plain output line", ts)).toEqual([
+ { kind: "stdout", ts, text: "plain output line" },
+ ]);
+ });
+});
diff --git a/packages/adapters/kimi-local/src/ui/parse-stdout.ts b/packages/adapters/kimi-local/src/ui/parse-stdout.ts
new file mode 100644
index 0000000000..279b73bb15
--- /dev/null
+++ b/packages/adapters/kimi-local/src/ui/parse-stdout.ts
@@ -0,0 +1,114 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import { parseAcpxStdoutLine } from "@paperclipai/adapter-utils/acpx-engine/ui";
+
+function safeJsonParse(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+ return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+ return typeof value === "string" ? value : fallback;
+}
+
+function stringifyUnknown(value: unknown): string {
+ if (typeof value === "string") return value;
+ if (value === null || value === undefined) return "";
+ try {
+ return JSON.stringify(value, null, 2);
+ } catch {
+ return String(value);
+ }
+}
+
+function parseToolCallArguments(value: unknown): unknown {
+ if (typeof value !== "string") return value ?? {};
+ const trimmed = value.trim();
+ if (!trimmed) return {};
+ try {
+ return JSON.parse(trimmed);
+ } catch {
+ return value;
+ }
+}
+
+/**
+ * Map one `kimi -p ... --output-format stream-json` stdout line to transcript
+ * entries. Verified shapes (kimi 0.27.0): assistant content, assistant
+ * tool_calls (arguments is a JSON-encoded string), tool results, and a
+ * trailing meta session.resume_hint event.
+ */
+export function parseKimiStdoutLine(line: string, ts: string): TranscriptEntry[] {
+ const parsed = asRecord(safeJsonParse(line));
+ if (!parsed) {
+ return [{ kind: "stdout", ts, text: line }];
+ }
+
+ // ACP-lane runs emit acpx.* events (streaming text deltas, tool-call status
+ // lifecycle); delegate those to the shared acpx transcript parser.
+ if (asString(parsed.type).startsWith("acpx.")) {
+ return parseAcpxStdoutLine(line, ts);
+ }
+
+ const role = asString(parsed.role).trim().toLowerCase();
+
+ if (role === "assistant") {
+ const entries: TranscriptEntry[] = [];
+ const content = asString(parsed.content).trim();
+ if (content) entries.push({ kind: "assistant", ts, text: content });
+ const toolCalls = Array.isArray(parsed.tool_calls) ? parsed.tool_calls : [];
+ for (const callRaw of toolCalls) {
+ const call = asRecord(callRaw);
+ if (!call) continue;
+ const fn = asRecord(call.function);
+ const name = asString(fn?.name, asString(call.name, "tool")).trim() || "tool";
+ entries.push({
+ kind: "tool_call",
+ ts,
+ name,
+ input: parseToolCallArguments(fn?.arguments ?? call.arguments),
+ toolUseId: asString(call.id).trim() || undefined,
+ });
+ }
+ return entries;
+ }
+
+ if (role === "tool") {
+ const toolUseId = asString(parsed.tool_call_id).trim() || "tool_result";
+ const content = asString(parsed.content) || stringifyUnknown(parsed.content);
+ return [{
+ kind: "tool_result",
+ ts,
+ toolUseId,
+ content,
+ isError: false,
+ }];
+ }
+
+ if (role === "meta") {
+ const type = asString(parsed.type).trim();
+ if (type === "session.resume_hint") {
+ const sessionId = asString(parsed.session_id).trim();
+ return sessionId ? [{ kind: "system", ts, text: `session: ${sessionId}` }] : [];
+ }
+ return [];
+ }
+
+ if (role === "error" || asString(parsed.type).trim().toLowerCase() === "error") {
+ const text =
+ asString(parsed.content) ||
+ asString(parsed.message) ||
+ asString(parsed.error) ||
+ "Kimi error";
+ return [{ kind: "stderr", ts, text }];
+ }
+
+ return [{ kind: "stdout", ts, text: line }];
+}
diff --git a/packages/adapters/kimi-local/tsconfig.json b/packages/adapters/kimi-local/tsconfig.json
new file mode 100644
index 0000000000..2f355cfeeb
--- /dev/null
+++ b/packages/adapters/kimi-local/tsconfig.json
@@ -0,0 +1,8 @@
+{
+ "extends": "../../../tsconfig.json",
+ "compilerOptions": {
+ "outDir": "dist",
+ "rootDir": "src"
+ },
+ "include": ["src"]
+}
diff --git a/packages/adapters/kimi-local/vitest.config.ts b/packages/adapters/kimi-local/vitest.config.ts
new file mode 100644
index 0000000000..f624398e8d
--- /dev/null
+++ b/packages/adapters/kimi-local/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ environment: "node",
+ },
+});
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index d466081235..4b8aba6f25 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -37,6 +37,7 @@ export const AGENT_ADAPTER_TYPES = [
"grok_local",
"hermes_gateway",
"hermes_local",
+ "kimi_local",
"opencode_local",
"pi_local",
"cursor",
diff --git a/packages/shared/src/environment-support.test.ts b/packages/shared/src/environment-support.test.ts
index 0a2c72b364..94926016ae 100644
--- a/packages/shared/src/environment-support.test.ts
+++ b/packages/shared/src/environment-support.test.ts
@@ -42,6 +42,30 @@ describe("isSandboxProviderSupportedForAdapter", () => {
}),
]);
});
+
+ it("treats kimi_local as a remote-managed local adapter", () => {
+ expect(adapterSupportsRemoteManagedEnvironments("kimi_local")).toBe(true);
+ expect(supportedEnvironmentDriversForAdapter("kimi_local")).toEqual(["local", "ssh", "sandbox"]);
+ expect(
+ isSandboxProviderSupportedForAdapter("kimi_local", "fake-plugin", ["fake-plugin"]),
+ ).toBe(true);
+ });
+
+ it("includes kimi_local sandbox support in environment capabilities", () => {
+ const capabilities = getEnvironmentCapabilities(["kimi_local"], {
+ sandboxProviders: {
+ "fake-plugin": { displayName: "Fake Plugin" },
+ },
+ });
+
+ expect(capabilities.adapters).toEqual([
+ expect.objectContaining({
+ adapterType: "kimi_local",
+ drivers: expect.objectContaining({ sandbox: "supported", ssh: "supported" }),
+ sandboxProviders: expect.objectContaining({ "fake-plugin": "supported" }),
+ }),
+ ]);
+ });
});
describe("getEnvironmentCapabilities reusable leases default", () => {
diff --git a/packages/shared/src/environment-support.ts b/packages/shared/src/environment-support.ts
index e08e32d76c..5bb5a076ea 100644
--- a/packages/shared/src/environment-support.ts
+++ b/packages/shared/src/environment-support.ts
@@ -70,6 +70,7 @@ const REMOTE_MANAGED_ADAPTERS = new Set<AgentAdapterType>([
"cursor",
"gemini_local",
"grok_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]);
diff --git a/packages/shared/src/telemetry/generated/paperclip-telemetry.ts b/packages/shared/src/telemetry/generated/paperclip-telemetry.ts
index 281b657da9..32e9e07576 100644
--- a/packages/shared/src/telemetry/generated/paperclip-telemetry.ts
+++ b/packages/shared/src/telemetry/generated/paperclip-telemetry.ts
@@ -11,7 +11,7 @@ agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer
}
export interface PaperclipAgentTaskCompletedDimensions {
-adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "other")
+adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "kimi_local" | "other")
agent_id: string
agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other")
model?: string
@@ -32,7 +32,7 @@ goal_level: ("company" | "team" | "agent" | "task" | "other")
}
export interface PaperclipInstallCompletedDimensions {
-adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "other")
+adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "kimi_local" | "other")
}
export interface PaperclipInstallStartedDimensions {
@@ -186,6 +186,7 @@ export const PAPERCLIP_ENUM_DESCRIPTIONS = {
"cursor": "Agent runtime uses the Cursor adapter.",
"openclaw_gateway": "Agent runtime uses the OpenClaw gateway adapter.",
"grok_local": "Agent runtime uses the local Grok adapter.",
+ "kimi_local": "Agent runtime uses the local Kimi adapter.",
"other": "Fallback when the adapter type is unknown or not represented by the tracked enum."
},
"agent_role": {
@@ -239,6 +240,7 @@ export const PAPERCLIP_ENUM_DESCRIPTIONS = {
"cursor": "Agent runtime uses the Cursor adapter.",
"openclaw_gateway": "Agent runtime uses the OpenClaw gateway adapter.",
"grok_local": "Agent runtime uses the local Grok adapter.",
+ "kimi_local": "Agent runtime uses the local Kimi adapter.",
"other": "Fallback when the adapter type is unknown or not represented by the tracked enum."
}
},
diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.json
index cd061d627e..b13049d2bd 100644
--- a/scripts/release-package-manifest.json
+++ b/scripts/release-package-manifest.json
@@ -44,6 +44,11 @@
"name": "@paperclipai/adapter-hermes-gateway",
"publishFromCi": false
},
+ {
+ "dir": "packages/adapters/kimi-local",
+ "name": "@paperclipai/adapter-kimi-local",
+ "publishFromCi": true
+ },
{
"dir": "packages/adapters/opencode-local",
"name": "@paperclipai/adapter-opencode-local",
diff --git a/server/package.json b/server/package.json
index 7098eeb6ed..bfb75db352 100644
--- a/server/package.json
+++ b/server/package.json
@@ -51,6 +51,7 @@
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-gemini-local": "workspace:*",
"@paperclipai/adapter-grok-local": "workspace:*",
+ "@paperclipai/adapter-kimi-local": "workspace:*",
"@paperclipai/adapter-openclaw-gateway": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
"@paperclipai/adapter-pi-local": "workspace:*",
diff --git a/server/src/__tests__/adapter-routes.test.ts b/server/src/__tests__/adapter-routes.test.ts
index aaae9fc89e..7765859679 100644
--- a/server/src/__tests__/adapter-routes.test.ts
+++ b/server/src/__tests__/adapter-routes.test.ts
@@ -218,6 +218,24 @@ describe("adapter routes", () => {
supportsAcp: false,
});
+ const kimiAdapter = res.body.find((a: any) => a.type === "kimi_local");
+ expect(kimiAdapter).toBeDefined();
+ expect(kimiAdapter.capabilities).toMatchObject({
+ supportsInstructionsBundle: true,
+ supportsSkills: true,
+ supportsLocalAgentJwt: true,
+ requiresMaterializedRuntimeSkills: true,
+ supportsAcp: true,
+ });
+ expect(kimiAdapter.acp).toMatchObject({
+ agentId: "kimi",
+ skillsMode: "ephemeral",
+ prerequisites: {
+ nodeRange: ">=20.0.0",
+ packages: ["@moonshot-ai/kimi-code"],
+ },
+ });
+
const hermesLocal = res.body.find((a: any) => a.type === "hermes_local");
expect(hermesLocal).toBeDefined();
expect(hermesLocal.source).toBe("builtin");
diff --git a/server/src/__tests__/environment-execution-target.test.ts b/server/src/__tests__/environment-execution-target.test.ts
index 662cf4c071..b9d96aabc3 100644
--- a/server/src/__tests__/environment-execution-target.test.ts
+++ b/server/src/__tests__/environment-execution-target.test.ts
@@ -258,13 +258,14 @@ describe("resolveEnvironmentExecutionTarget", () => {
});
});
- it("resolves sandbox targets for every remote-managed adapter, including grok_local", async () => {
+ it("resolves sandbox targets for every remote-managed adapter, including grok_local and kimi_local", async () => {
for (const adapterType of [
"claude_local",
"codex_local",
"cursor",
"gemini_local",
"grok_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]) {
@@ -358,6 +359,42 @@ describe("resolveEnvironmentExecutionTarget", () => {
});
});
+ it("resolves SSH execution targets for kimi_local", async () => {
+ mockResolveEnvironmentDriverConfigForRuntime.mockResolvedValue({
+ driver: "ssh",
+ config: {
+ host: "ssh.example.test",
+ port: 22,
+ username: "paperclip",
+ remoteWorkspacePath: "/srv/paperclip",
+ privateKey: "PRIVATE KEY",
+ knownHosts: "[ssh.example.test]:22 ssh-ed25519 AAAA",
+ strictHostKeyChecking: true,
+ },
+ });
+
+ const target = await resolveEnvironmentExecutionTarget({
+ db: {} as never,
+ companyId: "company-1",
+ adapterType: "kimi_local",
+ environment: {
+ id: "env-ssh-1",
+ driver: "ssh",
+ config: {},
+ },
+ leaseId: "lease-ssh-1",
+ leaseMetadata: {},
+ lease: null,
+ environmentRuntime: null,
+ });
+
+ expect(target).toMatchObject({
+ kind: "remote",
+ transport: "ssh",
+ remoteCwd: "/srv/paperclip",
+ });
+ });
+
it("resolves SSH execution targets in bridge mode", async () => {
mockResolveEnvironmentDriverConfigForRuntime.mockResolvedValue({
driver: "ssh",
diff --git a/server/src/__tests__/kimi-local-skill-sync.test.ts b/server/src/__tests__/kimi-local-skill-sync.test.ts
new file mode 100644
index 0000000000..7bb904252a
--- /dev/null
+++ b/server/src/__tests__/kimi-local-skill-sync.test.ts
@@ -0,0 +1,51 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+ listKimiSkills,
+ syncKimiSkills,
+} from "@paperclipai/adapter-kimi-local/server";
+
+async function makeTempDir(prefix: string): Promise<string> {
+ return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+describe("kimi local skill sync", () => {
+ const paperclipKey = "paperclipai/paperclip/paperclip";
+ const cleanupDirs = new Set<string>();
+
+ afterEach(async () => {
+ await Promise.all(Array.from(cleanupDirs).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+ cleanupDirs.clear();
+ });
+
+ it("reports configured Paperclip skills and installs them into the Kimi skills home", async () => {
+ const kimiCodeHome = await makeTempDir("paperclip-kimi-skill-sync-");
+ cleanupDirs.add(kimiCodeHome);
+
+ const ctx = {
+ agentId: "agent-1",
+ companyId: "company-1",
+ adapterType: "kimi_local",
+ config: {
+ env: {
+ KIMI_CODE_HOME: kimiCodeHome,
+ },
+ paperclipSkillSync: {
+ desiredSkills: [paperclipKey],
+ },
+ },
+ } as const;
+
+ const before = await listKimiSkills(ctx);
+ expect(before.adapterType).toBe("kimi_local");
+ expect(before.mode).toBe("persistent");
+ expect(before.desiredSkills).toContain(paperclipKey);
+ expect(before.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("missing");
+
+ const after = await syncKimiSkills(ctx, [paperclipKey]);
+ expect(after.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");
+ expect((await fs.lstat(path.join(kimiCodeHome, "skills", "paperclip"))).isSymbolicLink()).toBe(true);
+ });
+});
diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.ts
index 505162f7ed..aaaf28cabd 100644
--- a/server/src/adapters/builtin-adapter-types.ts
+++ b/server/src/adapters/builtin-adapter-types.ts
@@ -11,6 +11,7 @@ export const BUILTIN_ADAPTER_TYPES = new Set([
"grok_local",
"hermes_gateway",
"hermes_local",
+ "kimi_local",
"openclaw_gateway",
"opencode_local",
"pi_local",
diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.ts
index dd5f539bcb..f71352dedb 100644
--- a/server/src/adapters/registry.ts
+++ b/server/src/adapters/registry.ts
@@ -88,6 +88,17 @@ import {
agentConfigurationDoc as grokAgentConfigurationDoc,
models as grokModels,
} from "@paperclipai/adapter-grok-local";
+import {
+ execute as kimiExecute,
+ listKimiSkills,
+ syncKimiSkills,
+ testEnvironment as kimiTestEnvironment,
+ sessionCodec as kimiSessionCodec,
+} from "@paperclipai/adapter-kimi-local/server";
+import {
+ agentConfigurationDoc as kimiAgentConfigurationDoc,
+ models as kimiModels,
+} from "@paperclipai/adapter-kimi-local";
import {
createHermesGatewayServerAdapter,
createHermesLocalServerAdapter,
@@ -412,6 +423,32 @@ const grokLocalAdapter: ServerAdapterModule = {
agentConfigurationDoc: grokAgentConfigurationDoc,
};
+const kimiLocalAdapter: ServerAdapterModule = {
+ type: "kimi_local",
+ execute: kimiExecute,
+ testEnvironment: kimiTestEnvironment,
+ acp: {
+ agentId: "kimi",
+ skillsMode: "ephemeral",
+ prerequisites: {
+ nodeRange: ">=20.0.0",
+ packages: ["@moonshot-ai/kimi-code"],
+ },
+ },
+ listSkills: listKimiSkills,
+ syncSkills: syncKimiSkills,
+ sessionCodec: kimiSessionCodec,
+ sessionManagement: getAdapterSessionManagement("kimi_local") ?? undefined,
+ models: kimiModels,
+ supportsLocalAgentJwt: true,
+ supportsInstructionsBundle: true,
+ instructionsPathKey: "instructionsFilePath",
+ requiresMaterializedRuntimeSkills: true,
+ getRuntimeCommandSpec: (config) =>
+ buildNpmRuntimeCommandSpec(config, "kimi", "@moonshot-ai/kimi-code"),
+ agentConfigurationDoc: kimiAgentConfigurationDoc,
+};
+
const hermesGatewayAdapter = createHermesGatewayServerAdapter();
const hermesLocalAdapter = createHermesLocalServerAdapter();
@@ -488,6 +525,7 @@ function registerBuiltInAdapters() {
cursorLocalAdapter,
geminiLocalAdapter,
grokLocalAdapter,
+ kimiLocalAdapter,
hermesGatewayAdapter,
hermesLocalAdapter,
openclawGatewayAdapter,
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 14e4a6a49b..e5f6d356ce 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -149,6 +149,7 @@ import {
import type { AdapterAuthSessionOwnerResponse } from "@paperclipai/shared";
import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";
import { DEFAULT_OPENCODE_LOCAL_MODEL } from "@paperclipai/adapter-opencode-local";
import { requireOpenCodeModelId } from "@paperclipai/adapter-opencode-local/server";
import {
@@ -276,6 +277,7 @@ export function agentRoutes(
codex_local: "instructionsFilePath",
droid_local: "instructionsFilePath",
gemini_local: "instructionsFilePath",
+ kimi_local: "instructionsFilePath",
opencode_local: "instructionsFilePath",
cursor: "instructionsFilePath",
pi_local: "instructionsFilePath",
@@ -1850,6 +1852,10 @@ export function agentRoutes(
next.model = DEFAULT_GEMINI_LOCAL_MODEL;
return ensureGatewayDeviceKey(adapterType, next);
}
+ if (adapterType === "kimi_local" && !asNonEmptyString(next.model)) {
+ next.model = DEFAULT_KIMI_LOCAL_MODEL;
+ return ensureGatewayDeviceKey(adapterType, next);
+ }
if (adapterType === "opencode_local" && !asNonEmptyString(next.model)) {
next.model = DEFAULT_OPENCODE_LOCAL_MODEL;
return ensureGatewayDeviceKey(adapterType, next);
diff --git a/server/src/services/company-portability.ts b/server/src/services/company-portability.ts
index f3770d504e..ecc17fc4e5 100644
--- a/server/src/services/company-portability.ts
+++ b/server/src/services/company-portability.ts
@@ -770,6 +770,10 @@ const ADAPTER_DEFAULT_RULES_BY_TYPE: Record<string, Array<{ path: string[]; valu
{ path: ["timeoutSec"], value: 0 },
{ path: ["graceSec"], value: 15 },
],
+ kimi_local: [
+ { path: ["timeoutSec"], value: 0 },
+ { path: ["graceSec"], value: 15 },
+ ],
opencode_local: [
{ path: ["timeoutSec"], value: 0 },
{ path: ["graceSec"], value: 15 },
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 6a74c765c3..1882fa514c 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -470,6 +470,7 @@ const GIT_SENSITIVE_LOCAL_ADAPTER_TYPES = new Set([
"gemini_local",
"grok_local",
"hermes_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]);
@@ -770,6 +771,7 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([
"cursor",
"gemini_local",
"hermes_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]);
diff --git a/server/src/services/recovery/service.ts b/server/src/services/recovery/service.ts
index ec31c026c8..dcddb30ae8 100644
--- a/server/src/services/recovery/service.ts
+++ b/server/src/services/recovery/service.ts
@@ -102,6 +102,7 @@ const SESSIONED_LOCAL_ADAPTERS = new Set([
"cursor",
"gemini_local",
"hermes_local",
+ "kimi_local",
"opencode_local",
"pi_local",
]);
diff --git a/ui/package.json b/ui/package.json
index 28eca24ca2..765857ad79 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -41,6 +41,7 @@
"@paperclipai/adapter-cursor-local": "workspace:*",
"@paperclipai/adapter-gemini-local": "workspace:*",
"@paperclipai/adapter-grok-local": "workspace:*",
+ "@paperclipai/adapter-kimi-local": "workspace:*",
"@paperclipai/adapter-openclaw-gateway": "workspace:*",
"@paperclipai/adapter-opencode-local": "workspace:*",
"@paperclipai/adapter-pi-local": "workspace:*",
diff --git a/ui/src/adapters/adapter-display-registry.test.ts b/ui/src/adapters/adapter-display-registry.test.ts
index 6d23749710..0b34460347 100644
--- a/ui/src/adapters/adapter-display-registry.test.ts
+++ b/ui/src/adapters/adapter-display-registry.test.ts
@@ -10,6 +10,7 @@ describe("adapter display registry", () => {
expect(getAdapterLabel("cursor")).toBe("Cursor");
expect(getAdapterLabel("gemini_local")).toBe("Gemini CLI");
expect(getAdapterLabel("grok_local")).toBe("Grok Build");
+ expect(getAdapterLabel("kimi_local")).toBe("Kimi Code");
expect(getAdapterLabel("hermes_local")).toBe("Hermes");
expect(getAdapterLabel("hermes_gateway")).toBe("Hermes Gateway");
expect(getAdapterLabel("opencode_local")).toBe("OpenCode");
@@ -22,6 +23,7 @@ describe("adapter display registry", () => {
cursor: "Cursor",
gemini_local: "Gemini CLI",
grok_local: "Grok Build",
+ kimi_local: "Kimi Code",
hermes_local: "Hermes",
hermes_gateway: "Hermes Gateway",
opencode_local: "OpenCode",
diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.ts
index 4b7013fc06..91e3899947 100644
--- a/ui/src/adapters/adapter-display-registry.ts
+++ b/ui/src/adapters/adapter-display-registry.ts
@@ -10,6 +10,7 @@ import {
Bot,
Code,
Gem,
+ Moon,
MousePointer2,
Sparkles,
Terminal,
@@ -89,6 +90,11 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {
description: "Grok Build harness",
icon: Bot,
},
+ kimi_local: {
+ label: "Kimi Code",
+ description: "Kimi Code CLI harness",
+ icon: Moon,
+ },
hermes_gateway: {
label: "Hermes Gateway",
description: "Remote Hermes API server",
diff --git a/ui/src/adapters/kimi-local/config-fields.tsx b/ui/src/adapters/kimi-local/config-fields.tsx
new file mode 100644
index 0000000000..351a4cad4d
--- /dev/null
+++ b/ui/src/adapters/kimi-local/config-fields.tsx
@@ -0,0 +1,51 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+ DraftInput,
+ Field,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+ "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+ "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Prepended to the Kimi prompt at runtime.";
+
+export function KimiLocalConfigFields({
+ isCreate,
+ values,
+ set,
+ config,
+ eff,
+ mark,
+ hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+ if (hideInstructionsFile) return null;
+ return (
+ <>
+ <Field label="Agent instructions file" hint={instructionsFileHint}>
+ <div className="flex items-center gap-2">
+ <DraftInput
+ value={
+ isCreate
+ ? values!.instructionsFilePath ?? ""
+ : eff(
+ "adapterConfig",
+ "instructionsFilePath",
+ String(config.instructionsFilePath ?? ""),
+ )
+ }
+ onCommit={(v) =>
+ isCreate
+ ? set!({ instructionsFilePath: v })
+ : mark("adapterConfig", "instructionsFilePath", v || undefined)
+ }
+ immediate
+ className={inputClass}
+ placeholder="/absolute/path/to/AGENTS.md"
+ />
+ <ChoosePathButton />
+ </div>
+ </Field>
+ </>
+ );
+}
diff --git a/ui/src/adapters/kimi-local/index.ts b/ui/src/adapters/kimi-local/index.ts
new file mode 100644
index 0000000000..9b9b287609
--- /dev/null
+++ b/ui/src/adapters/kimi-local/index.ts
@@ -0,0 +1,20 @@
+import type { UIAdapterModule } from "../types";
+import { parseKimiStdoutLine } from "@paperclipai/adapter-kimi-local/ui";
+import { KimiLocalConfigFields } from "./config-fields";
+import { buildKimiLocalConfig } from "@paperclipai/adapter-kimi-local/ui";
+
+export const kimiLocalUIAdapter: UIAdapterModule = {
+ type: "kimi_local",
+ label: "Kimi Code",
+ parseStdoutLine: parseKimiStdoutLine,
+ ConfigFields: KimiLocalConfigFields,
+ buildAdapterConfig: buildKimiLocalConfig,
+ // Kimi streams token-level deltas (~16k per run, ~50x a comparable Claude
+ // run): keep a wide transcript window so heartbeats don't drop rendered
+ // content mid-run, and render live reasoning as a scrollable log instead of
+ // the one-line ticker.
+ transcriptPresentation: {
+ maxVisibleEntries: 400,
+ liveReasoningView: "scrollLog",
+ },
+};
diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.ts
index c4d6b009c0..38345e24fa 100644
--- a/ui/src/adapters/registry.ts
+++ b/ui/src/adapters/registry.ts
@@ -5,6 +5,7 @@ import { cursorCloudUIAdapter } from "./cursor-cloud";
import { cursorLocalUIAdapter } from "./cursor";
import { geminiLocalUIAdapter } from "./gemini-local";
import { grokLocalUIAdapter } from "./grok-local";
+import { kimiLocalUIAdapter } from "./kimi-local";
import { hermesGatewayUIAdapter } from "./hermes-gateway";
import { hermesLocalUIAdapter } from "./hermes-local";
import { openCodeLocalUIAdapter } from "./opencode-local";
@@ -57,6 +58,7 @@ function registerBuiltInUIAdapters() {
cursorCloudUIAdapter,
geminiLocalUIAdapter,
grokLocalUIAdapter,
+ kimiLocalUIAdapter,
hermesGatewayUIAdapter,
hermesLocalUIAdapter,
openCodeLocalUIAdapter,
diff --git a/ui/src/adapters/transcript.test.ts b/ui/src/adapters/transcript.test.ts
index 56627f328a..768909311c 100644
--- a/ui/src/adapters/transcript.test.ts
+++ b/ui/src/adapters/transcript.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import { buildTranscript, type RunLogChunk } from "./transcript";
import { grokLocalUIAdapter } from "./grok-local";
+import { kimiLocalUIAdapter } from "./kimi-local";
import type { UIAdapterModule } from "./types";
describe("buildTranscript", () => {
@@ -199,4 +200,31 @@ describe("buildTranscript", () => {
{ kind: "system", ts, text: "stop_reason=EndTurn session=sess-1" },
]);
});
+
+ it("coalesces kimi_local ACP text deltas into one assistant entry", () => {
+ const entries = buildTranscript(
+ [
+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "acpx.text_delta", channel: "output", text: "Hello " })}\n` },
+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "acpx.text_delta", channel: "output", text: "world" })}\n` },
+ { ts, stream: "stdout", chunk: `${JSON.stringify({ type: "acpx.result", summary: "done", stopReason: "end_turn" })}\n` },
+ ],
+ kimiLocalUIAdapter,
+ );
+
+ expect(entries).toEqual([
+ { kind: "assistant", ts, text: "Hello world", delta: true },
+ {
+ kind: "result",
+ ts,
+ text: "done",
+ inputTokens: 0,
+ outputTokens: 0,
+ cachedTokens: 0,
+ costUsd: 0,
+ subtype: "end_turn",
+ isError: false,
+ errors: [],
+ },
+ ]);
+ });
});
diff --git a/ui/src/adapters/use-adapter-capabilities.ts b/ui/src/adapters/use-adapter-capabilities.ts
index 78d81f5d33..55abb33ded 100644
--- a/ui/src/adapters/use-adapter-capabilities.ts
+++ b/ui/src/adapters/use-adapter-capabilities.ts
@@ -22,6 +22,7 @@ const KNOWN_DEFAULTS: Record<string, AdapterCapabilities> = {
cursor: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true, supportsAcp: false },
gemini_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true, supportsAcp: true },
grok_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false, supportsAcp: false },
+ kimi_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false, supportsAcp: true },
opencode_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true, supportsAcp: false },
pi_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false, supportsAcp: false },
openclaw_gateway: ALL_FALSE,
diff --git a/ui/src/components/AgentConfigForm.render.test.tsx b/ui/src/components/AgentConfigForm.render.test.tsx
index 60ed57ca94..c36cc362fd 100644
--- a/ui/src/components/AgentConfigForm.render.test.tsx
+++ b/ui/src/components/AgentConfigForm.render.test.tsx
@@ -742,6 +742,28 @@ describe("AgentConfigForm environment selector", () => {
expect(selector?.textContent).toContain("E2B · sandbox");
});
+ it("shows the environment override for Kimi local agents", async () => {
+ const result = await renderForm(
+ [
+ makeEnvironment({ id: "local-1", name: "Local", driver: "local" }),
+ makeEnvironment({
+ id: "sandbox-1",
+ name: "E2B",
+ driver: "sandbox",
+ config: { provider: "e2b" },
+ }),
+ ],
+ { adapterType: "kimi_local" },
+ );
+ roots.push(result.root);
+
+ const text = result.container.textContent ?? "";
+ const selector = result.container.querySelector("select");
+
+ expect(text).toContain("Environment override");
+ expect(selector?.textContent).toContain("E2B · sandbox");
+ });
+
it("keeps an existing non-runnable override visible so it can be cleared", async () => {
const result = await renderForm(
[
diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsx
index aded4092e3..c7e9ee8cac 100644
--- a/ui/src/components/AgentConfigForm.tsx
+++ b/ui/src/components/AgentConfigForm.tsx
@@ -21,6 +21,7 @@ import { assetsApi } from "../api/assets";
import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX } from "@paperclipai/adapter-codex-local";
import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";
import { DEFAULT_OPENCODE_LOCAL_MODEL } from "@paperclipai/adapter-opencode-local";
import {
Popover,
@@ -200,6 +201,15 @@ const claudeThinkingEffortOptions = [
{ id: "high", label: "High" },
] as const;
+// Kimi exposes low/high/max (no "medium") via each model's support_efforts;
+// the kimi_local adapter maps a legacy "medium" onto "high" at runtime.
+const kimiThinkingEffortOptions = [
+ { id: "", label: "Auto" },
+ { id: "low", label: "Low" },
+ { id: "high", label: "High" },
+ { id: "max", label: "Max" },
+] as const;
+
const MAX_TURN_CONTINUATION_DEFAULT_MAX_ATTEMPTS = 2;
const MAX_TURN_CONTINUATION_MAX_ATTEMPTS_CAP = 10;
const MAX_TURN_CONTINUATION_DEFAULT_DELAY_SEC = 1;
@@ -1097,7 +1107,9 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
? cursorModeOptions
: adapterType === "opencode_local"
? openCodeThinkingEffortOptions
- : claudeThinkingEffortOptions;
+ : adapterType === "kimi_local"
+ ? kimiThinkingEffortOptions
+ : claudeThinkingEffortOptions;
const currentThinkingEffort = isCreate
? val!.thinkingEffort
: adapterType === "codex_local"
@@ -1452,6 +1464,8 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX;
} else if (t === "gemini_local") {
nextValues.model = DEFAULT_GEMINI_LOCAL_MODEL;
+ } else if (t === "kimi_local") {
+ nextValues.model = DEFAULT_KIMI_LOCAL_MODEL;
} else if (t === "cursor") {
nextValues.model = DEFAULT_CURSOR_LOCAL_MODEL;
} else if (t === "opencode_local") {
@@ -1469,6 +1483,8 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
model:
t === "gemini_local"
? DEFAULT_GEMINI_LOCAL_MODEL
+ : t === "kimi_local"
+ ? DEFAULT_KIMI_LOCAL_MODEL
: t === "opencode_local"
? DEFAULT_OPENCODE_LOCAL_MODEL
: t === "cursor"
@@ -1583,6 +1599,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
claude_local: "claude",
codex_local: "codex",
gemini_local: "gemini",
+ kimi_local: "kimi",
pi_local: "pi",
cursor: "agent",
opencode_local: "opencode",
diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsx
index 8c23e267e8..3d7267c54b 100644
--- a/ui/src/components/OnboardingWizard.tsx
+++ b/ui/src/components/OnboardingWizard.tsx
@@ -44,6 +44,7 @@ import { buildNewAgentRuntimeConfig } from "../lib/new-agent-runtime-config";
import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX } from "@paperclipai/adapter-codex-local";
import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";
import { DEFAULT_OPENCODE_LOCAL_MODEL, isValidOpenCodeModelId } from "@paperclipai/adapter-opencode-local";
import {
canGoBackFromOnboardingStep,
@@ -658,6 +659,7 @@ function OnboardingWizardInner({
adapterType === "claude_local" ||
adapterType === "codex_local" ||
adapterType === "gemini_local" ||
+ adapterType === "kimi_local" ||
adapterType === "opencode_local" ||
adapterType === "pi_local" ||
adapterType === "cursor";
@@ -717,6 +719,7 @@ function OnboardingWizardInner({
claude_local: "claude",
codex_local: "codex",
gemini_local: "gemini",
+ kimi_local: "kimi",
pi_local: "pi",
cursor: "agent",
opencode_local: "opencode",
@@ -929,6 +932,8 @@ function OnboardingWizardInner({
model:
adapterType === "gemini_local"
? model || DEFAULT_GEMINI_LOCAL_MODEL
+ : adapterType === "kimi_local"
+ ? model || DEFAULT_KIMI_LOCAL_MODEL
: adapterType === "cursor"
? model || DEFAULT_CURSOR_LOCAL_MODEL
: adapterType === "opencode_local"
@@ -1863,6 +1868,10 @@ function OnboardingWizardInner({
setModel(DEFAULT_GEMINI_LOCAL_MODEL);
return;
}
+ if (nextType === "kimi_local" && !model) {
+ setModel(DEFAULT_KIMI_LOCAL_MODEL);
+ return;
+ }
if (nextType === "cursor" && !model) {
setModel(DEFAULT_CURSOR_LOCAL_MODEL);
return;
@@ -2063,6 +2072,8 @@ function OnboardingWizardInner({
? `${effectiveAdapterCommand} exec --json -`
: adapterType === "gemini_local"
? `${effectiveAdapterCommand} --output-format json "Respond with hello."`
+ : adapterType === "kimi_local"
+ ? `${effectiveAdapterCommand} -p "Respond with hello." --output-format stream-json`
: adapterType === "opencode_local"
? `${effectiveAdapterCommand} run --format json "Respond with hello."`
: `${effectiveAdapterCommand} --print - --output-format stream-json --verbose`}
@@ -2074,6 +2085,7 @@ function OnboardingWizardInner({
{adapterType === "cursor" ||
adapterType === "codex_local" ||
adapterType === "gemini_local" ||
+ adapterType === "kimi_local" ||
adapterType === "opencode_local" ? (
<p className="text-muted-foreground">
If auth fails, set{" "}
@@ -2082,6 +2094,8 @@ function OnboardingWizardInner({
? "CURSOR_API_KEY"
: adapterType === "gemini_local"
? "GEMINI_API_KEY"
+ : adapterType === "kimi_local"
+ ? "KIMI_MODEL_NAME + KIMI_MODEL_API_KEY"
: "OPENAI_API_KEY"}
</span>{" "}
in env or run{" "}
@@ -2092,6 +2106,8 @@ function OnboardingWizardInner({
? "codex login"
: adapterType === "gemini_local"
? "gemini auth"
+ : adapterType === "kimi_local"
+ ? "kimi login"
: "opencode auth login"}
</span>
.
diff --git a/ui/src/pages/InviteLanding.tsx b/ui/src/pages/InviteLanding.tsx
index 242ecf058c..3ac1e9ca26 100644
--- a/ui/src/pages/InviteLanding.tsx
+++ b/ui/src/pages/InviteLanding.tsx
@@ -23,6 +23,7 @@ const ENABLED_INVITE_ADAPTERS = new Set([
"claude_local",
"codex_local",
"gemini_local",
+ "kimi_local",
"opencode_local",
"pi_local",
"cursor",
diff --git a/ui/src/pages/NewAgent.tsx b/ui/src/pages/NewAgent.tsx
index 78a69a1b6c..8fcc815865 100644
--- a/ui/src/pages/NewAgent.tsx
+++ b/ui/src/pages/NewAgent.tsx
@@ -40,6 +40,7 @@ import { buildPermissionsForTrustPreset, getTrustPreset } from "../lib/trust-pol
import { DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX } from "@paperclipai/adapter-codex-local";
import { DEFAULT_CURSOR_LOCAL_MODEL } from "@paperclipai/adapter-cursor-local";
import { DEFAULT_GEMINI_LOCAL_MODEL } from "@paperclipai/adapter-gemini-local";
+import { DEFAULT_KIMI_LOCAL_MODEL } from "@paperclipai/adapter-kimi-local";
import { DEFAULT_OPENCODE_LOCAL_MODEL, isValidOpenCodeModelId } from "@paperclipai/adapter-opencode-local";
function createValuesForAdapterType(
@@ -52,6 +53,8 @@ function createValuesForAdapterType(
DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX;
} else if (adapterType === "gemini_local") {
nextValues.model = DEFAULT_GEMINI_LOCAL_MODEL;
+ } else if (adapterType === "kimi_local") {
+ nextValues.model = DEFAULT_KIMI_LOCAL_MODEL;
} else if (adapterType === "cursor") {
nextValues.model = DEFAULT_CURSOR_LOCAL_MODEL;
} else if (adapterType === "opencode_local") {
diff --git a/vitest.config.ts b/vitest.config.ts
index 10649e7c93..f4dda31b46 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -13,6 +13,7 @@ export default defineConfig({
"packages/adapters/cursor-local",
"packages/adapters/gemini-local",
"packages/adapters/grok-local",
+ "packages/adapters/kimi-local",
"packages/adapters/openclaw-gateway",
"packages/adapters/opencode-local",
"packages/adapters/pi-local",