node: add per-connection env + in-process env/telemetry guards

Bring the Node SDK to parity with .NET and Python on the transport env API:

- Factor a shared ChildProcessRuntimeConnection base interface for the
  stdio/tcp transports and give it a per-connection `env`, exposed via
  forStdio/forTcp. Connection-level env takes precedence over the client-level
  env, which falls back to process.env.
- Reject at construction: `env` or `telemetry` with forInProcess() (the shared
  host process can't carry per-client values; workingDirectory was already
  rejected), and `env` set on both the client and the connection for
  child-process transports.
- Unit tests for all guards + precedence; README documents the connection env
  and in-process restrictions.

Also drop the redundant "coherent only for child-process transports" phrasing
from the Python connection env docstring (it's attached to the child-process
base already).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a96d1a82-c80e-40f1-a3df-a9708429b68b

Author: SteveSandersonMS

nodejs/README.md

@@ -84,9 +84,11 @@ new CopilotClient(options?: CopilotClientOptions)
 **Options:**
 
 - `connection?: RuntimeConnection` - How to connect to the Copilot runtime. Construct via the factory functions on `RuntimeConnection`:
-    - `RuntimeConnection.forStdio({ path?, args? })` (default) — spawn the runtime and communicate over its stdin/stdout.
-    - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args? })` — spawn the runtime as a TCP server.
+    - `RuntimeConnection.forStdio({ path?, args?, env? })` (default) — spawn the runtime and communicate over its stdin/stdout.
+    - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args?, env? })` — spawn the runtime as a TCP server.
     - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
+    - `RuntimeConnection.forInProcess()` — host the runtime in-process over its native C ABI (FFI). **Experimental.** Because the runtime shares this process, `env`, `telemetry`, and `workingDirectory` are rejected with this transport; set them on the host process instead.
+    - The child-process transports (`forStdio`/`forTcp`) also accept a per-connection `env`. Set it there or via the top-level `env` option — not both (setting both throws).
 - `mode?: "empty" | "copilot-cli"` - Defaulting strategy. Use `"empty"` for multi-user server mode; defaults to `"copilot-cli"`.
 - `workingDirectory?: string` - Working directory for the runtime process (default: current process cwd).
 - `baseDirectory?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned runtime. When not set, the runtime defaults to `~/.copilot`. Ignored when connecting via `RuntimeConnection.forUri`.

nodejs/src/client.ts

@@ -644,6 +644,32 @@ export class CopilotClient {
                     "constructing the client instead."
             );
         }
+        if (conn.kind === "inprocess" && options.env !== undefined) {
+            throw new Error(
+                "env is not supported with 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."
+            );
+        }
+        if (conn.kind === "inprocess" && options.telemetry !== undefined) {
+            throw new Error(
+                "telemetry is not supported with 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."
+            );
+        }
+        if (
+            (conn.kind === "stdio" || conn.kind === "tcp") &&
+            conn.env !== undefined &&
+            options.env !== undefined
+        ) {
+            throw new Error(
+                "Set environment variables via either the client-level env option or the connection's env " +
+                    "(RuntimeConnection.forStdio/forTcp), not both. Prefer the connection-level env for " +
+                    "child-process transports."
+            );
+        }
         if (conn.kind === "tcp" && conn.connectionToken !== undefined) {
             if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
                 throw new Error("connectionToken must be a non-empty string");
@@ -681,7 +707,13 @@ export class CopilotClient {
         this.onGitHubTelemetry = options.onGitHubTelemetry;
         this.setupClientGlobalHandlers();
 
-        const effectiveEnv = options.env ?? process.env;
+        // Connection-level env (child-process transports only) takes precedence
+        // over the client-level env, which falls back to the ambient process env.
+        // The constructor guard above rejects setting both, so at most one of the
+        // first two is defined. Mirrors .NET/Python precedence.
+        const connEnv: Record<string, string> | undefined =
+            conn.kind === "stdio" || conn.kind === "tcp" ? conn.env : undefined;
+        const effectiveEnv = connEnv ?? options.env ?? process.env;
         this.resolvedEnv = effectiveEnv;
         this.resolvedCliPath =
             conn.kind === "stdio" || conn.kind === "tcp"

nodejs/src/index.ts

@@ -63,6 +63,7 @@ export type {
     InProcessRuntimeConnection,
     TcpRuntimeConnection,
     UriRuntimeConnection,
+    ChildProcessRuntimeConnection,
     CustomAgentConfig,
     ElicitationFieldValue,
     ElicitationHandler,

nodejs/src/types.ts

@@ -101,15 +101,29 @@ export type RuntimeConnection =
     | UriRuntimeConnection;
 
 /**
- * Spawns a runtime child process and communicates over its stdin/stdout.
- * This is the default if no {@link CopilotClientOptions.connection} is set.
+ * Shared shape for the transports that spawn a runtime **child process**
+ * ({@link StdioRuntimeConnection} and {@link TcpRuntimeConnection}).
  */
-export interface StdioRuntimeConnection {
-    readonly kind: "stdio";
+export interface ChildProcessRuntimeConnection {
     /** Path to the runtime executable. When omitted, the bundled runtime is used. */
     readonly path?: string;
     /** Extra command-line arguments to pass to the runtime process. */
     readonly args?: readonly string[];
+    /**
+     * Environment variables for the spawned runtime child process, replacing the
+     * inherited environment. Cannot be combined with
+     * {@link CopilotClientOptions.env}; setting both throws when the client is
+     * constructed. When omitted, the client-level env (or `process.env`) is used.
+     */
+    readonly env?: Record<string, string>;
+}
+
+/**
+ * Spawns a runtime child process and communicates over its stdin/stdout.
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
+ */
+export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
+    readonly kind: "stdio";
 }
 
 /**
@@ -135,7 +149,7 @@ export interface InProcessRuntimeConnection {
 /**
  * Spawns a runtime child process that listens on a TCP socket and connects to it.
  */
-export interface TcpRuntimeConnection {
+export interface TcpRuntimeConnection extends ChildProcessRuntimeConnection {
     readonly kind: "tcp";
     /**
      * TCP port to listen on. `0` (the default) auto-allocates a free port.
@@ -148,10 +162,6 @@ export interface TcpRuntimeConnection {
      * loopback listener is safe by default.
      */
     readonly connectionToken?: string;
-    /** Path to the runtime executable. When omitted, the bundled runtime is used. */
-    readonly path?: string;
-    /** Extra command-line arguments to pass to the runtime process. */
-    readonly args?: readonly string[];
 }
 
 /**
@@ -175,8 +185,10 @@ export const RuntimeConnection = {
      * Spawn a runtime child process and communicate over its stdin/stdout.
      * This is the default if no {@link CopilotClientOptions.connection} is set.
      */
-    forStdio(opts: { path?: string; args?: readonly string[] } = {}): StdioRuntimeConnection {
-        return { kind: "stdio", path: opts.path, args: opts.args };
+    forStdio(
+        opts: { path?: string; args?: readonly string[]; env?: Record<string, string> } = {}
+    ): StdioRuntimeConnection {
+        return { kind: "stdio", path: opts.path, args: opts.args, env: opts.env };
     },
     /**
      * Spawn a runtime child process that listens on a TCP socket and connect to it.
@@ -187,6 +199,7 @@ export const RuntimeConnection = {
             connectionToken?: string;
             path?: string;
             args?: readonly string[];
+            env?: Record<string, string>;
         } = {}
     ): TcpRuntimeConnection {
         return {
@@ -195,6 +208,7 @@ export const RuntimeConnection = {
             connectionToken: opts.connectionToken,
             path: opts.path,
             args: opts.args,
+            env: opts.env,
         };
     },
     /**

nodejs/test/client.test.ts

@@ -2007,6 +2007,77 @@ describe("CopilotClient", () => {
                 /gitHubToken and useLoggedInUser cannot be used with RuntimeConnection.forUri/
             );
         });
+
+        it("should throw error when env is used with forInProcess", () => {
+            expect(() => {
+                new CopilotClient({
+                    connection: RuntimeConnection.forInProcess(),
+                    env: { FOO: "bar" },
+                    logLevel: "error",
+                });
+            }).toThrow(/env is not supported with RuntimeConnection.forInProcess/);
+        });
+
+        it("should throw error when telemetry is used with forInProcess", () => {
+            expect(() => {
+                new CopilotClient({
+                    connection: RuntimeConnection.forInProcess(),
+                    telemetry: { otlpEndpoint: "http://localhost:4318" },
+                    logLevel: "error",
+                });
+            }).toThrow(/telemetry is not supported with RuntimeConnection.forInProcess/);
+        });
+
+        it("should throw error when workingDirectory is used with forInProcess", () => {
+            expect(() => {
+                new CopilotClient({
+                    connection: RuntimeConnection.forInProcess(),
+                    workingDirectory: "/tmp",
+                    logLevel: "error",
+                });
+            }).toThrow(/workingDirectory is not supported with RuntimeConnection.forInProcess/);
+        });
+
+        it("should throw error when env is set on both the client and a stdio connection", () => {
+            expect(() => {
+                new CopilotClient({
+                    connection: RuntimeConnection.forStdio({ env: { FOO: "conn" } }),
+                    env: { FOO: "client" },
+                    logLevel: "error",
+                });
+            }).toThrow(
+                /Set environment variables via either the client-level env option or the connection/
+            );
+        });
+
+        it("should throw error when env is set on both the client and a tcp connection", () => {
+            expect(() => {
+                new CopilotClient({
+                    connection: RuntimeConnection.forTcp({ env: { FOO: "conn" } }),
+                    env: { FOO: "client" },
+                    logLevel: "error",
+                });
+            }).toThrow(
+                /Set environment variables via either the client-level env option or the connection/
+            );
+        });
+
+        it("should use the connection-level env for child-process transports", () => {
+            const client = new CopilotClient({
+                connection: RuntimeConnection.forStdio({ env: { FOO: "from-conn" } }),
+                logLevel: "error",
+            });
+            expect((client as any).resolvedEnv).toEqual({ FOO: "from-conn" });
+        });
+
+        it("should allow env on the client alone with a child-process transport", () => {
+            const client = new CopilotClient({
+                connection: RuntimeConnection.forStdio(),
+                env: { FOO: "from-client" },
+                logLevel: "error",
+            });
+            expect((client as any).resolvedEnv).toEqual({ FOO: "from-client" });
+        });
     });
 
     describe("overridesBuiltInTool in tool definitions", () => {

python/copilot/client.py

@@ -400,9 +400,8 @@ class ChildProcessRuntimeConnection(RuntimeConnection):
     env: dict[str, str] | None = None
     """Per-connection environment variables for the spawned child process.
 
-    Coherent only for child-process transports (each client owns its own OS
-    process). When set, do not also set :attr:`CopilotClientOptions.env` — the
-    client rejects setting environment in both places. ``None`` inherits the
+    When set, do not also set :attr:`CopilotClientOptions.env` — the client
+    rejects setting environment in both places. ``None`` inherits the
     client-level env (or the current process env)."""