C#: make per-client Environment coherent per transport (#1930)

Author: SteveSandersonMS

dotnet/src/Client.cs

@@ -174,6 +174,8 @@ public CopilotClient(CopilotClientOptions? options = null)
                 throw new ArgumentException($"Unsupported RuntimeConnection type: {_connection.GetType().Name}", nameof(options));
         }
 
+        ValidateEnvironmentOptions(_options, _connection);
+
         _logger = _options.Logger ?? NullLogger.Instance;
         _onListModels = _options.OnListModels;
 
@@ -202,6 +204,53 @@ _options.SessionFs is not null ||
         }
     }
 
+    /// <summary>
+    /// Validates environment-variable options against the resolved transport.
+    /// Per-client environment is only representable for child-process transports
+    /// (each client owns its own OS process). The in-process (FFI) transport
+    /// loads the native runtime into the shared host process, whose single
+    /// environment block cannot carry per-client values, so environment and
+    /// telemetry options that lower to environment variables are rejected there.
+    /// </summary>
+    private static void ValidateEnvironmentOptions(CopilotClientOptions options, RuntimeConnection connection)
+    {
+        if (connection is InProcessRuntimeConnection)
+        {
+            if (options.Environment is not null)
+            {
+                throw new ArgumentException(
+                    $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.Environment)} is not supported with " +
+                    $"{nameof(RuntimeConnection)}.{nameof(RuntimeConnection.ForInProcess)}(): the in-process transport " +
+                    "loads the native runtime into the shared host process, whose single environment block cannot carry " +
+                    "per-client values. Set the variables on the host process environment instead.",
+                    nameof(options));
+            }
+
+            if (options.Telemetry is not null)
+            {
+                throw new ArgumentException(
+                    $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.Telemetry)} is not supported with " +
+                    $"{nameof(RuntimeConnection)}.{nameof(RuntimeConnection.ForInProcess)}(): telemetry configuration is " +
+                    "lowered to environment variables read by native runtime code running in the shared host process, so " +
+                    "per-client telemetry cannot be honored in-process. Configure telemetry via the host process " +
+                    "environment, or use a child-process transport.",
+                    nameof(options));
+            }
+
+            return;
+        }
+
+        if (connection is ChildProcessRuntimeConnection { Environment: not null } && options.Environment is not null)
+        {
+            throw new ArgumentException(
+                $"Set environment variables via either {nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.Environment)} " +
+                $"or {nameof(ChildProcessRuntimeConnection)}.{nameof(ChildProcessRuntimeConnection.Environment)}, not both. " +
+                $"Prefer {nameof(ChildProcessRuntimeConnection)}.{nameof(ChildProcessRuntimeConnection.Environment)} for " +
+                "child-process transports.",
+                nameof(options));
+        }
+    }
+
     /// <summary>
     /// Environment variable that overrides the transport used when the caller does not
     /// specify <see cref="CopilotClientOptions.Connection"/>. Accepts <c>"inprocess"</c>
@@ -1943,9 +1992,12 @@ private static void ApplyTelemetryEnvironment(IDictionary<string, string?> envir
         var tcpConnection = _connection as TcpRuntimeConnection;
         var useStdio = _connection is StdioRuntimeConnection;
 
-        // Use explicit path, COPILOT_CLI_PATH env var (from options.Environment or process env), or bundled runtime - no PATH fallback
-        var envCliPath = options.Environment is not null && options.Environment.TryGetValue("COPILOT_CLI_PATH", out var envValue) ? envValue
-            : System.Environment.GetEnvironmentVariable("COPILOT_CLI_PATH");
+        // Use explicit path, COPILOT_CLI_PATH env var (from the connection's
+        // Environment, options.Environment, or process env), or bundled runtime - no PATH fallback
+        var envCliPath =
+            (childProcessConnection.Environment is not null && childProcessConnection.Environment.TryGetValue("COPILOT_CLI_PATH", out var connEnvValue) ? connEnvValue : null)
+            ?? (options.Environment is not null && options.Environment.TryGetValue("COPILOT_CLI_PATH", out var envValue) ? envValue : null)
+            ?? System.Environment.GetEnvironmentVariable("COPILOT_CLI_PATH");
         var cliPath = childProcessConnection.Path
             ?? envCliPath
             ?? GetBundledCliPath(out var searchedPath)
@@ -2012,10 +2064,11 @@ private static void ApplyTelemetryEnvironment(IDictionary<string, string?> envir
             CreateNoWindow = true
         };
 
-        if (options.Environment != null)
+        var childEnvironment = options.Environment ?? childProcessConnection.Environment;
+        if (childEnvironment != null)
         {
             startInfo.Environment.Clear();
-            foreach (var (key, value) in options.Environment)
+            foreach (var (key, value) in childEnvironment)
             {
                 startInfo.Environment[key] = value;
             }

dotnet/src/Types.cs

@@ -173,6 +173,16 @@ internal ChildProcessRuntimeConnection() { }
 
     /// <summary>Extra command-line arguments to pass to the runtime process.</summary>
     public IList<string>? Args { get; set; }
+
+    /// <summary>
+    /// Gets or sets the environment variables passed to the spawned runtime process,
+    /// replacing the inherited environment.
+    /// </summary>
+    /// <remarks>
+    /// Cannot be combined with <see cref="CopilotClientOptions.Environment"/>; setting both throws
+    /// an <see cref="ArgumentException"/> when the client is constructed.
+    /// </remarks>
+    public IReadOnlyDictionary<string, string>? Environment { get; set; }
 }
 
 /// <summary>
@@ -358,7 +368,15 @@ private CopilotClientOptions(CopilotClientOptions? other)
     /// </summary>
     public CopilotLogLevel? LogLevel { get; set; }
 
-    /// <summary>Environment variables to pass to the runtime process.</summary>
+    /// <summary>
+    /// Gets or sets environment variables passed to the runtime process.
+    /// </summary>
+    /// <remarks>
+    /// Not supported with the in-process transport (<see cref="RuntimeConnection.ForInProcess"/>),
+    /// which runs the runtime in the host process; setting this option there throws an
+    /// <see cref="ArgumentException"/>. For child-process transports, prefer
+    /// <see cref="ChildProcessRuntimeConnection.Environment"/>; setting both throws.
+    /// </remarks>
     public IReadOnlyDictionary<string, string>? Environment { get; set; }
 
     /// <summary>Logger instance for SDK diagnostic output.</summary>

dotnet/test/ConnectionTokenTests.cs

@@ -113,7 +113,7 @@ public class ConnectionTokenAutoGeneratedTests : IAsyncLifetime
     public async Task InitializeAsync()
     {
         _ctx = await E2ETestContext.CreateAsync();
-        _client = _ctx.CreateClient(useStdio: false);
+        _client = _ctx.CreateClient(options: new CopilotClientOptions { Connection = RuntimeConnection.ForTcp() });
     }
 
     public async Task DisposeAsync()

dotnet/test/E2E/ClientOptionsE2ETests.cs

@@ -71,7 +71,6 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         {
             Connection = RuntimeConnection.ForStdio(path: cliPath, args: ["--capture-file", capturePath]),
             BaseDirectory = copilotHomeFromOption,
-            Environment = clientEnv,
             GitHubToken = "process-option-token",
             LogLevel = CopilotLogLevel.Debug,
             SessionIdleTimeoutSeconds = 17,
@@ -85,7 +84,7 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
                 CaptureContent = true,
             },
             UseLoggedInUser = false,
-        });
+        }, environment: clientEnv);
 
         await client.StartAsync();
 

dotnet/test/E2E/CopilotRequestWebSocketE2ETests.cs

@@ -51,8 +51,7 @@ public async Task Services_A_WebSocket_Turn_End_To_End_Via_The_Request_Handler()
         {
             Connection = RuntimeConnection.ForStdio(),
             RequestHandler = handler,
-            Environment = env,
-        });
+        }, environment: env);
         await client.StartAsync();
 
         var session = await client.CreateSessionAsync(new SessionConfig

dotnet/test/E2E/ModeHandlersE2ETests.cs

@@ -155,7 +155,7 @@ private CopilotClient CreateAuthenticatedClient()
             ["COPILOT_DEBUG_GITHUB_API_URL"] = Ctx.ProxyUrl,
         };
 
-        return Ctx.CreateClient(options: new CopilotClientOptions { Environment = env });
+        return Ctx.CreateClient(environment: env);
     }
 
     private Task ConfigureAuthenticatedUserAsync()

dotnet/test/E2E/PerSessionAuthE2ETests.cs

@@ -22,7 +22,7 @@ private CopilotClient CreateAuthTestClient()
         };
         // Disable the harness's auto-injected client token so the per-session
         // auth tests validate only session-scoped tokens.
-        return Ctx.CreateClient(options: new CopilotClientOptions { Environment = env }, autoInjectGitHubToken: false);
+        return Ctx.CreateClient(environment: env, autoInjectGitHubToken: false);
     }
 
     private CopilotClient CreateNoAuthTestClient()
@@ -32,9 +32,8 @@ private CopilotClient CreateNoAuthTestClient()
 
         return Ctx.CreateClient(options: new CopilotClientOptions
         {
-            Environment = env,
             UseLoggedInUser = false,
-        }, autoInjectGitHubToken: false);
+        }, autoInjectGitHubToken: false, environment: env);
     }
 
     private static Dictionary<string, string> WithoutAuthEnv(Dictionary<string, string> env)

dotnet/test/E2E/ProviderEndpointE2ETests.cs

@@ -23,7 +23,7 @@ private CopilotClient CreateProviderEndpointClient()
         {
             ["COPILOT_ALLOW_GET_PROVIDER_ENDPOINT"] = "true",
         };
-        return Ctx.CreateClient(options: new CopilotClientOptions { Environment = env });
+        return Ctx.CreateClient(environment: env);
     }
 
     [Fact]

dotnet/test/E2E/RpcExtensionsLoadedE2ETests.cs

@@ -58,8 +58,7 @@ private CopilotClient CreateExtensionsClient()
         return Ctx.CreateClient(options: new CopilotClientOptions
         {
             Connection = RuntimeConnection.ForStdio(args: ["--yolo"]),
-            Environment = ExtensionsEnabledEnvironment(),
-        });
+        }, environment: ExtensionsEnabledEnvironment());
     }
 
     /// <summary>

dotnet/test/E2E/RpcMcpAndSkillsE2ETests.cs

@@ -398,10 +398,7 @@ private CopilotClient CreateMcpAppsClient()
         environment["COPILOT_MCP_APPS"] = "true";
         environment["MCP_APPS"] = "true";
 
-        return Ctx.CreateClient(options: new CopilotClientOptions
-        {
-            Environment = environment,
-        });
+        return Ctx.CreateClient(environment: environment);
     }
 
     private static void CreateSkill(string skillsDir, string skillName, string description)