ACP TypeScript SDK

The ACP TypeScript SDK is the official implementation of the Agent Client Protocol, a standardized JSON-RPC-based protocol that lets code editors and AI-powered coding agents communicate over a common interface instead of each editor integrating each agent one-off. It ships typed builders for both sides of the protocol: agent({ name }) for implementing an agent that registers initialize, newSession, and prompt handlers, and client({ name }) for implementing an editor-side client that registers handlers like requestPermission and sessionUpdate.

Beyond the core stdio JSON-RPC connection, the SDK exposes experimental transports for HTTP streaming, WebSockets, and a Node.js process adapter, plus a Zod-validated, generated schema layer so protocol messages are type-checked at compile time. It backs production integrations such as the Gemini CLI’s editor integration and is consumed directly by editors like Zed.

What You Get

• Typed agent({ name }) and client({ name }) builder APIs for implementing either side of the ACP protocol
• A core JSON-RPC connection layer (connection.ts, jsonrpc.ts) handling request/response correlation, notifications, and error propagation
• Generated, Zod-validated schema types (schema/zod.gen.js, schema/types.gen.js) kept in sync with the protocol specification
• Experimental transport adapters for HTTP streaming, WebSockets, and Node.js process I/O beyond the default stdio stream
• Runtime narrowing helpers (declaration-merged guards) for extensible protocol unions like CreateElicitationResponse
• Working example implementations of both Agents and Clients under src/examples

Common Use Cases

• Building a new AI coding agent that needs to speak a standard protocol to any ACP-compatible editor
• Adding ACP client support to a code editor so it can drive third-party coding agents
• Wiring an agent’s prompt/sessionUpdate flow into an editor’s UI via typed handler registration
• Prototyping agent/client behavior locally using the bundled example implementations
• Bridging an existing agent (e.g. a CLI-based coding assistant) into ACP via the Node.js process adapter

Under The Hood

Architecture: The package is organized around a central acp.ts entrypoint (~4,200 lines) that re-exports generated schema types and guards, and layers typed agent()/client() builder functions over a lower-level JSON-RPC engine split across connection.ts (message routing/handler registration) and jsonrpc.ts (~1,400 lines: request IDs, correlation, RequestError, notification dispatch); transport concerns are decoupled from protocol logic through a Stream interface implemented separately for stdio, HTTP (http-stream.ts), WebSockets (ws-stream.ts, ws-server.ts), and Node.js child processes (node-adapter.ts). Tech Stack: Modern TypeScript (ESM-only, type: module) targeting Node.js, with Zod as a peer dependency for schema validation, ws for WebSocket transport, and a generated schema layer produced via @hey-api/openapi-ts from the protocol specification, keeping hand-written code and generated code (*.gen.ts) clearly separated. Code Quality: Every core module has a co-located .test.ts file (connection, jsonrpc, server, sse, ws-stream, schema-deserialize, cookie-store) run under Vitest, and the check script chains lint, format-check, spellcheck, build, test, and TypeDoc verification, indicating a CI-enforced quality bar; tsc strictness plus generated Zod schemas gives both compile-time and runtime type safety. API Design: The builder pattern (agent({...}).initialize(...).newSession(...).prompt(...)) reads as a fluent, discoverable surface that only requires implementing the handlers relevant to one’s role, while re-exporting protocol constants (AGENT_METHODS, CLIENT_METHODS, PROTOCOL_VERSION) keeps consumers aligned with the spec without hardcoding method name strings.