fix(dotnet): handle unknown session event types gracefully

Add UnknownSessionEvent type and TryFromJson method so that unrecognized event types from newer CLI versions do not crash GetMessagesAsync or real-time event dispatch.

Author: Ron537

dotnet/src/Client.cs

@@ -1303,11 +1303,8 @@ public void OnSessionEvent(string sessionId, JsonElement? @event)
             var session = client.GetSession(sessionId);
             if (session != null && @event != null)
             {
-                var evt = SessionEvent.FromJson(@event.Value.GetRawText());
-                if (evt != null)
-                {
-                    session.DispatchEvent(evt);
-                }
+                var evt = SessionEvent.TryFromJson(@event.Value.GetRawText(), client._logger);
+                session.DispatchEvent(evt);
             }
         }
 

dotnet/src/Session.cs

@@ -681,8 +681,7 @@ public async Task<IReadOnlyList<SessionEvent>> GetMessagesAsync(CancellationToke
             "session.getMessages", [new GetMessagesRequest { SessionId = SessionId }], cancellationToken);
 
         return response.Events
-            .Select(e => SessionEvent.FromJson(e.ToJsonString()))
-            .OfType<SessionEvent>()
+            .Select(e => SessionEvent.TryFromJson(e.ToJsonString(), _logger))
             .ToList();
     }
 

dotnet/src/SessionEventExtensions.cs

@@ -0,0 +1,59 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Microsoft.Extensions.Logging;
+
+namespace GitHub.Copilot.SDK;
+
+public abstract partial class SessionEvent
+{
+    /// <summary>
+    /// Attempts to deserialize a JSON string into a <see cref="SessionEvent"/>.
+    /// </summary>
+    /// <param name="json">The JSON string representing a session event.</param>
+    /// <param name="logger">Optional logger for recording deserialization warnings.</param>
+    /// <returns>
+    /// The deserialized <see cref="SessionEvent"/> on success, or an
+    /// <see cref="UnknownSessionEvent"/> when the event type is not recognized by this
+    /// version of the SDK.
+    /// </returns>
+    /// <remarks>
+    /// Unlike <see cref="FromJson"/>, this method never throws for unknown event types.
+    /// It catches <see cref="JsonException"/> and returns an <see cref="UnknownSessionEvent"/>
+    /// that preserves the raw JSON and type discriminator for diagnostic purposes.
+    /// </remarks>
+    public static SessionEvent TryFromJson(string json, ILogger? logger = null)
+    {
+        try
+        {
+            return FromJson(json);
+        }
+        catch (JsonException ex)
+        {
+            var rawType = ExtractTypeDiscriminator(json);
+            logger?.LogWarning(ex, "Skipping unrecognized session event type '{EventType}'", rawType);
+
+            return new UnknownSessionEvent
+            {
+                RawType = rawType,
+                RawJson = json,
+            };
+        }
+    }
+
+    private static string? ExtractTypeDiscriminator(string json)
+    {
+        try
+        {
+            var node = JsonNode.Parse(json);
+            return node?["type"]?.GetValue<string>();
+        }
+        catch
+        {
+            return null;
+        }
+    }
+}

dotnet/src/UnknownSessionEvent.cs

@@ -0,0 +1,43 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using System.Text.Json.Serialization;
+
+namespace GitHub.Copilot.SDK;
+
+/// <summary>
+/// Represents a session event whose <c>type</c> discriminator is not recognized by this
+/// version of the SDK.
+/// </summary>
+/// <remarks>
+/// <para>
+/// When the Copilot CLI emits an event type that the SDK has not yet been updated to
+/// support, deserialization via <see cref="SessionEvent.FromJson"/> would normally throw
+/// a <see cref="System.Text.Json.JsonException"/>. Instead,
+/// <see cref="SessionEvent.TryFromJson"/> catches the failure and returns an
+/// <see cref="UnknownSessionEvent"/> that preserves the raw JSON for diagnostic purposes.
+/// </para>
+/// <para>
+/// Consumers can pattern-match on this type to detect and log forward-compatibility gaps
+/// without losing the rest of the event stream.
+/// </para>
+/// </remarks>
+public sealed class UnknownSessionEvent : SessionEvent
+{
+    /// <inheritdoc />
+    [JsonIgnore]
+    public override string Type => RawType ?? "unknown";
+
+    /// <summary>
+    /// The original <c>type</c> discriminator value from the JSON payload, if it could be
+    /// extracted. <c>null</c> when the type field is missing or unreadable.
+    /// </summary>
+    public string? RawType { get; init; }
+
+    /// <summary>
+    /// The complete, unparsed JSON string of the event. Useful for logging, debugging,
+    /// or forwarding to systems that may understand the event.
+    /// </summary>
+    public string? RawJson { get; init; }
+}

dotnet/test/UnknownSessionEventTests.cs

@@ -0,0 +1,176 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using Xunit;
+
+namespace GitHub.Copilot.SDK.Test;
+
+/// <summary>
+/// Tests for forward-compatible handling of unknown session event types.
+/// Verifies that the SDK gracefully handles event types introduced by newer CLI versions.
+/// </summary>
+public class UnknownSessionEventTests
+{
+    [Fact]
+    public void FromJson_KnownEventType_DeserializesNormally()
+    {
+        var json = """
+        {
+            "id": "00000000-0000-0000-0000-000000000001",
+            "timestamp": "2026-01-01T00:00:00Z",
+            "parentId": null,
+            "type": "user.message",
+            "data": {
+                "content": "Hello"
+            }
+        }
+        """;
+
+        var result = SessionEvent.FromJson(json);
+
+        Assert.IsType<UserMessageEvent>(result);
+        Assert.Equal("user.message", result.Type);
+    }
+
+    [Fact]
+    public void FromJson_UnknownEventType_Throws()
+    {
+        var json = """
+        {
+            "id": "00000000-0000-0000-0000-000000000007",
+            "timestamp": "2026-01-01T00:00:00Z",
+            "parentId": null,
+            "type": "future.feature_from_server",
+            "data": {}
+        }
+        """;
+
+        Assert.Throws<System.Text.Json.JsonException>(() => SessionEvent.FromJson(json));
+    }
+
+    [Fact]
+    public void UnknownSessionEvent_Type_ReturnsRawType()
+    {
+        var evt = new UnknownSessionEvent
+        {
+            RawType = "future.feature",
+            RawJson = """{"type":"future.feature"}""",
+        };
+
+        Assert.Equal("future.feature", evt.Type);
+        Assert.Equal("future.feature", evt.RawType);
+        Assert.NotNull(evt.RawJson);
+    }
+
+    [Fact]
+    public void UnknownSessionEvent_Type_FallsBackToUnknown_WhenRawTypeIsNull()
+    {
+        var evt = new UnknownSessionEvent { RawType = null, RawJson = null };
+
+        Assert.Equal("unknown", evt.Type);
+    }
+
+    [Fact]
+    public void UnknownSessionEvent_PreservesRawJson()
+    {
+        var rawJson = """{"type":"new.event","data":{"nested":{"deep":true},"list":[1,2,3]}}""";
+        var evt = new UnknownSessionEvent
+        {
+            RawType = "new.event",
+            RawJson = rawJson,
+        };
+
+        Assert.Equal(rawJson, evt.RawJson);
+        Assert.Contains("nested", evt.RawJson);
+    }
+
+    [Fact]
+    public void UnknownSessionEvent_IsSessionEvent()
+    {
+        var evt = new UnknownSessionEvent { RawType = "future.event" };
+
+        Assert.IsAssignableFrom<SessionEvent>(evt);
+    }
+
+    [Fact]
+    public void TryFromJson_KnownEventType_DeserializesNormally()
+    {
+        var json = """
+        {
+            "id": "00000000-0000-0000-0000-000000000010",
+            "timestamp": "2026-01-01T00:00:00Z",
+            "parentId": null,
+            "type": "user.message",
+            "data": {
+                "content": "Hello"
+            }
+        }
+        """;
+
+        var result = SessionEvent.TryFromJson(json);
+
+        Assert.IsType<UserMessageEvent>(result);
+        Assert.Equal("user.message", result.Type);
+    }
+
+    [Fact]
+    public void TryFromJson_UnknownEventType_ReturnsUnknownSessionEvent()
+    {
+        var json = """
+        {
+            "id": "00000000-0000-0000-0000-000000000011",
+            "timestamp": "2026-01-01T00:00:00Z",
+            "parentId": null,
+            "type": "future.feature_from_server",
+            "data": { "key": "value" }
+        }
+        """;
+
+        var result = SessionEvent.TryFromJson(json);
+
+        var unknown = Assert.IsType<UnknownSessionEvent>(result);
+        Assert.Equal("future.feature_from_server", unknown.RawType);
+        Assert.Equal("future.feature_from_server", unknown.Type);
+        Assert.NotNull(unknown.RawJson);
+        Assert.Contains("future.feature_from_server", unknown.RawJson);
+    }
+
+    [Fact]
+    public void TryFromJson_UnknownEventType_PreservesRawJson()
+    {
+        var json = """
+        {
+            "id": "00000000-0000-0000-0000-000000000012",
+            "timestamp": "2026-01-01T00:00:00Z",
+            "parentId": null,
+            "type": "some.new.event",
+            "data": { "nested": { "deep": true }, "list": [1, 2, 3] }
+        }
+        """;
+
+        var result = SessionEvent.TryFromJson(json);
+
+        var unknown = Assert.IsType<UnknownSessionEvent>(result);
+        Assert.Contains("\"nested\"", unknown.RawJson);
+        Assert.Contains("\"deep\"", unknown.RawJson);
+    }
+
+    [Fact]
+    public void TryFromJson_MultipleEvents_MixedKnownAndUnknown()
+    {
+        var events = new[]
+        {
+            """{"id":"00000000-0000-0000-0000-000000000013","timestamp":"2026-01-01T00:00:00Z","parentId":null,"type":"user.message","data":{"content":"Hi"}}""",
+            """{"id":"00000000-0000-0000-0000-000000000014","timestamp":"2026-01-01T00:00:00Z","parentId":null,"type":"future.unknown_type","data":{}}""",
+            """{"id":"00000000-0000-0000-0000-000000000015","timestamp":"2026-01-01T00:00:00Z","parentId":null,"type":"user.message","data":{"content":"Bye"}}""",
+        };
+
+        var results = events.Select(e => SessionEvent.TryFromJson(e)).ToList();
+
+        Assert.Equal(3, results.Count);
+        Assert.IsType<UserMessageEvent>(results[0]);
+        Assert.IsType<UnknownSessionEvent>(results[1]);
+        Assert.IsType<UserMessageEvent>(results[2]);
+    }
+}