C# API review fixes

dotnet/README.md

@@ -1,4 +1,4 @@
-# Copilot SDK
+# Copilot SDK
 
 SDK for programmatic control of GitHub Copilot CLI.
 
@@ -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)
     {
@@ -72,20 +72,24 @@ new CopilotClient(CopilotClientOptions? options = null)
 
 **Options:**
 
-- `CliPath` - Path to CLI executable (default: `COPILOT_CLI_PATH` env var, or bundled CLI)
-- `CliArgs` - Extra arguments prepended before SDK-managed flags
-- `CliUrl` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`). When provided, the client will not spawn a CLI process.
-- `Port` - Server port (default: 0 for random)
-- `UseStdio` - Use stdio transport instead of TCP (default: true)
-- `LogLevel` - Log level (default: "info")
-- `AutoStart` - Auto-start server (default: true)
-- `Cwd` - Working directory for the CLI process
-- `CopilotHome` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `CliUrl`.
-- `Environment` - Environment variables to pass to the CLI process
-- `Logger` - `ILogger` instance for SDK logging
+- `Connection` - How to connect to the Copilot runtime. Defaults to `null` (equivalent to `RuntimeConnection.Stdio()` with the bundled runtime). See "RuntimeConnection" below.
+- `LogLevel` - Runtime log level. Accepts well-known values `CopilotLogLevel.None`, `Error`, `Warning`, `Info`, `Debug`, `All`. Defaults to null (the runtime's own default).
+- `WorkingDirectory` - Working directory for the runtime process.
+- `BaseDirectory` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned runtime process. When not set, the runtime defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when connecting via `RuntimeConnection.Uri(...)`.
+- `EnableRemoteSessions` - Enables remote-session features.
+- `Environment` - Environment variables to pass to the runtime process.
+- `Logger` - `ILogger` instance for SDK logging.
 - `GitHubToken` - GitHub token for authentication. When provided, takes priority over other auth methods.
-- `UseLoggedInUser` - Whether to use logged-in user for authentication (default: true, but false when `GitHubToken` is provided). Cannot be used with `CliUrl`.
-- `Telemetry` - OpenTelemetry configuration for the CLI process. Providing this enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
+- `UseLoggedInUser` - Whether to use logged-in user for authentication (default: true, but false when `GitHubToken` is provided). Cannot be used with `RuntimeConnection.Uri(...)`.
+- `Telemetry` - OpenTelemetry configuration for the runtime process. Providing this enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
+
+#### RuntimeConnection
+
+`CopilotClientOptions.Connection` describes how the SDK reaches a Copilot runtime. There are three flavors, all constructed via static factories:
+
+- `RuntimeConnection.Stdio(path?, args?)` — spawns the runtime as a child process and communicates over stdio. This is the default when `Connection` is null.
+- `RuntimeConnection.Tcp(port = 0, connectionToken?, path?, args?)` — spawns the runtime as a child process listening on a TCP port. `port = 0` auto-allocates; if a non-zero port is already in use, startup fails (no fallback). Use `CopilotClient.RuntimePort` after `StartAsync` to read the assigned port. `connectionToken` is required if other clients will connect via `RuntimeConnection.Uri(...)`.
+- `RuntimeConnection.Uri(url, connectionToken?)` — connects to an already-running runtime at `url` (e.g., `"localhost:8080"`). Does not spawn a process.
 
 #### Methods
 
@@ -153,35 +157,31 @@ Get the ID of the session currently displayed in the TUI. Only available when co
 
 Request the TUI to switch to displaying the specified session. Only available in TUI+server mode.
 
-##### `On(Action<SessionLifecycleEvent> handler): IDisposable`
+##### `OnLifecycle<T>(Action<T> handler): IDisposable where T : SessionLifecycleEvent`
 
-Subscribe to all session lifecycle events. Returns an `IDisposable` that unsubscribes when disposed.
+Subscribe to session lifecycle events. Pass a derived type to filter by kind, or `SessionLifecycleEvent` to receive every lifecycle event. Returns an `IDisposable` that unsubscribes when disposed.
 
 ```csharp
-using var subscription = client.On(evt =>
+// Receive every lifecycle event:
+using var subscription = client.OnLifecycle<SessionLifecycleEvent>(evt =>
 {
     Console.WriteLine($"Session {evt.SessionId}: {evt.Type}");
 });
-```
 
-##### `On(string eventType, Action<SessionLifecycleEvent> handler): IDisposable`
-
-Subscribe to a specific lifecycle event type. Use `SessionLifecycleEventTypes` constants.
-
-```csharp
-using var subscription = client.On(SessionLifecycleEventTypes.Foreground, evt =>
+// Only receive foreground events:
+using var foreground = client.OnLifecycle<SessionForegroundEvent>(evt =>
 {
     Console.WriteLine($"Session {evt.SessionId} is now in foreground");
 });
 ```
 
 **Lifecycle Event Types:**
 
-- `SessionLifecycleEventTypes.Created` - A new session was created
-- `SessionLifecycleEventTypes.Deleted` - A session was deleted
-- `SessionLifecycleEventTypes.Updated` - A session was updated
-- `SessionLifecycleEventTypes.Foreground` - A session became the foreground session in TUI
-- `SessionLifecycleEventTypes.Background` - A session is no longer the foreground session
+- `SessionCreatedEvent` — A new session was created
+- `SessionDeletedEvent` — A session was deleted
+- `SessionUpdatedEvent` — A session was updated
+- `SessionForegroundEvent` — A session became the foreground session in TUI
+- `SessionBackgroundEvent` — A session is no longer the foreground session
 
 ---
 
@@ -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}");
 });
@@ -226,7 +226,7 @@ subscription.Dispose();
 
 Abort the currently processing message in this session.
 
-##### `GetMessagesAsync(): Task<IReadOnlyList<SessionEvent>>`
+##### `GetEventsAsync(): Task<IReadOnlyList<SessionEvent>>`
 
 Get all events/messages from this session.
 
@@ -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)
     {
@@ -558,15 +558,15 @@ if (session.Capabilities.Ui?.Elicitation == true)
         ["production", "staging", "dev"]);
 
     // Text input — returns string or null
-    string? name = await session.Ui.InputAsync("Project name:", new InputOptions
+    string? name = await session.Ui.InputAsync("Project name:", new UiInputOptions
     {
         Title = "Name",
         MinLength = 1,
         MaxLength = 50,
     });
 
     // Generic elicitation with full schema control
-    ElicitationResult result = await session.Ui.ElicitationAsync(new ElicitationParams
+    ElicitationResult result = await session.Ui.ElicitAsync(new ElicitationParams
     {
         Message = "Configure deployment",
         RequestedSchema = new ElicitationSchema
@@ -749,7 +749,7 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 ### Custom Permission Handler
 
-Provide your own `PermissionRequestHandler` delegate to inspect each request and apply custom logic:
+Provide your own permission handler (`Func<PermissionRequest, ToolInvocation, Task<PermissionRequestResult>>`) to inspect each request and apply custom logic:
 
 ```csharp
 var session = await client.CreateSessionAsync(new SessionConfig
@@ -987,7 +987,7 @@ catch (Exception ex)
 ## Requirements
 
 - .NET 8.0 or later
-- GitHub Copilot CLI installed and in PATH (or provide custom `CliPath`)
+- GitHub Copilot CLI installed and in PATH (or provide custom `Connection = RuntimeConnection.Stdio(path: ...)`)
 
 ## License
 

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))
         {