Handle unknown/malformed session events gracefully in Python SDK

[Copilot]

The Python SDK crashes with unhandled exceptions when receiving unknown or malformed session events from the Copilot server, producing noisy stderr output despite successful request completion.

Changes

• Python SDK (client.py): Wrapped session_event_from_dict() calls in try-except blocks within both notification handlers (stdio and TCP)

  • Silently ignores parsing failures for forward compatibility
  • Aligns behavior with Go and .NET SDKs which already handle this gracefully

• Tests: Added test_unknown_events.py verifying:

  • Unknown event types map to UNKNOWN enum value
  • Malformed data (invalid UUID/timestamp) raises exceptions caught by handler
  • Events are silently dropped without crashing

Context

The generated code already handles unknown event type strings by mapping them to SessionEventType.UNKNOWN, but malformed event data (e.g., invalid UUIDs) raises exceptions that were propagating uncaught through asyncio's event loop.

# Before: Crashes on malformed events
event = session_event_from_dict(event_dict)

# After: Silently ignores unparseable events
try:
    event = session_event_from_dict(event_dict)
except Exception:
    return

Node.js SDK validates notification structure before parsing; Go and .NET SDKs already return early on parse errors.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ValueError: 'session.usage_info' is not a valid SessionEventType</issue_title>
<issue_description>## Summary

The SDK throws a ValueError when the Copilot server sends session.usage_info events, because this event type is not defined in the SessionEventType enum. The error is printed to stderr as an unhandled exception in the asyncio event loop callback, which creates noisy output even though the request completes successfully.

Reproduction

import asyncio
from copilot import CopilotClient
from copilot.generated.session_events import SessionEventType

async def repro():
    client = CopilotClient()
    await client.start()
    
    try:
        session = await client.create_session({
            "model": "claude-sonnet-4.5",
            "streaming": False,
            "available_tools": [],
        })
        
        done = asyncio.Event()
        
        def handle_event(event):
            if event.type == SessionEventType.ASSISTANT_TURN_END:
                done.set()
        
        unsubscribe = session.on(handle_event)
        
        try:
            await session.send({"prompt": "Say hello"})
            await asyncio.wait_for(done.wait(), timeout=30)
        finally:
            unsubscribe()
            await session.destroy()
    finally:
        await client.stop()

# Run with GH_TOKEN set
asyncio.run(repro())

Output:

Exception in callback CopilotClient._connect_via_stdio.<locals>.handle_notification(...)
Traceback (most recent call last):
  ...
  File ".../copilot/generated/session_events.py", line 618, in from_dict
    type = SessionEventType(obj.get("type"))
ValueError: 'session.usage_info' is not a valid SessionEventType

Root Cause

In copilot/generated/session_events.py, the SessionEventType enum does not include session.usage_info:

class SessionEventType(Enum):
    ASSISTANT_MESSAGE = "session.assistant.message"
    ASSISTANT_MESSAGE_DELTA = "session.assistant.message.delta"
    ASSISTANT_TURN_END = "session.assistant.turn.end"
    # ... other types
    # Missing: SESSION_USAGE_INFO = "session.usage_info"

When SessionEvent.from_dict() tries to parse an event with type: "session.usage_info", it fails:

type = SessionEventType(obj.get("type"))  # ValueError!

Suggested Fix

Option 1: Add the missing event type to the enum:

class SessionEventType(Enum):
    # ... existing types ...
    SESSION_USAGE_INFO = "session.usage_info"

Option 2: Handle unknown event types gracefully in session_event_from_dict():

def session_event_from_dict(s: dict) -> Optional[SessionEvent]:
    try:
        return SessionEvent.from_dict(s)
    except ValueError:
        # Unknown event type - ignore gracefully
        return None

And update handle_notification() to handle None:

def handle_notification(method: str, params: dict):
    if method == "session.event":
        event = session_event_from_dict(event_dict)
        if event is not None:  # Skip unknown event types
            session._dispatch_event(event)

Environment

• OS: macOS 14.x
• Python: 3.11
• SDK version: Latest from pip

Impact

• Severity: Low (does not break functionality, but creates noisy stderr output)
• Workaround: Suppress the exception via custom asyncio exception handler
  </issue_description>

<agent_instructions>Let's make sure that we fail gracefully on unknown events across all client SDKs, not just the Python one</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Custom agent used: debug-agentic-workflow
Debug and refine agentic workflows using gh-aw CLI tools - analyze logs, audit runs, and improve workflow performance

• Fixes ValueError: 'session.usage_info' is not a valid SessionEventType #30

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.