On branch edburns/dd-2758695-virtual-threads-accept-executor

modified:   src/main/java/com/github/copilot/sdk/CopilotClient.java

- Spotless.

modified:   src/main/java/com/github/copilot/sdk/json/CopilotClientOptions.java

- Remove stub from TDD red phase.

modified:   src/site/markdown/cookbook/multiple-sessions.md

- Document new feature.

modified:   src/test/java/com/github/copilot/sdk/ExecutorWiringTest.java

- Update test documentation.

Signed-off-by: Ed Burns <edburns@microsoft.com>

Author: edburns

src/main/java/com/github/copilot/sdk/CopilotClient.java

@@ -188,8 +188,7 @@ private Connection startCoreBody() {
         } catch (Exception e) {
             String stderr = serverManager.getStderrOutput();
             if (!stderr.isEmpty()) {
-                throw new CompletionException(
-                        new IOException("CLI process exited unexpectedly. stderr: " + stderr, e));
+                throw new CompletionException(new IOException("CLI process exited unexpectedly. stderr: " + stderr, e));
             }
             throw new CompletionException(e);
         }
@@ -245,9 +244,8 @@ public CompletableFuture<Void> stop() {
                     LOG.log(Level.WARNING, "Error closing session " + session.getSessionId(), e);
                 }
             };
-            closeFutures.add(exec != null
-                    ? CompletableFuture.runAsync(closeTask, exec)
-                    : CompletableFuture.runAsync(closeTask));
+            closeFutures.add(
+                    exec != null ? CompletableFuture.runAsync(closeTask, exec) : CompletableFuture.runAsync(closeTask));
         }
         sessions.clear();
 

src/main/java/com/github/copilot/sdk/json/CopilotClientOptions.java

@@ -429,18 +429,14 @@ public Executor getExecutor() {
      * <p>
      * When provided, the SDK uses this executor for all internal
      * {@code CompletableFuture} combinators instead of the default
-     * {@code ForkJoinPool.commonPool()}. This allows callers to isolate SDK
-     * work onto a dedicated thread pool or integrate with container-managed
-     * threading.
+     * {@code ForkJoinPool.commonPool()}. This allows callers to isolate SDK work
+     * onto a dedicated thread pool or integrate with container-managed threading.
      *
      * @param executor
      *            the executor to use, or {@code null} for the default
      * @return this options instance for fluent chaining
      */
     public CopilotClientOptions setExecutor(Executor executor) {
-        if (null == executor) {
-            throw new IllegalArgumentException("PENDING(copilot): not implemented");
-        }
         this.executor = executor;
         return this;
     }

src/site/markdown/cookbook/multiple-sessions.md

@@ -164,6 +164,69 @@ public class ParallelSessions {
 }
 ```
 
+## Providing a custom Executor for parallel sessions
+
+By default, `CompletableFuture` operations run on `ForkJoinPool.commonPool()`,
+which has limited parallelism (typically `Runtime.availableProcessors() - 1`
+threads). When multiple sessions block waiting for CLI responses, those threads
+are unavailable for other work—a condition known as *pool starvation*.
+
+Use `CopilotClientOptions.setExecutor(Executor)` to supply a dedicated thread
+pool so that SDK work does not compete with the rest of your application for
+common-pool threads:
+
+```java
+//DEPS com.github:copilot-sdk-java:${project.version}
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.json.CopilotClientOptions;
+import com.github.copilot.sdk.json.SessionConfig;
+import com.github.copilot.sdk.json.MessageOptions;
+import com.github.copilot.sdk.json.PermissionHandler;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+
+public class ParallelSessionsWithExecutor {
+    public static void main(String[] args) throws Exception {
+        ExecutorService pool = Executors.newFixedThreadPool(4);
+        try {
+            var options = new CopilotClientOptions().setExecutor(pool);
+            try (CopilotClient client = new CopilotClient(options)) {
+                client.start().get();
+
+                var s1 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-5")).get();
+                var s2 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("gpt-5")).get();
+                var s3 = client.createSession(new SessionConfig()
+                    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                    .setModel("claude-sonnet-4.5")).get();
+
+                CompletableFuture.allOf(
+                    s1.sendAndWait(new MessageOptions().setPrompt("Question 1")),
+                    s2.sendAndWait(new MessageOptions().setPrompt("Question 2")),
+                    s3.sendAndWait(new MessageOptions().setPrompt("Question 3"))
+                ).get();
+
+                s1.close();
+                s2.close();
+                s3.close();
+            }
+        } finally {
+            pool.shutdown();
+        }
+    }
+}
+```
+
+Passing `null` (or omitting `setExecutor` entirely) keeps the default
+`ForkJoinPool.commonPool()` behaviour. The executor is used for all internal
+`CompletableFuture.runAsync` / `supplyAsync` calls—including client start/stop,
+tool-call dispatch, permission dispatch, user-input dispatch, and hooks.
+
 ## Use cases
 
 - **Multi-user applications**: One session per user

src/test/java/com/github/copilot/sdk/ExecutorWiringTest.java

@@ -25,7 +25,6 @@
 import com.github.copilot.sdk.json.CopilotClientOptions;
 import com.github.copilot.sdk.json.MessageOptions;
 import com.github.copilot.sdk.json.PermissionHandler;
-import com.github.copilot.sdk.json.PermissionRequest;
 import com.github.copilot.sdk.json.PermissionRequestResult;
 import com.github.copilot.sdk.json.PreToolUseHookOutput;
 import com.github.copilot.sdk.json.SessionConfig;
@@ -62,8 +61,8 @@ static void teardown() throws Exception {
     }
 
     /**
-     * A decorator executor that delegates to a real executor while counting
-     * task submissions.
+     * A decorator executor that delegates to a real executor while counting task
+     * submissions.
      */
     static class TrackingExecutor implements Executor {
 
@@ -101,8 +100,8 @@ private CopilotClientOptions createOptionsWithExecutor(TrackingExecutor executor
      *
      * <p>
      * {@code CopilotClient.startCore()} uses
-     * {@code CompletableFuture.supplyAsync(...)} to initialize the connection.
-     * This test asserts that the start-up task goes through the caller-supplied
+     * {@code CompletableFuture.supplyAsync(...)} to initialize the connection. This
+     * test asserts that the start-up task goes through the caller-supplied
      * executor, not {@code ForkJoinPool.commonPool()}.
      * </p>
      *
@@ -129,9 +128,8 @@ void testClientStartUsesProvidedExecutor() throws Exception {
      * Verifies that tool call dispatch routes through the provided executor.
      *
      * <p>
-     * When a custom tool is invoked by the LLM, the
-     * {@code RpcHandlerDispatcher} calls
-     * {@code CompletableFuture.runAsync(...)} to dispatch the tool handler.
+     * When a custom tool is invoked by the LLM, the {@code RpcHandlerDispatcher}
+     * calls {@code CompletableFuture.runAsync(...)} to dispatch the tool handler.
      * This test asserts that dispatch goes through the caller-supplied executor.
      * </p>
      *
@@ -187,10 +185,9 @@ void testToolCallDispatchUsesProvidedExecutor() throws Exception {
      * executor.
      *
      * <p>
-     * When the LLM requests a permission, the {@code RpcHandlerDispatcher}
-     * calls {@code CompletableFuture.runAsync(...)} to dispatch the permission
-     * handler. This test asserts that dispatch goes through the caller-supplied
-     * executor.
+     * When the LLM requests a permission, the {@code RpcHandlerDispatcher} calls
+     * {@code CompletableFuture.runAsync(...)} to dispatch the permission handler.
+     * This test asserts that dispatch goes through the caller-supplied executor.
      * </p>
      *
      * @see Snapshot: permissions/permission_handler_for_write_operations
@@ -212,8 +209,7 @@ void testPermissionDispatchUsesProvidedExecutor() throws Exception {
 
             int beforeSend = trackingExecutor.getTaskCount();
 
-            session.sendAndWait(
-                    new MessageOptions().setPrompt("Edit test.txt and replace 'original' with 'modified'"))
+            session.sendAndWait(new MessageOptions().setPrompt("Edit test.txt and replace 'original' with 'modified'"))
                     .get(60, TimeUnit.SECONDS);
 
             assertTrue(trackingExecutor.getTaskCount() > beforeSend,
@@ -231,9 +227,8 @@ void testPermissionDispatchUsesProvidedExecutor() throws Exception {
      *
      * <p>
      * When the LLM asks for user input, the {@code RpcHandlerDispatcher} calls
-     * {@code CompletableFuture.runAsync(...)} to dispatch the user input
-     * handler. This test asserts that dispatch goes through the caller-supplied
-     * executor.
+     * {@code CompletableFuture.runAsync(...)} to dispatch the user input handler.
+     * This test asserts that dispatch goes through the caller-supplied executor.
      * </p>
      *
      * @see Snapshot:
@@ -278,8 +273,8 @@ void testUserInputDispatchUsesProvidedExecutor() throws Exception {
      *
      * <p>
      * When the LLM triggers a hook, the {@code RpcHandlerDispatcher} calls
-     * {@code CompletableFuture.runAsync(...)} to dispatch the hooks handler.
-     * This test asserts that dispatch goes through the caller-supplied executor.
+     * {@code CompletableFuture.runAsync(...)} to dispatch the hooks handler. This
+     * test asserts that dispatch goes through the caller-supplied executor.
      * </p>
      *
      * @see Snapshot: hooks/invoke_pre_tool_use_hook_when_model_runs_a_tool
@@ -316,14 +311,13 @@ void testHooksDispatchUsesProvidedExecutor() throws Exception {
     }
 
     /**
-     * Verifies that {@code CopilotClient.stop()} routes session closure through
-     * the provided executor.
+     * Verifies that {@code CopilotClient.stop()} routes session closure through the
+     * provided executor.
      *
      * <p>
-     * {@code CopilotClient.stop()} uses
-     * {@code CompletableFuture.runAsync(...)} to close each active session.
-     * This test asserts that those closures go through the caller-supplied
-     * executor.
+     * {@code CopilotClient.stop()} uses {@code CompletableFuture.runAsync(...)} to
+     * close each active session. This test asserts that those closures go through
+     * the caller-supplied executor.
      * </p>
      *
      * @see Snapshot: tools/invokes_custom_tool