Register sessions before RPC and add SessionConfig.OnEvent (#664)

Register sessions in the client's sessions map before issuing the
session.create and session.resume RPC calls, so that events emitted
by the CLI during the RPC (e.g. session.start, permission requests,
tool calls) are not dropped. Previously, sessions were registered
only after the RPC completed, creating a window where notifications
for the session had no target.

The session ID is now generated client-side (via UUID) rather than
extracted from the server response. On RPC failure, the session is
cleaned up from the map.

Add a new OnEvent property to each SDK's session configuration
(SessionConfig / ResumeSessionConfig) that registers an event handler
on the session before the create/resume RPC is issued. This guarantees
that early events emitted by the CLI during session creation (e.g.
session.start) are delivered to the handler, unlike calling On() after
createSession() returns.

Changes across all four SDKs (Node.js, Python, Go, .NET):
- Generate sessionId client-side before the RPC
- Create and register the session in the sessions map before the RPC
- Set workspacePath from the RPC response after it completes
- Remove the session from the map if the RPC fails
- Add OnEvent/on_event config property wired up before the RPC

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

Author: stephentoub

dotnet/src/Client.cs

@@ -403,34 +403,11 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
             config.Hooks.OnSessionEnd != null ||
             config.Hooks.OnErrorOccurred != null);
 
-        var request = new CreateSessionRequest(
-            config.Model,
-            config.SessionId,
-            config.ClientName,
-            config.ReasoningEffort,
-            config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
-            config.SystemMessage,
-            config.AvailableTools,
-            config.ExcludedTools,
-            config.Provider,
-            (bool?)true,
-            config.OnUserInputRequest != null ? true : null,
-            hasHooks ? true : null,
-            config.WorkingDirectory,
-            config.Streaming is true ? true : null,
-            config.McpServers,
-            "direct",
-            config.CustomAgents,
-            config.Agent,
-            config.ConfigDir,
-            config.SkillDirectories,
-            config.DisabledSkills,
-            config.InfiniteSessions);
-
-        var response = await InvokeRpcAsync<CreateSessionResponse>(
-            connection.Rpc, "session.create", [request], cancellationToken);
-
-        var session = new CopilotSession(response.SessionId, connection.Rpc, response.WorkspacePath);
+        var sessionId = config.SessionId ?? Guid.NewGuid().ToString();
+
+        // Create and register the session before issuing the RPC so that
+        // events emitted by the CLI (e.g. session.start) are not dropped.
+        var session = new CopilotSession(sessionId, connection.Rpc);
         session.RegisterTools(config.Tools ?? []);
         session.RegisterPermissionHandler(config.OnPermissionRequest);
         if (config.OnUserInputRequest != null)
@@ -441,10 +418,47 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
         {
             session.RegisterHooks(config.Hooks);
         }
+        if (config.OnEvent != null)
+        {
+            session.On(config.OnEvent);
+        }
+        _sessions[sessionId] = session;
 
-        if (!_sessions.TryAdd(response.SessionId, session))
+        try
         {
-            throw new InvalidOperationException($"Session {response.SessionId} already exists");
+            var request = new CreateSessionRequest(
+                config.Model,
+                sessionId,
+                config.ClientName,
+                config.ReasoningEffort,
+                config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+                config.SystemMessage,
+                config.AvailableTools,
+                config.ExcludedTools,
+                config.Provider,
+                (bool?)true,
+                config.OnUserInputRequest != null ? true : null,
+                hasHooks ? true : null,
+                config.WorkingDirectory,
+                config.Streaming is true ? true : null,
+                config.McpServers,
+                "direct",
+                config.CustomAgents,
+                config.Agent,
+                config.ConfigDir,
+                config.SkillDirectories,
+                config.DisabledSkills,
+                config.InfiniteSessions);
+
+            var response = await InvokeRpcAsync<CreateSessionResponse>(
+                connection.Rpc, "session.create", [request], cancellationToken);
+
+            session.WorkspacePath = response.WorkspacePath;
+        }
+        catch
+        {
+            _sessions.TryRemove(sessionId, out _);
+            throw;
         }
 
         return session;
@@ -495,35 +509,9 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
             config.Hooks.OnSessionEnd != null ||
             config.Hooks.OnErrorOccurred != null);
 
-        var request = new ResumeSessionRequest(
-            sessionId,
-            config.ClientName,
-            config.Model,
-            config.ReasoningEffort,
-            config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
-            config.SystemMessage,
-            config.AvailableTools,
-            config.ExcludedTools,
-            config.Provider,
-            (bool?)true,
-            config.OnUserInputRequest != null ? true : null,
-            hasHooks ? true : null,
-            config.WorkingDirectory,
-            config.ConfigDir,
-            config.DisableResume is true ? true : null,
-            config.Streaming is true ? true : null,
-            config.McpServers,
-            "direct",
-            config.CustomAgents,
-            config.Agent,
-            config.SkillDirectories,
-            config.DisabledSkills,
-            config.InfiniteSessions);
-
-        var response = await InvokeRpcAsync<ResumeSessionResponse>(
-            connection.Rpc, "session.resume", [request], cancellationToken);
-
-        var session = new CopilotSession(response.SessionId, connection.Rpc, response.WorkspacePath);
+        // Create and register the session before issuing the RPC so that
+        // events emitted by the CLI (e.g. session.start) are not dropped.
+        var session = new CopilotSession(sessionId, connection.Rpc);
         session.RegisterTools(config.Tools ?? []);
         session.RegisterPermissionHandler(config.OnPermissionRequest);
         if (config.OnUserInputRequest != null)
@@ -534,9 +522,50 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
         {
             session.RegisterHooks(config.Hooks);
         }
+        if (config.OnEvent != null)
+        {
+            session.On(config.OnEvent);
+        }
+        _sessions[sessionId] = session;
+
+        try
+        {
+            var request = new ResumeSessionRequest(
+                sessionId,
+                config.ClientName,
+                config.Model,
+                config.ReasoningEffort,
+                config.Tools?.Select(ToolDefinition.FromAIFunction).ToList(),
+                config.SystemMessage,
+                config.AvailableTools,
+                config.ExcludedTools,
+                config.Provider,
+                (bool?)true,
+                config.OnUserInputRequest != null ? true : null,
+                hasHooks ? true : null,
+                config.WorkingDirectory,
+                config.ConfigDir,
+                config.DisableResume is true ? true : null,
+                config.Streaming is true ? true : null,
+                config.McpServers,
+                "direct",
+                config.CustomAgents,
+                config.Agent,
+                config.SkillDirectories,
+                config.DisabledSkills,
+                config.InfiniteSessions);
+
+            var response = await InvokeRpcAsync<ResumeSessionResponse>(
+                connection.Rpc, "session.resume", [request], cancellationToken);
+
+            session.WorkspacePath = response.WorkspacePath;
+        }
+        catch
+        {
+            _sessions.TryRemove(sessionId, out _);
+            throw;
+        }
 
-        // Replace any existing session entry to ensure new config (like permission handler) is used
-        _sessions[response.SessionId] = session;
         return session;
     }
 

dotnet/src/Session.cs

@@ -86,7 +86,7 @@ public sealed partial class CopilotSession : IAsyncDisposable
     /// The path to the workspace containing checkpoints/, plan.md, and files/ subdirectories,
     /// or null if infinite sessions are disabled.
     /// </value>
-    public string? WorkspacePath { get; }
+    public string? WorkspacePath { get; internal set; }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="CopilotSession"/> class.

dotnet/src/Types.cs

@@ -1183,6 +1183,7 @@ protected SessionConfig(SessionConfig? other)
             ? new Dictionary<string, object>(other.McpServers, other.McpServers.Comparer)
             : null;
         Model = other.Model;
+        OnEvent = other.OnEvent;
         OnPermissionRequest = other.OnPermissionRequest;
         OnUserInputRequest = other.OnUserInputRequest;
         Provider = other.Provider;
@@ -1307,6 +1308,18 @@ protected SessionConfig(SessionConfig? other)
     /// </summary>
     public InfiniteSessionConfig? InfiniteSessions { get; set; }
 
+    /// <summary>
+    /// Optional event handler that is registered on the session before the
+    /// session.create RPC is issued.
+    /// </summary>
+    /// <remarks>
+    /// Equivalent to calling <see cref="CopilotSession.On"/> immediately
+    /// after creation, but executes earlier in the lifecycle so no events are missed.
+    /// Using this property rather than <see cref="CopilotSession.On"/> guarantees that early events emitted 
+    /// by the CLI during session creation (e.g. session.start) are delivered to the handler.
+    /// </remarks>
+    public SessionEventHandler? OnEvent { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of this <see cref="SessionConfig"/> instance.
     /// </summary>
@@ -1355,6 +1368,7 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
             ? new Dictionary<string, object>(other.McpServers, other.McpServers.Comparer)
             : null;
         Model = other.Model;
+        OnEvent = other.OnEvent;
         OnPermissionRequest = other.OnPermissionRequest;
         OnUserInputRequest = other.OnUserInputRequest;
         Provider = other.Provider;
@@ -1482,6 +1496,12 @@ protected ResumeSessionConfig(ResumeSessionConfig? other)
     /// </summary>
     public InfiniteSessionConfig? InfiniteSessions { get; set; }
 
+    /// <summary>
+    /// Optional event handler registered before the session.resume RPC is issued,
+    /// ensuring early events are delivered. See <see cref="SessionConfig.OnEvent"/>.
+    /// </summary>
+    public SessionEventHandler? OnEvent { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of this <see cref="ResumeSessionConfig"/> instance.
     /// </summary>

dotnet/test/SessionTests.cs

@@ -245,7 +245,17 @@ await session.SendAsync(new MessageOptions
     [Fact]
     public async Task Should_Receive_Session_Events()
     {
-        var session = await CreateSessionAsync();
+        // Use OnEvent to capture events dispatched during session creation.
+        // session.start is emitted during the session.create RPC; if the session
+        // weren't registered in the sessions map before the RPC, it would be dropped.
+        var earlyEvents = new List<SessionEvent>();
+        var session = await CreateSessionAsync(new SessionConfig
+        {
+            OnEvent = evt => earlyEvents.Add(evt),
+        });
+
+        Assert.Contains(earlyEvents, evt => evt is SessionStartEvent);
+
         var receivedEvents = new List<SessionEvent>();
         var idleReceived = new TaskCompletionSource<bool>();
 

go/client.go

@@ -44,6 +44,8 @@ import (
 	"sync/atomic"
 	"time"
 
+	"github.com/google/uuid"
+
 	"github.com/github/copilot-sdk/go/internal/embeddedcli"
 	"github.com/github/copilot-sdk/go/internal/jsonrpc2"
 	"github.com/github/copilot-sdk/go/rpc"
@@ -493,7 +495,6 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 
 	req := createSessionRequest{}
 	req.Model = config.Model
-	req.SessionID = config.SessionID
 	req.ClientName = config.ClientName
 	req.ReasoningEffort = config.ReasoningEffort
 	req.ConfigDir = config.ConfigDir
@@ -527,17 +528,15 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	}
 	req.RequestPermission = Bool(true)
 
-	result, err := c.client.Request("session.create", req)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create session: %w", err)
-	}
-
-	var response createSessionResponse
-	if err := json.Unmarshal(result, &response); err != nil {
-		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	sessionID := config.SessionID
+	if sessionID == "" {
+		sessionID = uuid.New().String()
 	}
+	req.SessionID = sessionID
 
-	session := newSession(response.SessionID, c.client, response.WorkspacePath)
+	// Create and register the session before issuing the RPC so that
+	// events emitted by the CLI (e.g. session.start) are not dropped.
+	session := newSession(sessionID, c.client, "")
 
 	session.registerTools(config.Tools)
 	session.registerPermissionHandler(config.OnPermissionRequest)
@@ -547,11 +546,32 @@ func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Ses
 	if config.Hooks != nil {
 		session.registerHooks(config.Hooks)
 	}
+	if config.OnEvent != nil {
+		session.On(config.OnEvent)
+	}
 
 	c.sessionsMux.Lock()
-	c.sessions[response.SessionID] = session
+	c.sessions[sessionID] = session
 	c.sessionsMux.Unlock()
 
+	result, err := c.client.Request("session.create", req)
+	if err != nil {
+		c.sessionsMux.Lock()
+		delete(c.sessions, sessionID)
+		c.sessionsMux.Unlock()
+		return nil, fmt.Errorf("failed to create session: %w", err)
+	}
+
+	var response createSessionResponse
+	if err := json.Unmarshal(result, &response); err != nil {
+		c.sessionsMux.Lock()
+		delete(c.sessions, sessionID)
+		c.sessionsMux.Unlock()
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	session.workspacePath = response.WorkspacePath
+
 	return session, nil
 }
 
@@ -627,17 +647,10 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	req.InfiniteSessions = config.InfiniteSessions
 	req.RequestPermission = Bool(true)
 
-	result, err := c.client.Request("session.resume", req)
-	if err != nil {
-		return nil, fmt.Errorf("failed to resume session: %w", err)
-	}
+	// Create and register the session before issuing the RPC so that
+	// events emitted by the CLI (e.g. session.start) are not dropped.
+	session := newSession(sessionID, c.client, "")
 
-	var response resumeSessionResponse
-	if err := json.Unmarshal(result, &response); err != nil {
-		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
-	}
-
-	session := newSession(response.SessionID, c.client, response.WorkspacePath)
 	session.registerTools(config.Tools)
 	session.registerPermissionHandler(config.OnPermissionRequest)
 	if config.OnUserInputRequest != nil {
@@ -646,11 +659,32 @@ func (c *Client) ResumeSessionWithOptions(ctx context.Context, sessionID string,
 	if config.Hooks != nil {
 		session.registerHooks(config.Hooks)
 	}
+	if config.OnEvent != nil {
+		session.On(config.OnEvent)
+	}
 
 	c.sessionsMux.Lock()
-	c.sessions[response.SessionID] = session
+	c.sessions[sessionID] = session
 	c.sessionsMux.Unlock()
 
+	result, err := c.client.Request("session.resume", req)
+	if err != nil {
+		c.sessionsMux.Lock()
+		delete(c.sessions, sessionID)
+		c.sessionsMux.Unlock()
+		return nil, fmt.Errorf("failed to resume session: %w", err)
+	}
+
+	var response resumeSessionResponse
+	if err := json.Unmarshal(result, &response); err != nil {
+		c.sessionsMux.Lock()
+		delete(c.sessions, sessionID)
+		c.sessionsMux.Unlock()
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	session.workspacePath = response.WorkspacePath
+
 	return session, nil
 }
 

go/go.mod

@@ -6,3 +6,5 @@ require (
 	github.com/google/jsonschema-go v0.4.2
 	github.com/klauspost/compress v1.18.3
 )
+
+require github.com/google/uuid v1.6.0