# Copilot SDK Streaming Event Types: Complete Guide to SessionEvent Handling

> Explore Copilot SDK streaming event types including completion, toolCall, and sessionStarted. Learn how to handle SessionEvent types effectively with this comprehensive guide.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: tutorial
- Published: 2026-07-18

---

**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`](https://github.com/github/copilot-sdk/blob/main/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)](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)](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`](https://github.com/github/copilot-sdk/tree/main/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)](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts)** that provides type-safe event subscription:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/types.ts)**, with code generation handled by **`scripts/codegen`**.
- The **`on()`** method in **[`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/tree/main/scripts/codegen)**. The build process, particularly the Rust and TypeScript generators in [`scripts/codegen/rust.ts`](https://github.com/github/copilot-sdk/blob/main/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.