Phase 4f: generic OnLifecycle<T> + On<T>, polymorphic lifecycle events

- Add SessionCreatedEvent / SessionDeletedEvent / SessionUpdatedEvent /
  SessionForegroundEvent / SessionBackgroundEvent as sealed derived types
  of SessionLifecycleEvent. Unknown future event types deserialize to the
  base SessionLifecycleEvent for forward compatibility (consumers can still
  inspect Type).
- Remove the SessionLifecycleEventTypes static constants class (subsumed by
  the typed hierarchy).
- Replace CopilotClient.On / CopilotClient.On(string, ...) with a single
  generic OnLifecycle<T>(Action<T>) where T : SessionLifecycleEvent. Consumers
  pass a derived type to filter, or SessionLifecycleEvent to receive all.
- Replace CopilotSession.On(SessionEventHandler) with generic
  On<T>(Action<T>) where T : SessionEvent. Same filtering pattern.
- Remove the SessionEventHandler delegate; SessionConfig.OnEvent /
  ResumeSessionConfig.OnEvent are now Action<SessionEvent>?.
- Update samples, tests, and README.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: SteveSandersonMS

dotnet/README.md

@@ -43,7 +43,7 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
 // Wait for the response using the session.idle event
 var done = new TaskCompletionSource();
 
-session.On(evt =>
+session.On<SessionEvent>(evt =>
 {
     if (evt is AssistantMessageEvent msg)
     {
@@ -158,7 +158,7 @@ Request the TUI to switch to displaying the specified session. Only available in
 Subscribe to all session lifecycle events. Returns an `IDisposable` that unsubscribes when disposed.
 
 ```csharp
-using var subscription = client.On(evt =>
+using var subscription = client.OnLifecycle<SessionLifecycleEvent>(evt =>
 {
     Console.WriteLine($"Session {evt.SessionId}: {evt.Type}");
 });
@@ -169,7 +169,7 @@ using var subscription = client.On(evt =>
 Subscribe to a specific lifecycle event type. Use `SessionLifecycleEventTypes` constants.
 
 ```csharp
-using var subscription = client.On(SessionLifecycleEventTypes.Foreground, evt =>
+using var subscription = client.OnLifecycle<SessionForegroundEvent>(evt =>
 {
     Console.WriteLine($"Session {evt.SessionId} is now in foreground");
 });
@@ -208,12 +208,12 @@ Send a message to the session.
 
 Returns the message ID.
 
-##### `On(SessionEventHandler handler): IDisposable`
+##### `On(Action<SessionEvent> handler): IDisposable`
 
 Subscribe to session events. Returns a disposable to unsubscribe.
 
 ```csharp
-var subscription = session.On(evt =>
+var subscription = session.On<SessionEvent>(evt =>
 {
     Console.WriteLine($"Event: {evt.Type}");
 });
@@ -262,7 +262,7 @@ Sessions emit various events during processing. Each event type is a class that
 Use pattern matching to handle specific event types:
 
 ```csharp
-session.On(evt =>
+session.On<SessionEvent>(evt =>
 {
     switch (evt)
     {
@@ -330,7 +330,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
 // Use TaskCompletionSource to wait for completion
 var done = new TaskCompletionSource();
 
-session.On(evt =>
+session.On<SessionEvent>(evt =>
 {
     switch (evt)
     {

dotnet/samples/Chat.cs

@@ -8,7 +8,7 @@
     OnPermissionRequest = PermissionHandler.ApproveAll
 });
 
-using var _ = session.On(evt =>
+using var _ = session.On<SessionEvent>(evt =>
 {
     Console.ForegroundColor = ConsoleColor.Blue;
     switch (evt)

dotnet/samples/ManualToolResume.cs

@@ -80,7 +80,7 @@ static async Task<T> WaitForEventAsync<T>(CopilotSession session, Func<T, bool>?
 {
     var tcs = new TaskCompletionSource<T>(TaskCreationOptions.RunContinuationsAsynchronously);
     IDisposable? subscription = null;
-    subscription = session.On(evt =>
+    subscription = session.On<SessionEvent>(evt =>
     {
         if (evt is T typed && (predicate?.Invoke(typed) ?? true))
         {

dotnet/src/Client.cs

@@ -41,7 +41,7 @@ namespace GitHub.Copilot.SDK;
 /// await using var session = await client.CreateSessionAsync(new() { OnPermissionRequest = PermissionHandler.ApproveAll, Model = "gpt-4" });
 ///
 /// // Handle events
-/// using var subscription = session.On(evt =>
+/// using var subscription = session.On<SessionEvent>(evt =>
 /// {
 ///     if (evt is AssistantMessageEvent assistantMessage)
 ///         Console.WriteLine(assistantMessage.Data?.Content);
@@ -82,11 +82,12 @@ public sealed partial class CopilotClient : IDisposable, IAsyncDisposable
     private List<ModelInfo>? _modelsCache;
     private readonly SemaphoreSlim _modelsCacheLock = new(1, 1);
     private readonly Func<CancellationToken, Task<IList<ModelInfo>>>? _onListModels;
-    private readonly List<Action<SessionLifecycleEvent>> _lifecycleHandlers = [];
-    private readonly Dictionary<string, List<Action<SessionLifecycleEvent>>> _typedLifecycleHandlers = [];
+    private readonly List<LifecycleSubscription> _lifecycleHandlers = [];
     private readonly object _lifecycleHandlersLock = new();
     private ServerRpc? _serverRpc;
 
+    private sealed record LifecycleSubscription(Type EventType, Action<SessionLifecycleEvent> Handler);
+
     /// <summary>
     /// Gets the typed RPC client for server-scoped methods (no session required).
     /// </summary>
@@ -584,7 +585,7 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
         }
         if (config.OnEvent != null)
         {
-            session.On(config.OnEvent);
+            session.On<SessionEvent>(config.OnEvent);
         }
         ConfigureSessionFsHandlers(session, config.CreateSessionFsProvider);
         RegisterSession(session);
@@ -742,7 +743,7 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
         }
         if (config.OnEvent != null)
         {
-            session.On(config.OnEvent);
+            session.On<SessionEvent>(config.OnEvent);
         }
         ConfigureSessionFsHandlers(session, config.CreateSessionFsProvider);
         RegisterSession(session);
@@ -1102,103 +1103,59 @@ public async Task SetForegroundSessionIdAsync(string sessionId, CancellationToke
     }
 
     /// <summary>
-    /// Subscribes to all session lifecycle events.
-    /// </summary>
-    /// <remarks>
-    /// Lifecycle events are emitted when sessions are created, deleted, updated,
-    /// or change foreground/background state (in TUI+server mode).
-    /// </remarks>
-    /// <param name="handler">A callback function that receives lifecycle events.</param>
-    /// <returns>An IDisposable that, when disposed, unsubscribes the handler.</returns>
-    /// <example>
-    /// <code>
-    /// using var subscription = client.On(evt =>
-    /// {
-    ///     Console.WriteLine($"Session {evt.SessionId}: {evt.Type}");
-    /// });
-    /// </code>
-    /// </example>
-    public IDisposable On(Action<SessionLifecycleEvent> handler)
-    {
-        ArgumentNullException.ThrowIfNull(handler);
-
-        lock (_lifecycleHandlersLock)
-        {
-            _lifecycleHandlers.Add(handler);
-        }
-
-        return new ActionDisposable(() =>
-        {
-            lock (_lifecycleHandlersLock)
-            {
-                _lifecycleHandlers.Remove(handler);
-            }
-        });
-    }
-
-    /// <summary>
-    /// Subscribes to a specific session lifecycle event type.
+    /// Subscribes to session lifecycle events of a specific kind.
     /// </summary>
-    /// <param name="eventType">The event type to listen for (use SessionLifecycleEventTypes constants).</param>
-    /// <param name="handler">A callback function that receives events of the specified type.</param>
-    /// <returns>An IDisposable that, when disposed, unsubscribes the handler.</returns>
+    /// <typeparam name="T">
+    /// The lifecycle event type to listen for. Pass a derived type such as
+    /// <see cref="SessionCreatedEvent"/> to filter by kind, or
+    /// <see cref="SessionLifecycleEvent"/> to receive every lifecycle event.
+    /// </typeparam>
+    /// <param name="handler">A callback invoked when a matching lifecycle event arrives.</param>
+    /// <returns>An <see cref="IDisposable"/> that, when disposed, unsubscribes the handler.</returns>
     /// <example>
     /// <code>
-    /// using var subscription = client.On(SessionLifecycleEventTypes.Foreground, evt =>
+    /// using var sub = client.OnLifecycle&lt;SessionForegroundEvent&gt;(evt =&gt;
     /// {
     ///     Console.WriteLine($"Session {evt.SessionId} is now in foreground");
     /// });
     /// </code>
     /// </example>
-    public IDisposable On(string eventType, Action<SessionLifecycleEvent> handler)
+    public IDisposable OnLifecycle<T>(Action<T> handler) where T : SessionLifecycleEvent
     {
-        ArgumentNullException.ThrowIfNull(eventType);
         ArgumentNullException.ThrowIfNull(handler);
 
+        var subscription = new LifecycleSubscription(typeof(T), evt => handler((T)evt));
+
         lock (_lifecycleHandlersLock)
         {
-            if (!_typedLifecycleHandlers.TryGetValue(eventType, out var handlers))
-            {
-                handlers = [];
-                _typedLifecycleHandlers[eventType] = handlers;
-            }
-
-            handlers.Add(handler);
+            _lifecycleHandlers.Add(subscription);
         }
 
         return new ActionDisposable(() =>
         {
             lock (_lifecycleHandlersLock)
             {
-                if (_typedLifecycleHandlers.TryGetValue(eventType, out var handlers))
-                {
-                    handlers.Remove(handler);
-                }
+                _lifecycleHandlers.Remove(subscription);
             }
         });
     }
 
     private void DispatchLifecycleEvent(SessionLifecycleEvent evt)
     {
-        List<Action<SessionLifecycleEvent>> typedHandlers;
-        List<Action<SessionLifecycleEvent>> wildcardHandlers;
-
+        List<LifecycleSubscription> snapshot;
         lock (_lifecycleHandlersLock)
         {
-            typedHandlers = _typedLifecycleHandlers.TryGetValue(evt.Type, out var handlers)
-                ? [.. handlers]
-                : [];
-            wildcardHandlers = [.. _lifecycleHandlers];
+            snapshot = [.. _lifecycleHandlers];
         }
 
-        foreach (var handler in typedHandlers)
+        var eventType = evt.GetType();
+        foreach (var subscription in snapshot)
         {
-            try { handler(evt); } catch { /* Ignore handler errors */ }
-        }
-
-        foreach (var handler in wildcardHandlers)
-        {
-            try { handler(evt); } catch { /* Ignore handler errors */ }
+            if (!subscription.EventType.IsAssignableFrom(eventType))
+            {
+                continue;
+            }
+            try { subscription.Handler(evt); } catch { /* Ignore handler errors */ }
         }
     }
 
@@ -1766,13 +1723,19 @@ public void OnSessionEvent(string sessionId, JsonElement? @event)
 
         public void OnSessionLifecycle(string type, string sessionId, JsonElement? metadata)
         {
-            var evt = new SessionLifecycleEvent
+            SessionLifecycleEvent evt = type switch
             {
-                Type = type,
-                SessionId = sessionId
+                "session.created" => new SessionCreatedEvent(),
+                "session.deleted" => new SessionDeletedEvent(),
+                "session.updated" => new SessionUpdatedEvent(),
+                "session.foreground" => new SessionForegroundEvent(),
+                "session.background" => new SessionBackgroundEvent(),
+                _ => new SessionLifecycleEvent()
             };
 
-            if (metadata != null)
+            evt.Type = type;
+            evt.SessionId = sessionId;
+            if (metadata is not null)
             {
                 evt.Metadata = JsonSerializer.Deserialize(
                     metadata.Value.GetRawText(),

dotnet/src/Session.cs

@@ -41,7 +41,7 @@ namespace GitHub.Copilot.SDK;
 /// await using var session = await client.CreateSessionAsync(new() { OnPermissionRequest = PermissionHandler.ApproveAll, Model = "gpt-4" });
 ///
 /// // Subscribe to events
-/// using var subscription = session.On(evt =>
+/// using var subscription = session.On<SessionEvent>(evt =>
 /// {
 ///     if (evt is AssistantMessageEvent assistantMessage)
 ///     {
@@ -65,7 +65,9 @@ public sealed partial class CopilotSession : IAsyncDisposable
     private volatile ElicitationHandler? _elicitationHandler;
     private volatile ExitPlanModeHandler? _exitPlanModeHandler;
     private volatile AutoModeSwitchHandler? _autoModeSwitchHandler;
-    private ImmutableArray<SessionEventHandler> _eventHandlers = ImmutableArray<SessionEventHandler>.Empty;
+    private ImmutableArray<EventSubscription> _eventHandlers = ImmutableArray<EventSubscription>.Empty;
+
+    private sealed record EventSubscription(Type EventType, Action<SessionEvent> Handler);
 
     private SessionHooks? _hooks;
     private readonly SemaphoreSlim _hooksLock = new(1, 1);
@@ -318,7 +320,7 @@ void Handler(SessionEvent evt)
             }
         }
 
-        using var subscription = On(Handler);
+        using var subscription = On<SessionEvent>(Handler);
 
         await SendAsync(options, cancellationToken);
 
@@ -381,7 +383,7 @@ void Handler(SessionEvent evt)
     /// </remarks>
     /// <example>
     /// <code>
-    /// using var subscription = session.On(evt =>
+    /// using var subscription = session.On&lt;SessionEvent&gt;(evt =&gt;
     /// {
     ///     switch (evt)
     ///     {
@@ -394,16 +396,21 @@ void Handler(SessionEvent evt)
     ///     }
     /// });
     ///
+    /// // Or filter to a specific event kind at compile time:
+    /// using var sub2 = session.On&lt;AssistantMessageEvent&gt;(evt =&gt;
+    ///     Console.WriteLine(evt.Data?.Content));
+    ///
     /// // The handler is automatically unsubscribed when the subscription is disposed.
     /// </code>
     /// </example>
-    public IDisposable On(SessionEventHandler handler)
+    public IDisposable On<T>(Action<T> handler) where T : SessionEvent
     {
         ArgumentNullException.ThrowIfNull(handler);
         ThrowIfDisposed();
 
-        ImmutableInterlocked.Update(ref _eventHandlers, array => array.Add(handler));
-        return new ActionDisposable(() => ImmutableInterlocked.Update(ref _eventHandlers, array => array.Remove(handler)));
+        var subscription = new EventSubscription(typeof(T), evt => handler((T)evt));
+        ImmutableInterlocked.Update(ref _eventHandlers, array => array.Add(subscription));
+        return new ActionDisposable(() => ImmutableInterlocked.Update(ref _eventHandlers, array => array.Remove(subscription)));
     }
 
     /// <summary>
@@ -438,11 +445,16 @@ private async Task ProcessEventsAsync()
         await foreach (var sessionEvent in _eventChannel.Reader.ReadAllAsync())
         {
             var dispatchTimestamp = Stopwatch.GetTimestamp();
-            foreach (var handler in _eventHandlers)
+            var eventType = sessionEvent.GetType();
+            foreach (var subscription in _eventHandlers)
             {
+                if (!subscription.EventType.IsAssignableFrom(eventType))
+                {
+                    continue;
+                }
                 try
                 {
-                    handler(sessionEvent);
+                    subscription.Handler(sessionEvent);
                 }
                 catch (Exception ex)
                 {
@@ -1488,7 +1500,7 @@ await InvokeRpcAsync<object>(
             GC.SuppressFinalize(this);
         }
 
-        _eventHandlers = ImmutableInterlocked.InterlockedExchange(ref _eventHandlers, ImmutableArray<SessionEventHandler>.Empty);
+        _eventHandlers = ImmutableInterlocked.InterlockedExchange(ref _eventHandlers, ImmutableArray<EventSubscription>.Empty);
         _toolHandlers.Clear();
         _commandHandlers.Clear();