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

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, 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.

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, 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 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, which generates the RPC module from the protocol definition.

// 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, lines 2095–2102).

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

Under the hood, this executes:

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 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.

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 and exposes it through generated typed wrappers in 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. 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, 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, which manages the MessageConnection. The typed wrappers are auto-generated in nodejs/src/generated/rpc.ts by scripts/codegen/typescript.ts, while nodejs/src/session.ts consumes the RPC surface to issue calls such as session.send.

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