python: add in-process (FFI) transport (#1975)

Author: SteveSandersonMS

.github/workflows/python-sdk-tests.yml

@@ -31,7 +31,7 @@ permissions:
 
 jobs:
   test:
-    name: "Python SDK Tests"
+    name: "Python SDK Tests (${{ matrix.os }}, ${{ matrix.transport }})"
     if: github.event.repository.fork == false
     env:
       POWERSHELL_UPDATECHECK: Off
@@ -41,6 +41,7 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
         # Test the oldest supported Python version to make sure compatibility is maintained.
         python-version: ["3.11"]
+        transport: ["default", "inprocess"]
     runs-on: ${{ matrix.os }}
     defaults:
       run:
@@ -86,6 +87,11 @@ jobs:
         if: runner.os == 'Windows'
         run: pwsh.exe -Command "Write-Host 'PowerShell ready'"
 
+      - name: Select inprocess transport
+        if: matrix.transport == 'inprocess'
+        run: |
+          echo "COPILOT_SDK_DEFAULT_CONNECTION=inprocess" >> "$GITHUB_ENV"
+
       - name: Run Python SDK tests
         env:
           COPILOT_HMAC_KEY: ${{ secrets.COPILOT_DEVELOPER_CLI_INTEGRATION_HMAC_KEY }}

dotnet/src/Client.cs

@@ -237,6 +237,17 @@ private static void ValidateEnvironmentOptions(CopilotClientOptions options, Run
                     nameof(options));
             }
 
+            if (options.WorkingDirectory is not null)
+            {
+                throw new ArgumentException(
+                    $"{nameof(CopilotClientOptions)}.{nameof(CopilotClientOptions.WorkingDirectory)} is not supported with " +
+                    $"{nameof(RuntimeConnection)}.{nameof(RuntimeConnection.ForInProcess)}(): the in-process transport hosts " +
+                    "the native runtime in the shared host process and spawns the worker without a working-directory " +
+                    "parameter, so a per-client working directory cannot be honored in-process. Use a child-process " +
+                    "transport, or set the process working directory before creating the client.",
+                    nameof(options));
+            }
+
             return;
         }
 

dotnet/test/Harness/E2ETestContext.cs

@@ -244,9 +244,17 @@ public CopilotClient CreateClient(
     {
         options ??= new CopilotClientOptions();
 
-        options.WorkingDirectory ??= WorkDir;
         options.Logger ??= Logger;
 
+        // Resolve the working directory the worker should run in. Child-process and
+        // URI transports take it as a per-client option; the in-process transport
+        // rejects a per-client WorkingDirectory (the native host spawns the worker
+        // without a cwd parameter), so — mirroring the Node/Rust harnesses — we point
+        // THIS process's cwd at the desired directory before the worker spawns and
+        // clear the per-client option. InProcessEnvIsolationAttribute.After restores
+        // the cwd after the test.
+        var desiredWorkingDirectory = options.WorkingDirectory ?? WorkDir;
+
         // Tests must supply environment via the 'environment' parameter, which the
         // harness routes to the right place per transport (the connection for
         // child-process transports, the host process for in-process). Setting
@@ -300,12 +308,24 @@ public CopilotClient CreateClient(
             {
                 InProcessEnvIsolation.Apply(name, value);
             }
+
+            // A per-client WorkingDirectory is rejected in-process; instead point this
+            // process's cwd at the desired directory so the worker inherits it at spawn
+            // (restored after the test by InProcessEnvIsolationAttribute).
+            options.WorkingDirectory = null;
+            InProcessEnvIsolation.SetWorkingDirectory(desiredWorkingDirectory);
         }
         else if (options.Connection is ChildProcessRuntimeConnection child)
         {
             // Child-process transport: hand the environment to the spawned child
             // via the connection, where per-client environment is coherent.
             child.Environment = env;
+            options.WorkingDirectory = desiredWorkingDirectory;
+        }
+        else
+        {
+            // URI / existing-runtime transport: per-client WorkingDirectory applies normally.
+            options.WorkingDirectory = desiredWorkingDirectory;
         }
 
         // Auto-inject auth token unless connecting to an existing runtime via URI.

dotnet/test/Harness/InProcessEnvIsolation.cs

@@ -22,6 +22,11 @@ internal static class InProcessEnvIsolation
     // Captured at load, before any fixture/test mutates env.
     private static readonly Dictionary<string, string?> s_ambient = CaptureEnvironment();
 
+    // The process working directory captured at load, restored after each test so an
+    // in-process test that repoints the cwd (the FFI worker inherits it at spawn)
+    // can't leak that change into the next test.
+    private static readonly string s_ambientCwd = Directory.GetCurrentDirectory();
+
     // Runs at assembly load so the ambient env is snapshotted before the shared
     // fixture mirrors per-test env onto the process. Justifies suppressing CA2255.
 #pragma warning disable CA2255 // ModuleInitializer discouraged in libraries; intentional in this test harness.
@@ -56,8 +61,21 @@ public static void NeutralizeAmbientCredentials()
         }
     }
 
+    // Points the process working directory at the given path so the in-process FFI
+    // worker inherits it at spawn (the native host has no per-client cwd parameter).
+    // RestoreAmbient() returns the process to its load-time cwd after the test.
+    public static void SetWorkingDirectory(string path) =>
+        Directory.SetCurrentDirectory(path);
+
     public static void RestoreAmbient()
     {
+        // Unconditionally repoint the process cwd at its load-time value. We must
+        // not read Directory.GetCurrentDirectory() first: an in-process test can
+        // chdir into a temp work dir that the harness then deletes, so getcwd()
+        // would throw FileNotFoundException. SetCurrentDirectory to an absolute
+        // path succeeds regardless of whether the old cwd still exists.
+        Directory.SetCurrentDirectory(s_ambientCwd);
+
         foreach (DictionaryEntry entry in Environment.GetEnvironmentVariables())
         {
             var name = (string)entry.Key;

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

@@ -103,15 +103,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";
 }
 
 /**
@@ -137,7 +151,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.
@@ -150,10 +164,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[];
 }
 
 /**
@@ -177,8 +187,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.
@@ -189,6 +201,7 @@ export const RuntimeConnection = {
             connectionToken?: string;
             path?: string;
             args?: readonly string[];
+            env?: Record<string, string>;
         } = {}
     ): TcpRuntimeConnection {
         return {
@@ -197,6 +210,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", () => {