Copilot SDK Streaming Event Types: Complete Guide to SessionEvent Handling

The Copilot SDK exposes twelve distinct streaming event types—including completion, toolCall, sessionStarted, and error—defined in the SessionEventType enum and handled via strongly-typed listeners in nodejs/src/types.ts.

The github/copilot-sdk repository implements a strongly-typed streaming event system that enables real-time communication between your application and GitHub Copilot models. At the heart of this system lies the SessionEvent union type and its corresponding SessionEventType enumeration, which define every possible event that can flow through a Copilot session. Understanding these Copilot SDK streaming event types is essential for building robust integrations that handle code completions, tool invocations, and lifecycle events as documented in [docs/features/streaming-events.md](https://github.com/github/copilot-sdk/blob/main/docs/features/streaming-events.md).

Core Event Architecture in nodejs/src/types.ts

The foundational definitions reside in [nodejs/src/types.ts](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts). Here, the SDK declares:

• SessionEventType – A TypeScript enum generated from the protocol schema, representing the discriminant type field for all possible events.
• SessionEvent – A discriminated union where each member corresponds to a specific event payload.

The type system ensures that event handlers receive precisely typed payloads through the TypedSessionEventHandler<K> generic, which maps each SessionEventType to its associated data structure. These definitions are generated during the build process via the codegen scripts located in scripts/codegen, ensuring the TypeScript definitions remain synchronized with the underlying protocol schema.

Complete List of Copilot SDK Streaming Event Types

The SessionEventType enum encompasses twelve distinct event categories that cover the full lifecycle of a Copilot interaction:

• completion – Delivers code‑completion results generated by the Copilot model during an active coding session.
• suggestion – Provides inline suggestions or function‑signature recommendations.
• telemetry – Emits usage statistics and performance metrics for monitoring and analytics.
• sessionStarted – Signals the successful initialization of a new Copilot session.
• sessionEnded – Indicates session termination, whether through explicit closure or timeout.
• toolCall – Represents a request from the model to execute a user‑defined tool or custom command.
• toolResult – Carries the return value from a previously invoked tool execution.
• error – Communicates failures within the streaming pipeline or model inference errors.
• message – Transmits generic informational updates, such as status notifications.
• responseChunk – Streams incremental data fragments for large responses, enabling progressive rendering.
• responseFinished – Marks the successful conclusion of a streamed response.
• responseCancelled – Notifies that the client or user aborted an ongoing response stream.

Implementing Event Listeners with SessionEventType

The Session class exposes an on() method defined in [nodejs/src/session.ts](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) that provides type-safe event subscription:

on<K extends SessionEventType>(eventType: K, handler: TypedSessionEventHandler<K>): () => void;

This generic signature guarantees that your handler receives the exact payload shape associated with the specified SessionEventType, eliminating runtime type mismatches.

Listening for Completion and Tool Events

To capture code completions and handle tool invocations, register handlers for the respective event types:

import { Copilot, SessionEventType } from "@github/copilot-sdk";

const client = new Copilot({ /* client options */ });
const session = await client.createSession();

// Handle code completions
session.on(SessionEventType.completion, (event) => {
  console.log("Completion received:", event.completion);
});

// Handle tool execution requests
session.on(SessionEventType.toolCall, async (event) => {
  console.log("Tool requested:", event.toolCall);
  await session.sendToolResult({
    requestId: event.toolCall.requestId,
    result: { /* tool output */ },
  });
});

Monitoring Session Lifecycle

Track session state changes using the lifecycle event types:

session.on(SessionEventType.sessionStarted, (event) => {
  console.log(`Session ${event.sessionId} initialized`);
});

session.on(SessionEventType.sessionEnded, (event) => {
  console.log(`Session ${event.sessionId} terminated`);
});

Processing Telemetry and Error Streams

Capture diagnostic information and error conditions:

session.on(SessionEventType.telemetry, (event) => {
  analyticsService.record(event.telemetry);
});

session.on(SessionEventType.error, (event) => {
  console.error("Streaming error:", event.error);
});

Summary

• The github/copilot-sdk defines twelve streaming event types in the SessionEventType enum, covering completions, tools, lifecycle, and errors.
• Type definitions reside in nodejs/src/types.ts, with code generation handled by scripts/codegen.
• The on() method in nodejs/src/session.ts provides type-safe event handling through TypedSessionEventHandler.
• Event types include completion, toolCall, sessionStarted, responseChunk, and error, among others.

Frequently Asked Questions

What is the difference between SessionEvent and SessionEventType in the Copilot SDK?

SessionEventType is a TypeScript enum that enumerates the string literals identifying each event category, while SessionEvent is a discriminated union type representing the actual event objects streamed from the service. The type property of every SessionEvent corresponds to a value from SessionEventType, enabling type-safe narrowing in event handlers.

How do I handle tool calls in the Copilot SDK streaming system?

Subscribe to the toolCall event type using session.on(SessionEventType.toolCall, handler). The handler receives a payload containing the tool name, arguments, and a unique requestId. After executing the requested operation, return results via session.sendToolResult() with the matching requestId to complete the round-trip.

Where are the event type definitions generated from in the Copilot SDK?

The TypeScript definitions are generated from a protocol schema located in scripts/codegen. The build process, particularly the Rust and TypeScript generators in scripts/codegen/rust.ts, creates the SessionEventType enum and SessionEvent union to ensure client-server type consistency.

Can I listen to multiple event types with a single handler?

While the on() method requires a specific SessionEventType per subscription, you can register the same handler function to multiple event types individually. Each registration returns a disposable function for cleanup; invoke these disposables to unsubscribe when the component unmounts or the session closes.

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