Merge reference implementation SDK changes (2026-05-04)

.lastmerge

@@ -1 +1 @@
-e42b726ca42bd1b2e099a956c9287ba9435ba3e5
+c063458ecc3d606766f04cf203b11b08de672cc8

pom.xml

@@ -94,7 +94,7 @@
             reference-impl-sync workflow and deal with the subsequent
             PR.
         -->
-        <readonly-copilot-sdk-ref-impl-version-from-lastmerge-file-updated-by-reference-impl-sync>^1.0.40-0</readonly-copilot-sdk-ref-impl-version-from-lastmerge-file-updated-by-reference-impl-sync>
+        <readonly-copilot-sdk-ref-impl-version-from-lastmerge-file-updated-by-reference-impl-sync>^1.0.41-0</readonly-copilot-sdk-ref-impl-version-from-lastmerge-file-updated-by-reference-impl-sync>
 
     </properties>
 

scripts/codegen/package.json

@@ -7,7 +7,7 @@
     "generate:java": "tsx java.ts"
   },
   "dependencies": {
-    "@github/copilot": "^1.0.40-0",
+    "@github/copilot": "^1.0.41-0",
     "json-schema": "^0.4.0",
     "tsx": "^4.20.6"
   }

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

@@ -115,6 +115,19 @@ ProcessInfo startCliServer() throws IOException, InterruptedException {
             pb.environment().put("COPILOT_SDK_AUTH_TOKEN", options.getGitHubToken());
         }
 
+        // Set COPILOT_HOME if configured
+        if (options.getCopilotHome() != null && !options.getCopilotHome().isEmpty()) {
+            pb.environment().put("COPILOT_HOME", options.getCopilotHome());
+        }
+
+        // Set connection token for TCP mode
+        if (options.getTcpConnectionToken() != null && !options.getTcpConnectionToken().isEmpty()) {
+            pb.environment().put("COPILOT_CONNECTION_TOKEN", options.getTcpConnectionToken());
+        } else if (!options.isUseStdio() && (options.getCliUrl() == null || options.getCliUrl().isEmpty())) {
+            // Auto-generate connection token for SDK-spawned TCP mode
+            pb.environment().put("COPILOT_CONNECTION_TOKEN", java.util.UUID.randomUUID().toString());
+        }
+
         // Set telemetry environment variables if configured
         if (options.getTelemetry() != null) {
             var telemetry = options.getTelemetry();

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

@@ -104,7 +104,8 @@ public CopilotClient() {
     public CopilotClient(CopilotClientOptions options) {
         this.options = options != null ? options : new CopilotClientOptions();
 
-        // When cliUrl is set, auto-correct useStdio since we're connecting via TCP
+        // When cliUrl is set, force TCP mode (we connect to an external server, not
+        // spawn one)
         if (this.options.getCliUrl() != null && !this.options.getCliUrl().isEmpty()) {
             this.options.setUseStdio(false);
         }
@@ -115,6 +116,16 @@ public CopilotClient(CopilotClientOptions options) {
             throw new IllegalArgumentException("CliUrl is mutually exclusive with CliPath");
         }
 
+        // Validate TcpConnectionToken
+        if (this.options.getTcpConnectionToken() != null) {
+            if (this.options.getTcpConnectionToken().isEmpty()) {
+                throw new IllegalArgumentException("TcpConnectionToken must be a non-empty string");
+            }
+            if (this.options.isUseStdio()) {
+                throw new IllegalArgumentException("TcpConnectionToken cannot be used with UseStdio = true");
+            }
+        }
+
         // Validate auth options with external server
         if (this.options.getCliUrl() != null && !this.options.getCliUrl().isEmpty()
                 && (this.options.getGitHubToken() != null || this.options.getUseLoggedInUser() != null)) {

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

@@ -122,6 +122,7 @@ static CreateSessionRequest buildCreateRequest(SessionConfig config, String sess
         request.setAgent(config.getAgent());
         request.setInfiniteSessions(config.getInfiniteSessions());
         request.setSkillDirectories(config.getSkillDirectories());
+        request.setInstructionDirectories(config.getInstructionDirectories());
         request.setDisabledSkills(config.getDisabledSkills());
         request.setConfigDir(config.getConfigDir());
         request.setEnableConfigDiscovery(config.getEnableConfigDiscovery());
@@ -192,13 +193,15 @@ static ResumeSessionRequest buildResumeRequest(String sessionId, ResumeSessionCo
         request.setConfigDir(config.getConfigDir());
         request.setEnableConfigDiscovery(config.getEnableConfigDiscovery());
         request.setDisableResume(config.isDisableResume() ? true : null);
+        request.setContinuePendingWork(config.getContinuePendingWork());
         request.setStreaming(config.isStreaming() ? true : null);
         request.setIncludeSubAgentStreamingEvents(config.getIncludeSubAgentStreamingEvents());
         request.setMcpServers(config.getMcpServers());
         request.setCustomAgents(config.getCustomAgents());
         request.setDefaultAgent(config.getDefaultAgent());
         request.setAgent(config.getAgent());
         request.setSkillDirectories(config.getSkillDirectories());
+        request.setInstructionDirectories(config.getInstructionDirectories());
         request.setDisabledSkills(config.getDisabledSkills());
         request.setInfiniteSessions(config.getInfiniteSessions());
         request.setModelCapabilities(config.getModelCapabilities());

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

@@ -44,13 +44,15 @@ public class CopilotClientOptions {
     private String[] cliArgs;
     private String cliPath;
     private String cliUrl;
+    private String copilotHome;
     private String cwd;
     private Map<String, String> environment;
     private Executor executor;
     private String gitHubToken;
     private String logLevel = "info";
     private Supplier<CompletableFuture<List<ModelInfo>>> onListModels;
     private int port;
+    private String tcpConnectionToken;
     private TelemetryConfig telemetry;
     private Integer sessionIdleTimeoutSeconds;
     private Boolean useLoggedInUser;
@@ -214,6 +216,36 @@ public CopilotClientOptions setCwd(String cwd) {
         return this;
     }
 
+    /**
+     * Gets the base directory for Copilot data (session state, config, etc.).
+     *
+     * @return the Copilot home directory path, or {@code null} to use the CLI
+     *         default ({@code ~/.copilot})
+     * @since 1.4.0
+     */
+    public String getCopilotHome() {
+        return copilotHome;
+    }
+
+    /**
+     * Sets the base directory for Copilot data (session state, config, etc.).
+     * <p>
+     * Sets the {@code COPILOT_HOME} environment variable on the spawned CLI
+     * process. When {@code null}, the CLI defaults to {@code ~/.copilot}.
+     * <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 copilotHome
+     *            the Copilot home directory path (must not be {@code null})
+     * @return this options instance for method chaining
+     * @since 1.4.0
+     */
+    public CopilotClientOptions setCopilotHome(String copilotHome) {
+        this.copilotHome = Objects.requireNonNull(copilotHome, "copilotHome must not be null");
+        return this;
+    }
+
     /**
      * Gets the environment variables for the CLI process.
      * <p>
@@ -405,6 +437,33 @@ public CopilotClientOptions setPort(int port) {
         return this;
     }
 
+    /**
+     * Gets the connection token for the headless CLI server (TCP only).
+     *
+     * @return the connection token, or {@code null} if not set
+     * @since 1.4.0
+     */
+    public String getTcpConnectionToken() {
+        return tcpConnectionToken;
+    }
+
+    /**
+     * Sets the connection token for the headless CLI server (TCP only).
+     * <p>
+     * When the SDK spawns its own CLI in TCP mode and this is omitted, a UUID is
+     * generated automatically so the loopback listener is safe by default. Cannot
+     * be combined with {@link #setUseStdio(boolean)} set to {@code true}.
+     *
+     * @param tcpConnectionToken
+     *            the connection token (must not be {@code null} or empty)
+     * @return this options instance for method chaining
+     * @since 1.4.0
+     */
+    public CopilotClientOptions setTcpConnectionToken(String tcpConnectionToken) {
+        this.tcpConnectionToken = Objects.requireNonNull(tcpConnectionToken, "tcpConnectionToken must not be null");
+        return this;
+    }
+
     /**
      * Gets the OpenTelemetry configuration for the CLI server.
      *
@@ -533,6 +592,7 @@ public CopilotClientOptions clone() {
         copy.cliArgs = this.cliArgs != null ? this.cliArgs.clone() : null;
         copy.cliPath = this.cliPath;
         copy.cliUrl = this.cliUrl;
+        copy.copilotHome = this.copilotHome;
         copy.cwd = this.cwd;
         copy.environment = this.environment != null ? new java.util.HashMap<>(this.environment) : null;
         copy.executor = this.executor;
@@ -541,6 +601,7 @@ public CopilotClientOptions clone() {
         copy.onListModels = this.onListModels;
         copy.port = this.port;
         copy.sessionIdleTimeoutSeconds = this.sessionIdleTimeoutSeconds;
+        copy.tcpConnectionToken = this.tcpConnectionToken;
         copy.telemetry = this.telemetry;
         copy.useLoggedInUser = this.useLoggedInUser;
         copy.useStdio = this.useStdio;

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

@@ -91,6 +91,9 @@ public final class CreateSessionRequest {
     @JsonProperty("skillDirectories")
     private List<String> skillDirectories;
 
+    @JsonProperty("instructionDirectories")
+    private List<String> instructionDirectories;
+
     @JsonProperty("disabledSkills")
     private List<String> disabledSkills;
 
@@ -326,6 +329,18 @@ public void setSkillDirectories(List<String> skillDirectories) {
         this.skillDirectories = skillDirectories;
     }
 
+    /** Gets instruction directories. @return the instruction directory paths */
+    public List<String> getInstructionDirectories() {
+        return instructionDirectories == null ? null : Collections.unmodifiableList(instructionDirectories);
+    }
+
+    /**
+     * Sets instruction directories. @param instructionDirectories the directories
+     */
+    public void setInstructionDirectories(List<String> instructionDirectories) {
+        this.instructionDirectories = instructionDirectories;
+    }
+
     /** Gets disabled skills. @return the disabled skill names */
     public List<String> getDisabledSkills() {
         return disabledSkills == null ? null : Collections.unmodifiableList(disabledSkills);