Add session shutdown method across all SDKs

Add a new shutdown() method (ShutdownAsync in .NET, Shutdown in Go) that
sends the session.destroy RPC to the CLI without clearing event handlers.
This allows callers to observe the session.shutdown notification that the
CLI sends after responding to the destroy request.

The existing destroy() / DisposeAsync() method now calls shutdown()
internally before clearing handlers, preserving full backward
compatibility.

Updated E2E tests in all four SDKs to exercise the new method and assert
that the session.shutdown event is received. Updated API reference docs
in all language READMEs, docs/compatibility.md, and the docs-maintenance
agent.

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

Author: stephentoub

.github/agents/docs-maintenance.agent.md

@@ -344,7 +344,7 @@ cat nodejs/src/types.ts | grep -A 10 "export interface ExportSessionOptions"
 **Must match:**
 - `CopilotClient` constructor options: `cliPath`, `cliUrl`, `useStdio`, `port`, `logLevel`, `autoStart`, `autoRestart`, `env`, `githubToken`, `useLoggedInUser`
 - `createSession()` config: `model`, `tools`, `hooks`, `systemMessage`, `mcpServers`, `availableTools`, `excludedTools`, `streaming`, `reasoningEffort`, `provider`, `infiniteSessions`, `customAgents`, `workingDirectory`
-- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `destroy()`, `abort()`, `on()`, `once()`, `off()`
+- `CopilotSession` methods: `send()`, `sendAndWait()`, `getMessages()`, `shutdown()`, `destroy()`, `abort()`, `on()`, `once()`, `off()`
 - Hook names: `onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`, `onErrorOccurred`
 
 #### Python Validation
@@ -362,7 +362,7 @@ cat python/copilot/types.py | grep -A 15 "class SessionHooks"
 **Must match (snake_case):**
 - `CopilotClient` options: `cli_path`, `cli_url`, `use_stdio`, `port`, `log_level`, `auto_start`, `auto_restart`, `env`, `github_token`, `use_logged_in_user`
 - `create_session()` config keys: `model`, `tools`, `hooks`, `system_message`, `mcp_servers`, `available_tools`, `excluded_tools`, `streaming`, `reasoning_effort`, `provider`, `infinite_sessions`, `custom_agents`, `working_directory`
-- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `destroy()`, `abort()`, `export_session()`
+- `CopilotSession` methods: `send()`, `send_and_wait()`, `get_messages()`, `shutdown()`, `destroy()`, `abort()`, `export_session()`
 - Hook names: `on_pre_tool_use`, `on_post_tool_use`, `on_user_prompt_submitted`, `on_session_start`, `on_session_end`, `on_error_occurred`
 
 #### Go Validation
@@ -380,7 +380,7 @@ cat go/types.go | grep -A 15 "type SessionHooks struct"
 **Must match (PascalCase for exported):**
 - `ClientOptions` fields: `CLIPath`, `CLIUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Env`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` fields: `Model`, `Tools`, `Hooks`, `SystemMessage`, `MCPServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
-- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Destroy()`, `Abort()`, `ExportSession()`
+- `Session` methods: `Send()`, `SendAndWait()`, `GetMessages()`, `Shutdown()`, `Destroy()`, `Abort()`, `ExportSession()`
 - Hook fields: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### .NET Validation
@@ -398,7 +398,7 @@ cat dotnet/src/Types.cs | grep -A 15 "public class SessionHooks"
 **Must match (PascalCase):**
 - `CopilotClientOptions` properties: `CliPath`, `CliUrl`, `UseStdio`, `Port`, `LogLevel`, `AutoStart`, `AutoRestart`, `Environment`, `GithubToken`, `UseLoggedInUser`
 - `SessionConfig` properties: `Model`, `Tools`, `Hooks`, `SystemMessage`, `McpServers`, `AvailableTools`, `ExcludedTools`, `Streaming`, `ReasoningEffort`, `Provider`, `InfiniteSessions`, `CustomAgents`, `WorkingDirectory`
-- `CopilotSession` methods: `SendAsync()`, `SendAndWaitAsync()`, `GetMessagesAsync()`, `DisposeAsync()`, `AbortAsync()`, `ExportSessionAsync()`
+- `CopilotSession` methods: `SendAsync()`, `SendAndWaitAsync()`, `GetMessagesAsync()`, `ShutdownAsync()`, `DisposeAsync()`, `AbortAsync()`, `ExportSessionAsync()`
 - Hook properties: `OnPreToolUse`, `OnPostToolUse`, `OnUserPromptSubmitted`, `OnSessionStart`, `OnSessionEnd`, `OnErrorOccurred`
 
 #### Common Sample Errors to Check

docs/compatibility.md

@@ -16,6 +16,7 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
 | Create session | `createSession()` | Full config support |
 | Resume session | `resumeSession()` | With infinite session workspaces |
 | Destroy session | `destroy()` | Clean up resources |
+| Shutdown session | `shutdown()` | End session server-side, keeping handlers active |
 | Delete session | `deleteSession()` | Remove from storage |
 | List sessions | `listSessions()` | All stored sessions |
 | Get last session | `getLastSessionId()` | For quick resume |

dotnet/README.md

@@ -219,7 +219,11 @@ Get all events/messages from this session.
 
 ##### `DisposeAsync(): ValueTask`
 
-Dispose the session and free resources.
+Dispose the session and free resources. Calls `ShutdownAsync()` first if not already called.
+
+##### `ShutdownAsync(CancellationToken): Task`
+
+Shut down the session on the server without clearing local event handlers. Call this before `DisposeAsync()` when you want to observe the `SessionShutdownEvent`.
 
 ---
 

dotnet/src/Session.cs

@@ -59,6 +59,7 @@ public partial class CopilotSession : IAsyncDisposable
     private readonly SemaphoreSlim _hooksLock = new(1, 1);
     private SessionRpc? _sessionRpc;
     private int _isDisposed;
+    private int _isShutdown;
 
     /// <summary>
     /// Gets the unique identifier for this session.
@@ -523,6 +524,42 @@ public async Task SetModelAsync(string model, CancellationToken cancellationToke
         await Rpc.Model.SwitchToAsync(model, cancellationToken);
     }
 
+    /// <summary>
+    /// Shuts down this session on the server without clearing local event handlers.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Call this before <see cref="DisposeAsync"/> when you want to observe the
+    /// <see cref="SessionShutdownEvent"/>. The event is dispatched to registered handlers
+    /// after this method returns. Once you have processed the event, call
+    /// <see cref="DisposeAsync"/> to clear handlers and release local resources.
+    /// </para>
+    /// <para>
+    /// If the session has already been shut down, this is a no-op.
+    /// </para>
+    /// </remarks>
+    /// <param name="cancellationToken">A cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous shutdown operation.</returns>
+    /// <example>
+    /// <code>
+    /// var shutdownTcs = new TaskCompletionSource();
+    /// session.On(evt => { if (evt is SessionShutdownEvent) shutdownTcs.TrySetResult(); });
+    /// await session.ShutdownAsync();
+    /// await shutdownTcs.Task;
+    /// await session.DisposeAsync();
+    /// </code>
+    /// </example>
+    public async Task ShutdownAsync(CancellationToken cancellationToken = default)
+    {
+        if (Interlocked.Exchange(ref _isShutdown, 1) == 1)
+        {
+            return;
+        }
+
+        await InvokeRpcAsync<object>(
+            "session.destroy", [new SessionDestroyRequest() { SessionId = SessionId }], cancellationToken);
+    }
+
     /// <summary>
     /// Disposes the <see cref="CopilotSession"/> and releases all associated resources.
     /// </summary>
@@ -533,6 +570,11 @@ public async Task SetModelAsync(string model, CancellationToken cancellationToke
     /// and tool handlers are cleared.
     /// </para>
     /// <para>
+    /// If <see cref="ShutdownAsync"/> was not called first, this method calls it automatically.
+    /// In that case the <see cref="SessionShutdownEvent"/> may not be observed because handlers
+    /// are cleared immediately after the server responds.
+    /// </para>
+    /// <para>
     /// To continue the conversation, use <see cref="CopilotClient.ResumeSessionAsync"/>
     /// with the session ID.
     /// </para>
@@ -557,8 +599,7 @@ public async ValueTask DisposeAsync()
 
         try
         {
-            await InvokeRpcAsync<object>(
-                "session.destroy", [new SessionDestroyRequest() { SessionId = SessionId }], CancellationToken.None);
+            await ShutdownAsync();
         }
         catch (ObjectDisposedException)
         {

dotnet/test/SessionTests.cs

@@ -247,6 +247,7 @@ public async Task Should_Receive_Session_Events()
         var session = await CreateSessionAsync();
         var receivedEvents = new List<SessionEvent>();
         var idleReceived = new TaskCompletionSource<bool>();
+        var shutdownReceived = new TaskCompletionSource<bool>();
 
         session.On(evt =>
         {
@@ -255,6 +256,10 @@ public async Task Should_Receive_Session_Events()
             {
                 idleReceived.TrySetResult(true);
             }
+            else if (evt is SessionShutdownEvent)
+            {
+                shutdownReceived.TrySetResult(true);
+            }
         });
 
         // Send a message to trigger events
@@ -275,6 +280,10 @@ public async Task Should_Receive_Session_Events()
         Assert.NotNull(assistantMessage);
         Assert.Contains("300", assistantMessage!.Data.Content);
 
+        // Shut down session and verify shutdown event is received
+        await session.ShutdownAsync();
+        await shutdownReceived.Task.WaitAsync(TimeSpan.FromSeconds(5));
+        Assert.Contains(receivedEvents, evt => evt is SessionShutdownEvent);
         await session.DisposeAsync();
     }
 

go/README.md

@@ -170,6 +170,7 @@ Event types: `SessionLifecycleCreated`, `SessionLifecycleDeleted`, `SessionLifec
 - `Abort(ctx context.Context) error` - Abort the currently processing message
 - `GetMessages(ctx context.Context) ([]SessionEvent, error)` - Get message history
 - `Destroy() error` - Destroy the session
+- `Shutdown() error` - Shut down the session on the server without clearing local handlers (call before `Destroy()` to observe the `session.shutdown` event)
 
 ### Helper Functions
 

go/internal/e2e/session_test.go

@@ -593,6 +593,7 @@ func TestSession(t *testing.T) {
 
 		var receivedEvents []copilot.SessionEvent
 		idle := make(chan bool)
+		shutdown := make(chan bool)
 
 		session.On(func(event copilot.SessionEvent) {
 			receivedEvents = append(receivedEvents, event)
@@ -601,6 +602,11 @@ func TestSession(t *testing.T) {
 				case idle <- true:
 				default:
 				}
+			} else if event.Type == "session.shutdown" {
+				select {
+				case shutdown <- true:
+				default:
+				}
 			}
 		})
 
@@ -654,6 +660,28 @@ func TestSession(t *testing.T) {
 		if assistantMessage.Data.Content == nil || !strings.Contains(*assistantMessage.Data.Content, "300") {
 			t.Errorf("Expected assistant message to contain '300', got %v", assistantMessage.Data.Content)
 		}
+
+		// Shut down session and verify shutdown event is received
+		if err := session.Shutdown(); err != nil {
+			t.Fatalf("Failed to shut down session: %v", err)
+		}
+		select {
+		case <-shutdown:
+		case <-time.After(5 * time.Second):
+			t.Fatal("Timed out waiting for session.shutdown")
+		}
+		hasShutdown := false
+		for _, evt := range receivedEvents {
+			if evt.Type == "session.shutdown" {
+				hasShutdown = true
+			}
+		}
+		if !hasShutdown {
+			t.Error("Expected to receive session.shutdown event")
+		}
+		if err := session.Destroy(); err != nil {
+			t.Fatalf("Failed to destroy session: %v", err)
+		}
 	})
 
 	t.Run("should create session with custom config dir", func(t *testing.T) {

go/session.go

@@ -6,6 +6,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/github/copilot-sdk/go/internal/jsonrpc2"
@@ -64,6 +65,7 @@ type Session struct {
 	userInputMux      sync.RWMutex
 	hooks             *SessionHooks
 	hooksMux          sync.RWMutex
+	isShutdown        atomic.Bool
 
 	// RPC provides typed session-scoped RPC methods.
 	RPC *rpc.SessionRpc
@@ -511,12 +513,50 @@ func (s *Session) GetMessages(ctx context.Context) ([]SessionEvent, error) {
 	return response.Events, nil
 }
 
+// Shutdown ends this session on the server without clearing local event handlers.
+//
+// Call this before [Session.Destroy] when you want to observe the session.shutdown
+// event. The event is dispatched to registered handlers after this method returns.
+// Once you have processed the event, call [Session.Destroy] to clear handlers and
+// release local resources.
+//
+// If the session has already been shut down, this is a no-op.
+//
+// Returns an error if the connection fails.
+//
+// Example:
+//
+//	session.On(func(event copilot.SessionEvent) {
+//	    if event.Type == copilot.SessionShutdown {
+//	        fmt.Println("Shutdown metrics:", event.Data)
+//	    }
+//	})
+//	if err := session.Shutdown(); err != nil {
+//	    log.Printf("Failed to shut down session: %v", err)
+//	}
+//	// ... wait for the shutdown event ...
+//	session.Destroy()
+func (s *Session) Shutdown() error {
+	if s.isShutdown.Swap(true) {
+		return nil
+	}
+	_, err := s.client.Request("session.destroy", sessionDestroyRequest{SessionID: s.SessionID})
+	if err != nil {
+		return fmt.Errorf("failed to shut down session: %w", err)
+	}
+	return nil
+}
+
 // Destroy destroys this session and releases all associated resources.
 //
 // After calling this method, the session can no longer be used. All event
 // handlers and tool handlers are cleared. To continue the conversation,
 // use [Client.ResumeSession] with the session ID.
 //
+// If [Session.Shutdown] was not called first, this method calls it automatically.
+// In that case the session.shutdown event may not be observed because handlers
+// are cleared immediately after the server responds.
+//
 // Returns an error if the connection fails.
 //
 // Example:
@@ -526,9 +566,8 @@ func (s *Session) GetMessages(ctx context.Context) ([]SessionEvent, error) {
 //	    log.Printf("Failed to destroy session: %v", err)
 //	}
 func (s *Session) Destroy() error {
-	_, err := s.client.Request("session.destroy", sessionDestroyRequest{SessionID: s.SessionID})
-	if err != nil {
-		return fmt.Errorf("failed to destroy session: %w", err)
+	if err := s.Shutdown(); err != nil {
+		return err
 	}
 
 	// Clear handlers

nodejs/README.md

@@ -267,7 +267,11 @@ Get all events/messages from this session.
 
 ##### `destroy(): Promise<void>`
 
-Destroy the session and free resources.
+Destroy the session and free resources. Calls `shutdown()` first if not already called.
+
+##### `shutdown(): Promise<void>`
+
+Shut down the session on the server without clearing local event handlers. Call this before `destroy()` when you want to observe the `session.shutdown` event.
 
 ---
 

nodejs/src/session.ts

@@ -79,6 +79,8 @@ export class CopilotSession {
         private readonly _workspacePath?: string
     ) {}
 
+    private _isShutdown = false;
+
     /**
      * Typed session-scoped RPC methods.
      */
@@ -498,13 +500,50 @@ export class CopilotSession {
         return (response as { events: SessionEvent[] }).events;
     }
 
+    /**
+     * Shuts down this session on the server without clearing local event handlers.
+     *
+     * Call this before {@link destroy} when you want to observe the `session.shutdown`
+     * event. The event is dispatched to registered handlers after this method returns.
+     * Once you have processed the event, call {@link destroy} to clear handlers and
+     * release local resources.
+     *
+     * If the session has already been shut down, this is a no-op.
+     *
+     * @returns A promise that resolves when the server has acknowledged the shutdown
+     * @throws Error if the connection fails
+     *
+     * @example
+     * ```typescript
+     * session.on("session.shutdown", (event) => {
+     *   console.log("Shutdown metrics:", event.data.modelMetrics);
+     * });
+     * await session.shutdown();
+     * // ... wait for the shutdown event ...
+     * await session.destroy();
+     * ```
+     */
+    async shutdown(): Promise<void> {
+        if (this._isShutdown) {
+            return;
+        }
+        this._isShutdown = true;
+        await this.connection.sendRequest("session.destroy", {
+            sessionId: this.sessionId,
+        });
+    }
+
     /**
      * Destroys this session and releases all associated resources.
      *
      * After calling this method, the session can no longer be used. All event
      * handlers and tool handlers are cleared. To continue the conversation,
      * use {@link CopilotClient.resumeSession} with the session ID.
      *
+     * If {@link shutdown} was not called first, this method calls it automatically.
+     * In that case the `session.shutdown` event may not be observed because handlers
+     * are cleared immediately after the server responds.
+     *
      * @returns A promise that resolves when the session is destroyed
      * @throws Error if the connection fails
      *
@@ -515,9 +554,7 @@ export class CopilotSession {
      * ```
      */
     async destroy(): Promise<void> {
-        await this.connection.sendRequest("session.destroy", {
-            sessionId: this.sessionId,
-        });
+        await this.shutdown();
         this.eventHandlers.clear();
         this.typedEventHandlers.clear();
         this.toolHandlers.clear();