How Does the acp-adapter Package Work in kimi-code: A Deep Dive into ACP Server Architecture

The acp-adapter layer in kimi-code acts as a protocol bridge that exposes remote Agent Communication Protocol (ACP) capabilities—such as file systems and terminals—as local services through dependency injection.

The acp-adapter functionality resides within the packages/acp-server directory of the MoonshotAI/kimi-code repository. It enables the IDE to communicate with remote ACP servers by wrapping RPC calls into familiar interfaces like IHostFileSystem, allowing seamless remote development as if the resources were local.

What Is the acp-adapter in kimi-code?

Despite the conceptual name "acp-adapter," the implementation lives in packages/acp-server. This package transforms ACP (Agent Communication Protocol) messages into native service calls within the kimi-code architecture. It registers session-scoped and agent-scoped services in the DI container (@moonshot-ai/agent-core-v2), translating between the wire protocol and internal TypeScript interfaces.

Core Architecture and Responsibilities

The adapter handles three primary responsibilities to abstract remote resources.

Session-Level RPC Bridge

The AcpHostFileSystem class in packages/acp-server/src/acp-fs/acpFsService.ts implements the IHostFileSystem interface. It registers as a Session-scoped service in the DI container, forwarding methods like readTextFile and writeTextFile over the ACP channel. Errors from the remote side are prefixed with acp: to distinguish them from local failures.

Reverse-RPC for Terminal I/O

Terminal interaction uses reverse-RPC, allowing the server to push output to the client. The acp-terminal barrel (imported in packages/acp-server/src/start.ts) registers a terminal handler at Agent scope using the IAcpConnection interface. This listens for TerminalCreated events and attaches a TerminalSession to stream bidirectional I/O.

Client Bootstrap and Handshake

The acpClientFromContext function in packages/acp-server/src/acp-client.ts initializes the AcpClient from the current DI context. It extracts the IAcpConnection accessor, binds a fresh client instance, and returns it for use by other services, handling capability negotiation during setup.

Implementation Flow

Understanding the acp-adapter requires tracing the lifecycle from server startup to active RPC handling.

Server Bootstrap (start.ts)

The entry point at packages/acp-server/src/start.ts creates an IAcpConnection accessor and invokes acpClientFromContext to obtain an AcpClient tied to the current session. This establishes the communication channel used by all subsequent adapter services.

File System Service (acpFsService.ts)

Located at packages/acp-server/src/acp-fs/acpFsService.ts, this service implements the IHostFileSystem interface. Each method forwards requests over the ACP channel via the AcpClient, making remote file operations appear synchronous to the rest of the application layer.

Terminal Integration

The terminal module at packages/acp-server/src/acp-terminal/index.ts registers listeners on IAcpConnection. When the remote ACP server creates a terminal, the local client receives the event, instantiates a TerminalSession, and manages the input/output streams between the remote shell and the local UI.

Mode Management and Feature Toggles

The packages/acp-server/src/modes.ts file defines ACP mode identifiers (e.g., DEFAULT_MODE_ID) and the acpModeToToggles function. This translates mode strings into feature flags that enable or disable capabilities such as write access or terminal support, ensuring the adapter respects security constraints negotiated during the ACP handshake.

Content Conversion Utilities

The packages/acp-server/src/convert.ts module provides acpBlocksToContentParts, which transforms raw ACP protocol blocks—text, images, and markdown—into the internal ContentPart format used by kimi-code's transcript engine. It also exports compressPromptImageParts to optimize image payloads before LLM processing.

Working with the acp-adapter: Code Examples

Creating an ACP-Backed Session

import { startAcpServer } from '#/packages/acp-server/src/start';
import { Klient } from '#/packages/klient';

async function run() {
  const klient = new Klient();
  const server = await startAcpServer({
    clientInfo: { name: 'my-app' },
    client: klient,
  });

  // Access remote file system through the adapter
  const fs = server.acpConnection.accessor.get(IHostFileSystem);
  const content = await fs.readTextFile('/home/user/readme.md');
  console.log(content);
}
run();

Using the Terminal via ACP

import { AcpClient } from '#/packages/acp-server/src/acp-client';

async function openTerminal(acp: AcpClient) {
  const term = await acp.createTerminal({ cols: 80, rows: 24 });
  term.onOutput(data => process.stdout.write(data));
  term.write('ls -la\n');
}

Switching ACP Modes

import { setAcpMode } from '#/packages/acp-server/src/modes';

// Switch to read-only mode, disabling write-file operations
setAcpMode('read-only');

Key Source Files and Their Roles

• packages/acp-server/src/start.ts: Server bootstrap that wires ACP services and initializes the connection.
• packages/acp-server/src/acp-client.ts: Contains acpClientFromContext for creating AcpClient instances from the DI context.
• packages/acp-server/src/acp-fs/acpFsService.ts: Implements IHostFileSystem over the ACP protocol.
• packages/acp-server/src/acp-terminal/index.ts: Registers agent-scoped terminal handling and session management.
• packages/acp-server/src/convert.ts: Protocol-to-internal format conversion for content blocks.
• packages/acp-server/src/modes.ts: Defines mode identifiers and feature toggle mappings.

Summary

• The acp-adapter functionality lives in packages/acp-server within the MoonshotAI/kimi-code repository.
• AcpHostFileSystem exposes remote file systems as local IHostFileSystem services at session scope.
• Reverse-RPC via IAcpConnection enables real-time terminal streaming from remote ACP servers.
• acpClientFromContext bootstraps the client from the DI container, managing handshake and capability negotiation.
• Mode management in modes.ts restricts functionality through feature toggles based on the active ACP mode.
• All components wire together through the @moonshot-ai/agent-core-v2 DI container, presenting a unified interface to the rest of the IDE.

Frequently Asked Questions

Where is the acp-adapter package located in kimi-code?

The acp-adapter functionality is implemented within the packages/acp-server directory rather than a separate acp-adapter package. This directory contains the full implementation of the ACP protocol bridge, including client initialization, file system adapters, and terminal handlers.

How does the acp-adapter handle file system operations remotely?

The adapter uses the AcpHostFileSystem class in packages/acp-server/src/acp-fs/acpFsService.ts to implement the IHostFileSystem interface. Each local method call is forwarded over the ACP channel to the remote server, with results returned asynchronously. Errors are wrapped with an acp: prefix to indicate their remote origin.

What is the difference between Session-scoped and Agent-scoped services in the acp-adapter?

Session-scoped services like AcpHostFileSystem are instantiated per user session and manage resources like file handles. Agent-scoped services, such as the terminal handler in packages/acp-server/src/acp-terminal/index.ts, persist across the entire agent lifecycle and handle server-wide events like terminal creation notifications.

How does the acp-adapter manage different capability modes?

The packages/acp-server/src/modes.ts file defines the acpModeToToggles function, which maps mode identifiers (e.g., DEFAULT_MODE_ID) to feature flags. These toggles enable or disable specific capabilities—such as write access or terminal support—based on the security level negotiated during the initial ACP handshake.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}