docs: streaming events tip describes a single Data class for Python and Go, but both use per-event data types

[examon]

What the docs say

docs/features/streaming-events.md is the field-level reference for session events, and says it is written so you know what data to expect "without reading the SDK source". Its Python/Go tip says:

(Python / Go) These SDKs use a single Data class/struct with all possible fields as optional/nullable. Only the fields listed in the tables below are populated for each event type—the rest will be None / nil.

What actually happens

Both bindings use a separate data type per event, so code written against that tip does not work.

Go. event.Data is the SessionEventData interface, which carries no data fields:

session.On(func(event copilot.SessionEvent) {
	fmt.Println(event.Data.ToolName)
})

./main.go:41:35: event.Data.ToolName undefined (type rpc.SessionEventData has no field or method ToolName)

toolName is listed in the doc's own tool.execution_start table, so this is a field the tip says should be readable for that event.

Python. event.data is a per-event dataclass, so a handler that checks a field belonging to a different event raises instead of seeing None:

def handle(event):
    # the tip says fields not populated for this event are None
    if event.data.delta_content is not None:
        print(event.data.delta_content)

session.on(handle)

AttributeError: 'ToolExecutionStartData' object has no attribute 'delta_content'

The class named Data does exist in the Python binding, but it is a shim for manually constructed payloads with no declared fields; event delivery never produces it, and unrecognized events fall back to RawSessionEventData.

Why it drifted

The tip was accurate when it was added. Go moved to per-event data structs in #1037 and Python did the same in #1063. The Go change updated this file's Go example and left the prose behind.

Docs validation extracts and compiles fenced code blocks only, so prose claims are never checked. That is how this file ended up with a Go example using event.Data.(*copilot.AssistantMessageDeltaData) about sixty lines above a tip saying that is unnecessary.

Expected

The tip should describe the per-event model, as the same file already does for .NET and TypeScript.

Environment

• github/copilot-sdk at f6fea8d2b7ac17384440d7e56ecfc2af6c27da10
• github.com/github/copilot-sdk/go with Go 1.24, github-copilot-sdk with Python 3.12

[github-actions]

Thanks for the detailed report! Here's a summary of the documentation gap:

Documentation Gap

File affected: docs/features/streaming-events.md

What's wrong: The Python/Go tip in that file states:

These SDKs use a single Data class/struct with all possible fields as optional/nullable. Only the fields listed in the tables below are populated for each event type—the rest will be None / nil.

This is no longer accurate for either SDK:

• Go — event.Data is the SessionEventData interface; accessing fields directly (e.g., event.Data.ToolName) fails at compile time. You must type-assert to the concrete per-event struct (e.g., event.Data.(*copilot.ToolExecutionStartData)), which is already demonstrated in a code example ~60 lines above the tip — contradicting the tip's claim.
• Python — event.data is a per-event dataclass (e.g., ToolExecutionStartData). Accessing a field that belongs to a different event type raises AttributeError, not returning None as the tip implies.

Root cause: The tip was accurate when written. Go switched to per-event data structs in #1037 and Python did the same in #1063. The code examples were updated but the prose tip was not.

What should be fixed

The tip for Python and Go should be updated to match what's already documented for .NET and TypeScript — describing the per-event data type model, explaining that you should check event.type (or use the typed callback overloads where available) and cast/access the appropriate per-event data class/struct. The contradicting code example (event.Data.(*copilot.AssistantMessageDeltaData)) already shows the correct pattern for Go.

Generated by Documentation Handler for #2159 · sonnet46 16.9 AIC · ⌖ 5.05 AIC · ⊞ 5.4K · ◷