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

> Explore the acp-adapter package in kimi-code and understand how it bridges ACP capabilities like file systems and terminals as local services via dependency injection. Uncover the ACP server architecture.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: deep-dive
- Published: 2026-08-14

---

**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](https://github.com/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/acp-server/src/start.ts)**: Server bootstrap that wires ACP services and initializes the connection.
- **[`packages/acp-server/src/acp-client.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/acp-server/src/acp-fs/acpFsService.ts)**: Implements `IHostFileSystem` over the ACP protocol.
- **[`packages/acp-server/src/acp-terminal/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/acp-server/src/acp-terminal/index.ts)**: Registers agent-scoped terminal handling and session management.
- **[`packages/acp-server/src/convert.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/acp-server/src/convert.ts)**: Protocol-to-internal format conversion for content blocks.
- **[`packages/acp-server/src/modes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.