# What Is the Role of JSON-RPC in the Copilot SDK Architecture?

> Discover how JSON-RPC in the Copilot SDK architecture facilitates typed, request-response communication between the SDK API and CLI runtime via MessageConnection, powering seamless integration.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: internals
- Published: 2026-06-05

---

**JSON-RPC is the transport protocol that connects the Copilot SDK's high-level API to the Copilot CLI runtime, enabling typed, request-response communication over a `MessageConnection`.**

The Copilot SDK uses JSON-RPC as its exclusive wire format for all client-side operations, from session creation to tool invocation. According to the `github/copilot-sdk` repository, every method call in the SDK is ultimately serialized as a JSON-RPC message and sent across a connection managed by the **vscode-jsonrpc** library. Understanding this architecture is essential for debugging, extending, or directly interfacing with the underlying RPC surface.

## JSON-RPC as the Core Transport Protocol

All communication between the SDK and the Copilot CLI process flows through JSON-RPC. This design provides a language-agnostic, error-aware channel that standardizes how the client and runtime exchange messages.

### Connection Establishment

The entry point is the **`CopilotClient`** class in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), which builds a **`MessageConnection`** using `createMessageConnection` from `vscode-jsonrpc`. Lines 22–28 instantiate and store this connection in a private `connection` field. When you call `client.start()`, the SDK spawns the CLI and performs the JSON-RPC handshake.

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient(); // spawns the CLI and creates a MessageConnection
await client.start();               // establishes the JSON-RPC link

```

The `start` method implements the full initialization sequence (see [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), lines 2090–2108).

### Typed RPC Surface

While raw JSON-RPC is untyped, the SDK generates strongly-typed wrappers to prevent runtime mismatches. The file [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) defines helpers such as `createServerRpc`, `createInternalServerRpc`, and `createSessionRpc`. These factories wrap the raw `MessageConnection` and expose methods like `session.create`, `session.resume`, and `options.update` (lines 10264–10268). The wrappers are produced by [`scripts/codegen/typescript.ts`](https://github.com/github/copilot-sdk/blob/main/scripts/codegen/typescript.ts), which generates the RPC module from the protocol definition.

```typescript
// Directly use the generated RPC helper for a low-level call
await client.rpc.options.update({ enableSessionTelemetry: true });

```

The `client.rpc` object is the result of `createServerRpc(connection)`, giving you type-safe access to every server capability without manually formatting JSON-RPC payloads.

## Request/Response Lifecycle

Every high-level SDK operation maps to a JSON-RPC request. When `CopilotClient` needs to create a session, it calls `this.connection!.sendRequest("session.create", …)`. The `vscode-jsonrpc` library serializes the method name and parameters into a standard JSON-RPC object, transmits it over STDIO or TCP, then awaits the matching response (see [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), lines 2095–2102).

```typescript
const session = await client.createSession({
  model: "gpt-4",
  tools: [{ name: "weather", description: "...", parameters: {} }],
});

```

Under the hood, this executes:

```typescript
await this.connection!.sendRequest("session.create", { /* ... */ });

```

This request/response model ensures that synchronous-looking SDK code remains non-blocking while preserving strict ordering and id matching.

## Error Handling Over JSON-RPC

JSON-RPC errors are first-class objects in the SDK. The [`client.ts`](https://github.com/github/copilot-sdk/blob/main/client.ts) file imports `ResponseError` and `ConnectionError` directly from `vscode-jsonrpc` (lines 21–26). When a JSON-RPC response contains an error code or the transport drops, the library raises these exceptions into the SDK's JavaScript error model. This gives consumers a predictable recovery path without parsing raw JSON payloads and keeps error handling consistent with standard Node.js patterns.

```typescript
try {
  await client.rpc.session.getState({ sessionId: "abc" });
} catch (e) {
  if (e instanceof ResponseError) {
    console.error("RPC error:", e.message);
  }
}

```

## Summary

- **JSON-RPC is the exclusive transport** between the Copilot SDK and the Copilot CLI runtime, managed through `vscode-jsonrpc`.
- **`CopilotClient`** establishes the connection in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts) and exposes it through generated typed wrappers in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts).
- **All SDK operations**, such as `session.create`, are issued as JSON-RPC requests via `sendRequest` and processed through a standard request/response lifecycle.
- **Errors** like `ResponseError` are forwarded directly from the JSON-RPC layer, providing a unified exception model across the SDK.

## Frequently Asked Questions

### What transport does the Copilot SDK use to communicate with the Copilot CLI?

The Copilot SDK communicates with the CLI exclusively over JSON-RPC. The SDK creates a `MessageConnection` using `createMessageConnection` from `vscode-jsonrpc`, then sends all operations as JSON-RPC requests over STDIO or TCP.

### How does the Copilot SDK expose typed methods if JSON-RPC is untyped?

The SDK uses auto-generated helpers in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts). Functions such as `createServerRpc` wrap the raw `MessageConnection` and expose strongly-typed methods—including `session.create` and `options.update`—while still serializing calls as standard JSON-RPC messages under the hood.

### Where does the Copilot SDK handle JSON-RPC errors?

JSON-RPC errors are surfaced directly in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), which imports `ResponseError` and `ConnectionError` from `vscode-jsonrpc`. These propagate as native JavaScript exceptions, allowing callers to handle transport or protocol failures with standard `try/catch` blocks.

### Which source files define the JSON-RPC integration?

The core integration lives in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), which manages the `MessageConnection`. The typed wrappers are auto-generated in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) by [`scripts/codegen/typescript.ts`](https://github.com/github/copilot-sdk/blob/main/scripts/codegen/typescript.ts), while [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) consumes the RPC surface to issue calls such as `session.send`.