Port reference implementation changes: remote sessions, provider model overrides, startup cleanup race fix

- Add Remote option to CopilotClientOptions with --remote CLI flag
- Add modelId, wireModel, maxPromptTokens, maxOutputTokens to ProviderConfig
- Fix client startup cleanup race condition (process cleanup on failure)
- Update E2E test harness for CONNECT proxy metadata
- Add unit tests for new provider config fields and clone
- Add E2E tests for provider wire model feature
- Document remote sessions and model overrides in advanced.md

Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Author: Copilot

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

@@ -102,6 +102,10 @@ ProcessInfo startCliServer() throws IOException, InterruptedException {
             args.add(String.valueOf(options.getSessionIdleTimeoutSeconds()));
         }
 
+        if (options.isRemote()) {
+            args.add("--remote");
+        }
+
         List<String> command = resolveCliCommand(cliPath, args);
 
         var pb = new ProcessBuilder(command);

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

@@ -187,9 +187,9 @@ private CompletableFuture<Connection> startCore() {
     }
 
     private Connection startCoreBody() {
+        Process process = null;
         try {
             JsonRpcClient rpc;
-            Process process = null;
 
             if (optionsHost != null && optionsPort != null) {
                 // External server (TCP)
@@ -215,6 +215,10 @@ private Connection startCoreBody() {
             LOG.info("Copilot client connected");
             return connection;
         } catch (Exception e) {
+            // Clean up the spawned process if connection setup failed
+            if (process != null) {
+                cleanupCliProcess(process);
+            }
             String stderr = serverManager.getStderrOutput();
             if (!stderr.isEmpty()) {
                 throw new CompletionException(new IOException(
@@ -352,21 +356,28 @@ private CompletableFuture<Void> cleanupConnection() {
             }
 
             if (connection.process != null) {
-                try {
-                    if (connection.process.isAlive()) {
-                        Process destroyedProcess = connection.process.destroyForcibly();
-                        if (!destroyedProcess.waitFor(FORCE_KILL_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
-                            LOG.fine("Process did not terminate within force kill timeout");
-                        }
-                    }
-                } catch (InterruptedException e) {
-                    Thread.currentThread().interrupt();
-                    LOG.log(Level.FINE, "Interrupted while killing process", e);
-                } catch (Exception e) {
-                    LOG.log(Level.FINE, "Error killing process", e);
+                cleanupCliProcess(connection.process);
+            }
+        }).exceptionally(ex -> {
+            LOG.log(Level.FINE, "Ignoring failed Copilot client startup during cleanup", ex);
+            return null;
+        });
+    }
+
+    private static void cleanupCliProcess(Process process) {
+        try {
+            if (process.isAlive()) {
+                Process destroyedProcess = process.destroyForcibly();
+                if (!destroyedProcess.waitFor(FORCE_KILL_TIMEOUT_SECONDS, TimeUnit.SECONDS)) {
+                    LOG.fine("Process did not terminate within force kill timeout");
                 }
             }
-        }).exceptionally(ex -> null);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            LOG.log(Level.FINE, "Interrupted while killing process", e);
+        } catch (Exception e) {
+            LOG.log(Level.FINE, "Error killing process", e);
+        }
     }
 
     /**

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

@@ -54,6 +54,7 @@ public class CopilotClientOptions {
     private int port;
     private TelemetryConfig telemetry;
     private Integer sessionIdleTimeoutSeconds;
+    private boolean remote;
     private String tcpConnectionToken;
     private Boolean useLoggedInUser;
     private boolean useStdio = true;
@@ -438,6 +439,37 @@ public CopilotClientOptions setPort(int port) {
         return this;
     }
 
+    /**
+     * Returns whether remote session support (Mission Control integration) is
+     * enabled.
+     * <p>
+     * When {@code true}, sessions in a GitHub repository working directory are
+     * accessible from GitHub web and mobile.
+     *
+     * @return {@code true} if remote sessions are enabled
+     */
+    public boolean isRemote() {
+        return remote;
+    }
+
+    /**
+     * Enables remote session support (Mission Control integration).
+     * <p>
+     * When {@code true}, sessions in a GitHub repository working directory are
+     * accessible from GitHub web and mobile.
+     * <p>
+     * This option is only used when the SDK spawns the CLI process; it is ignored
+     * when connecting to an external server via {@link #setCliUrl(String)}.
+     *
+     * @param remote
+     *            {@code true} to enable remote sessions
+     * @return this options instance for method chaining
+     */
+    public CopilotClientOptions setRemote(boolean remote) {
+        this.remote = remote;
+        return this;
+    }
+
     /**
      * Gets the OpenTelemetry configuration for the CLI server.
      *
@@ -599,6 +631,7 @@ public CopilotClientOptions clone() {
         copy.logLevel = this.logLevel;
         copy.onListModels = this.onListModels;
         copy.port = this.port;
+        copy.remote = this.remote;
         copy.sessionIdleTimeoutSeconds = this.sessionIdleTimeoutSeconds;
         copy.tcpConnectionToken = this.tcpConnectionToken;
         copy.telemetry = this.telemetry;

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

@@ -57,6 +57,18 @@ public class ProviderConfig {
     @JsonProperty("headers")
     private Map<String, String> headers;
 
+    @JsonProperty("modelId")
+    private String modelId;
+
+    @JsonProperty("wireModel")
+    private String wireModel;
+
+    @JsonProperty("maxPromptTokens")
+    private Integer maxPromptTokens;
+
+    @JsonProperty("maxOutputTokens")
+    private Integer maxOutputTokens;
+
     /**
      * Gets the provider type.
      *
@@ -225,4 +237,109 @@ public ProviderConfig setHeaders(Map<String, String> headers) {
         this.headers = headers;
         return this;
     }
+
+    /**
+     * Gets the well-known model name used by the runtime.
+     * <p>
+     * Used to look up agent configuration (tools, prompts, reasoning behavior) and
+     * default token limits. Also used as the wire model when
+     * {@link #getWireModel()} is not set.
+     *
+     * @return the model ID, or {@code null} if not set
+     */
+    public String getModelId() {
+        return modelId;
+    }
+
+    /**
+     * Sets the well-known model name used by the runtime.
+     * <p>
+     * Used to look up agent configuration (tools, prompts, reasoning behavior) and
+     * default token limits. Also used as the wire model when
+     * {@link #getWireModel()} is not set. Falls back to
+     * {@link SessionConfig#getModel()}.
+     *
+     * @param modelId
+     *            the model ID
+     * @return this config for method chaining
+     */
+    public ProviderConfig setModelId(String modelId) {
+        this.modelId = modelId;
+        return this;
+    }
+
+    /**
+     * Gets the model name sent to the provider API for inference.
+     *
+     * @return the wire model name, or {@code null} if not set
+     */
+    public String getWireModel() {
+        return wireModel;
+    }
+
+    /**
+     * Sets the model name sent to the provider API for inference.
+     * <p>
+     * Use this when the provider's model name (e.g. an Azure deployment name or a
+     * custom fine-tune name) differs from {@link #getModelId()}. Falls back to
+     * {@link #getModelId()}, then {@link SessionConfig#getModel()}.
+     *
+     * @param wireModel
+     *            the wire model name
+     * @return this config for method chaining
+     */
+    public ProviderConfig setWireModel(String wireModel) {
+        this.wireModel = wireModel;
+        return this;
+    }
+
+    /**
+     * Gets the maximum prompt token override.
+     *
+     * @return the max prompt tokens, or {@code null} if not set
+     */
+    public Integer getMaxPromptTokens() {
+        return maxPromptTokens;
+    }
+
+    /**
+     * Sets the maximum prompt tokens override.
+     * <p>
+     * Overrides the resolved model's default max prompt tokens. The runtime
+     * triggers conversation compaction before sending a request when the prompt
+     * (system message, history, tool definitions, user message) would exceed this
+     * limit.
+     *
+     * @param maxPromptTokens
+     *            the max prompt tokens
+     * @return this config for method chaining
+     */
+    public ProviderConfig setMaxPromptTokens(Integer maxPromptTokens) {
+        this.maxPromptTokens = maxPromptTokens;
+        return this;
+    }
+
+    /**
+     * Gets the maximum output token override.
+     *
+     * @return the max output tokens, or {@code null} if not set
+     */
+    public Integer getMaxOutputTokens() {
+        return maxOutputTokens;
+    }
+
+    /**
+     * Sets the maximum output tokens override.
+     * <p>
+     * Overrides the resolved model's default max output tokens. When hit, the model
+     * stops generating and returns a truncated response.
+     *
+     * @param maxOutputTokens
+     *            the max output tokens
+     * @return this config for method chaining
+     */
+    public ProviderConfig setMaxOutputTokens(Integer maxOutputTokens) {
+        this.maxOutputTokens = maxOutputTokens;
+        return this;
+    }
 }

src/site/markdown/advanced.md

@@ -383,6 +383,29 @@ var session = client.createSession(
 
 > **Note:** The `bearerToken` option accepts a **static token string** only. The SDK does not refresh this token automatically. If your token expires, requests will fail and you'll need to create a new session with a fresh token.
 
+### Model Overrides
+
+Use `modelId` and `wireModel` to control model resolution and the model name on the wire:
+
+```java
+var session = client.createSession(
+    new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+        .setProvider(new ProviderConfig()
+            .setType("openai")
+            .setBaseUrl("https://api.openai.com/v1")
+            .setApiKey("sk-...")
+            .setModelId("gpt-4o")           // Runtime config lookup
+            .setWireModel("my-finetune-v3") // Sent to the provider API
+            .setMaxPromptTokens(100_000)    // Override max prompt tokens
+            .setMaxOutputTokens(4096))      // Override max output tokens
+).get();
+```
+
+- **`modelId`** — Well-known model name used by the runtime to look up agent configuration (tools, prompts, reasoning behavior) and default token limits. Also used as the wire model when `wireModel` is not set.
+- **`wireModel`** — Model name sent to the provider API for inference. Use when the provider's model name (e.g., an Azure deployment name or a custom fine-tune name) differs from `modelId`.
+- **`maxPromptTokens`** — Overrides the resolved model's default max prompt tokens. The runtime triggers conversation compaction when the prompt would exceed this limit.
+- **`maxOutputTokens`** — Overrides the resolved model's default max output tokens.
+
 ### Microsoft Foundry Local
 
 [Microsoft Foundry Local](https://foundrylocal.ai) lets you run AI models locally on your own device with an OpenAI-compatible API. Install it via the Foundry Local CLI, then point the SDK at your local endpoint:
@@ -1262,6 +1285,39 @@ This is more efficient than `listSessions()` when you already know the session I
 
 ---
 
+## Remote Sessions
+
+Remote sessions enable Mission Control integration, making sessions accessible from GitHub web and mobile. When enabled, sessions in a GitHub repository working directory receive a remote URL.
+
+### Enabling Remote Sessions
+
+Set `remote(true)` on the client options to enable remote session support for all sessions:
+
+```java
+var options = new CopilotClientOptions()
+    .setRemote(true)
+    .setCwd("/path/to/github-repo");
+
+try (var client = new CopilotClient(options)) {
+    var session = client.createSession(
+        new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    // Listen for the remote URL info event
+    session.on(SessionInfoEvent.class, event -> {
+        System.out.println("Remote URL: " + event.getData());
+    });
+}
+```
+
+### Prerequisites
+
+- The user must be authenticated (GitHub token or logged-in user)
+- The session's working directory must be a GitHub repository
+- This option is only used when the SDK spawns the CLI process; it is ignored when connecting to an external server via `setCliUrl()`
+
+---
+
 ## Next Steps
 
 - 📖 **[Documentation](documentation.html)** - Core concepts, events, streaming, models, tool filtering, reasoning effort

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

@@ -56,10 +56,12 @@
 public class CapiProxy implements AutoCloseable {
 
     private static final ObjectMapper MAPPER = new ObjectMapper();
-    private static final Pattern LISTENING_PATTERN = Pattern.compile("Listening: (http://[^\\s]+)");
+    private static final Pattern LISTENING_PATTERN = Pattern.compile("Listening: (http://[^\\s]+)(?:\\s+(\\{.*\\}))?$");
 
     private Process process;
     private String proxyUrl;
+    private String connectProxyUrl;
+    private String caFilePath;
     private final HttpClient httpClient;
     private BufferedReader stdoutReader;
 
@@ -138,6 +140,21 @@ public String start() throws IOException, InterruptedException {
         }
 
         proxyUrl = matcher.group(1);
+
+        // Parse optional metadata (CONNECT proxy details)
+        String metadata = matcher.group(2);
+        if (metadata != null && !metadata.isEmpty()) {
+            try {
+                Map<String, String> meta = MAPPER.readValue(metadata, new TypeReference<Map<String, String>>() {
+                });
+                connectProxyUrl = meta.get("connectProxyUrl");
+                caFilePath = meta.get("caFilePath");
+            } catch (Exception e) {
+                process.destroyForcibly();
+                throw new IOException("Failed to parse proxy startup metadata: " + metadata, e);
+            }
+        }
+
         return proxyUrl;
     }
 
@@ -329,6 +346,8 @@ public void stop(boolean skipWritingCache) throws IOException, InterruptedExcept
 
         process = null;
         proxyUrl = null;
+        connectProxyUrl = null;
+        caFilePath = null;
     }
 
     /**
@@ -340,6 +359,24 @@ public String getProxyUrl() {
         return proxyUrl;
     }
 
+    /**
+     * Gets the CONNECT proxy URL for HTTPS interception.
+     *
+     * @return the CONNECT proxy URL, or null if not available
+     */
+    public String getConnectProxyUrl() {
+        return connectProxyUrl;
+    }
+
+    /**
+     * Gets the CA file path for trusting the CONNECT proxy's certificate.
+     *
+     * @return the CA file path, or null if not available
+     */
+    public String getCaFilePath() {
+        return caFilePath;
+    }
+
     /**
      * Checks if the proxy process is still alive and responsive. This does both a
      * process alive check AND an HTTP health check.