Protocol Negotiation Focus Deep-Dive

🎯 The Problem

The CLI is released on its own cadence; SDKs are released on theirs. Users install @github/copilot-sdk@0.3 today but upgrade the CLI tomorrow (npm i -g @github/copilot@latest). Or vice versa — a Python environment pinned at a specific SDK interacts with a freshly updated bundled CLI. The SDK must not assume version equality, but also must not silently degrade. Specific risks:

• A new event type ships that older SDKs don't know — causes JsonConverter exceptions in .NET.
• A method's parameter shape changes — silently sends malformed JSON and gets -32602 errors with no context.
• Permissions v2 introduces a new result-shape; a v1 SDK would misinterpret v2 events as malformed.

🔧 The Approach

A two-value handshake: version + capabilities. The version is a single integer (currently 3). Capabilities are named strings that gate individual features. Capabilities avoid version-number inflation when a feature is opt-in (SDK doesn't need permissions_v2? Don't care whether the CLI has it).

Each SDK embeds its own generated SDK_PROTOCOL_VERSION (not a hand-picked constant; the codegen step emits it from the schema). The Node SDK additionally exposes MIN_PROTOCOL_VERSION = 2 — it can talk to any CLI with version ≥ 2, even though its own schema targets 3.

🔄 Why Not Alternatives?

Handshake Flow

sequenceDiagram
    participant SDK
    participant CLI
    SDK->>CLI: getStatus (req, id=1)
    CLI-->>SDK: {protocolVersion:3, capabilities:[...]} (resp, id=1)
    alt SDK.MIN_PROTOCOL_VERSION <= reported <= SDK.SDK_PROTOCOL_VERSION
        Note over SDK: cache negotiatedVersion & capabilities
        SDK->>CLI: first real request
    else reported < MIN
        Note over SDK: throw IncompatibleCLIError with hint
        SDK->>CLI: close pipes
    else reported > SDK_PROTOCOL_VERSION
        Note over SDK: pin to SDK's version; log warning
        SDK->>CLI: continue with best-effort
    end

Capability Flags

// nodejs/src/client.ts (conceptual)
const required = ["permissions_v2"]; // because we call session.onPermissionRequest
for (const cap of required) {
    if (!status.capabilities.includes(cap)) {
        throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
    }
}

# python/copilot/client.py
async def _negotiate(self):
    status = await self._rpc.get_status()
    if status.protocol_version < MIN_PROTOCOL_VERSION:
        raise RuntimeError(f"CLI protocol v{status.protocol_version} < minimum v{MIN_PROTOCOL_VERSION}")
    self._negotiated_version = min(status.protocol_version, SDK_PROTOCOL_VERSION)
    self._capabilities = set(status.capabilities)

// go/sdk_protocol_version.go
const SDKProtocolVersion = 3

func (c *Client) negotiate(ctx context.Context) error {
    status, err := c.rpc.GetStatus(ctx)
    if err != nil { return err }
    if status.ProtocolVersion < minProtocolVersion {
        return fmt.Errorf("CLI protocol %d below minimum %d", status.ProtocolVersion, minProtocolVersion)
    }
    c.negotiated = status.ProtocolVersion
    c.caps = make(map[string]bool, len(status.Capabilities))
    for _, cap := range status.Capabilities { c.caps[cap] = true }
    return nil
}

if (status.ProtocolVersion < MinProtocolVersion) {
    throw new IncompatibleCliException(
        $"The Copilot CLI reports protocol version {status.ProtocolVersion}, " +
        $"but this SDK requires at least {MinProtocolVersion}. " +
        "Upgrade the CLI with: npm i -g @github/copilot@latest");
}

Compatibility Matrix

Handshake in the Client Lifecycle

stateDiagram-v2
    [*] --> Spawned : subprocess OK
    Spawned --> Handshaking : send getStatus
    Handshaking --> Active : version & caps pass
    Handshaking --> Failed : version below MIN or missing capability
    Failed --> Stopped : close pipes
    Active --> Stopped : Stop()
    Stopped --> [*]

💥 Failure Recovery

If handshake fails, the SDK closes pipes, sends SIGTERM (CTRL_BREAK on Windows), and returns a typed error from Start(). There is no retry — version incompatibility is deterministic. The error string includes the exact version reported and the upgrade command. Pending tasks are rejected with the same error so await client.CreateSessionAsync() fails fast even if it was already queued.

Blast radius is minimal: a failed handshake leaves no user-visible state (no sessions created, no events emitted, no files written). The user either updates the CLI and retries or pins the SDK to an older version.

Edge Cases

Configuration

Directory Map

nodejs/
├── src/client.ts                    ← MIN_PROTOCOL_VERSION, negotiate()
└── src/generated/rpc.ts             ← SDK_PROTOCOL_VERSION

python/copilot/
├── client.py                        ← _negotiate()
└── _sdk_protocol_version.py         ← SDK_PROTOCOL_VERSION

go/
├── client.go                        ← negotiate()
└── sdk_protocol_version.go          ← SDKProtocolVersion

dotnet/src/
├── Client.cs                        ← NegotiateAsync()
└── SdkProtocolVersion.cs            ← constant

Related

• JSON-RPC Transport
• Codegen Pipeline