refactor: use Optional return types instead of nullable boxed primitives in public API

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

@@ -90,16 +90,16 @@ ProcessInfo startCliServer() throws IOException, InterruptedException {
         }
 
         // Default UseLoggedInUser to false when GitHubToken is provided
-        boolean useLoggedInUser = options.getUseLoggedInUser() != null
-                ? options.getUseLoggedInUser()
-                : (options.getGitHubToken() == null || options.getGitHubToken().isEmpty());
+        boolean useLoggedInUser = options.getUseLoggedInUser()
+                .orElse(options.getGitHubToken() == null || options.getGitHubToken().isEmpty());
         if (!useLoggedInUser) {
             args.add("--no-auto-login");
         }
 
-        if (options.getSessionIdleTimeoutSeconds() != null && options.getSessionIdleTimeoutSeconds() > 0) {
+        if (options.getSessionIdleTimeoutSeconds().isPresent()
+                && options.getSessionIdleTimeoutSeconds().getAsInt() > 0) {
             args.add("--session-idle-timeout");
-            args.add(String.valueOf(options.getSessionIdleTimeoutSeconds()));
+            args.add(String.valueOf(options.getSessionIdleTimeoutSeconds().getAsInt()));
         }
 
         if (options.isRemote()) {
@@ -159,9 +159,9 @@ ProcessInfo startCliServer() throws IOException, InterruptedException {
             if (telemetry.getSourceName() != null) {
                 pb.environment().put("COPILOT_OTEL_SOURCE_NAME", telemetry.getSourceName());
             }
-            if (telemetry.getCaptureContent() != null) {
+            if (telemetry.getCaptureContent().isPresent()) {
                 pb.environment().put("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT",
-                        telemetry.getCaptureContent() ? "true" : "false");
+                        telemetry.getCaptureContent().get() ? "true" : "false");
             }
         }
 

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

@@ -120,7 +120,7 @@ public CopilotClient(CopilotClientOptions options) {
 
         // Validate auth options with external server
         if (this.options.getCliUrl() != null && !this.options.getCliUrl().isEmpty()
-                && (this.options.getGitHubToken() != null || this.options.getUseLoggedInUser() != null)) {
+                && (this.options.getGitHubToken() != null || this.options.getUseLoggedInUser().isPresent())) {
             throw new IllegalArgumentException(
                     "GitHubToken and UseLoggedInUser cannot be used with CliUrl (external server manages its own auth)");
         }

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

@@ -1118,9 +1118,9 @@ private void handleElicitationRequestAsync(ElicitationContext context, String re
      */
     private void assertElicitation() {
         SessionCapabilities caps = capabilities;
-        if (caps == null || caps.getUi() == null || !Boolean.TRUE.equals(caps.getUi().getElicitation())) {
+        if (caps == null || caps.getUi() == null || !caps.getUi().getElicitation().orElse(false)) {
             throw new IllegalStateException("Elicitation is not supported by the host. "
-                    + "Check session.getCapabilities().getUi()?.getElicitation() before calling UI methods.");
+                    + "Check session.getCapabilities().getUi().getElicitation().orElse(false) before calling UI methods.");
         }
     }
 
@@ -1201,10 +1201,10 @@ public CompletableFuture<String> input(String message, InputOptions options) {
                     field.put("title", options.getTitle());
                 if (options.getDescription() != null)
                     field.put("description", options.getDescription());
-                if (options.getMinLength() != null)
-                    field.put("minLength", options.getMinLength());
-                if (options.getMaxLength() != null)
-                    field.put("maxLength", options.getMaxLength());
+                if (options.getMinLength().isPresent())
+                    field.put("minLength", options.getMinLength().getAsInt());
+                if (options.getMaxLength().isPresent())
+                    field.put("maxLength", options.getMaxLength().getAsInt());
                 if (options.getFormat() != null)
                     field.put("format", options.getFormat());
                 if (options.getDefaultValue() != null)
@@ -1695,7 +1695,8 @@ public CompletableFuture<Void> setModel(String model, String reasoningEffort,
             ModelCapabilitiesOverrideSupports supports = null;
             if (modelCapabilities.getSupports() != null) {
                 var s = modelCapabilities.getSupports();
-                supports = new ModelCapabilitiesOverrideSupports(s.getVision(), s.getReasoningEffort());
+                supports = new ModelCapabilitiesOverrideSupports(s.getVision().orElse(null),
+                        s.getReasoningEffort().orElse(null));
             }
             ModelCapabilitiesOverrideLimits limits = null;
             if (modelCapabilities.getLimits() != null) {

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

@@ -111,12 +111,18 @@ static CreateSessionRequest buildCreateRequest(SessionConfig config, String sess
         request.setAvailableTools(config.getAvailableTools());
         request.setExcludedTools(config.getExcludedTools());
         request.setProvider(config.getProvider());
-        request.setEnableSessionTelemetry(config.getEnableSessionTelemetry());
-        request.setRequestUserInput(config.getOnUserInputRequest() != null ? true : null);
-        request.setHooks(config.getHooks() != null && config.getHooks().hasHooks() ? true : null);
+        config.getEnableSessionTelemetry().ifPresent(request::setEnableSessionTelemetry);
+        if (config.getOnUserInputRequest() != null) {
+            request.setRequestUserInput(true);
+        }
+        if (config.getHooks() != null && config.getHooks().hasHooks()) {
+            request.setHooks(true);
+        }
         request.setWorkingDirectory(config.getWorkingDirectory());
-        request.setStreaming(config.isStreaming() ? true : null);
-        request.setIncludeSubAgentStreamingEvents(config.getIncludeSubAgentStreamingEvents());
+        if (config.isStreaming()) {
+            request.setStreaming(true);
+        }
+        config.getIncludeSubAgentStreamingEvents().ifPresent(request::setIncludeSubAgentStreamingEvents);
         request.setMcpServers(config.getMcpServers());
         request.setCustomAgents(config.getCustomAgents());
         request.setDefaultAgent(config.getDefaultAgent());
@@ -126,7 +132,7 @@ static CreateSessionRequest buildCreateRequest(SessionConfig config, String sess
         request.setInstructionDirectories(config.getInstructionDirectories());
         request.setDisabledSkills(config.getDisabledSkills());
         request.setConfigDir(config.getConfigDir());
-        request.setEnableConfigDiscovery(config.getEnableConfigDiscovery());
+        config.getEnableConfigDiscovery().ifPresent(request::setEnableConfigDiscovery);
         request.setModelCapabilities(config.getModelCapabilities());
 
         if (config.getCommands() != null && !config.getCommands().isEmpty()) {
@@ -194,15 +200,23 @@ static ResumeSessionRequest buildResumeRequest(String sessionId, ResumeSessionCo
         request.setAvailableTools(config.getAvailableTools());
         request.setExcludedTools(config.getExcludedTools());
         request.setProvider(config.getProvider());
-        request.setEnableSessionTelemetry(config.getEnableSessionTelemetry());
-        request.setRequestUserInput(config.getOnUserInputRequest() != null ? true : null);
-        request.setHooks(config.getHooks() != null && config.getHooks().hasHooks() ? true : null);
+        config.getEnableSessionTelemetry().ifPresent(request::setEnableSessionTelemetry);
+        if (config.getOnUserInputRequest() != null) {
+            request.setRequestUserInput(true);
+        }
+        if (config.getHooks() != null && config.getHooks().hasHooks()) {
+            request.setHooks(true);
+        }
         request.setWorkingDirectory(config.getWorkingDirectory());
         request.setConfigDir(config.getConfigDir());
-        request.setEnableConfigDiscovery(config.getEnableConfigDiscovery());
-        request.setDisableResume(config.isDisableResume() ? true : null);
-        request.setStreaming(config.isStreaming() ? true : null);
-        request.setIncludeSubAgentStreamingEvents(config.getIncludeSubAgentStreamingEvents());
+        config.getEnableConfigDiscovery().ifPresent(request::setEnableConfigDiscovery);
+        if (config.isDisableResume()) {
+            request.setDisableResume(true);
+        }
+        if (config.isStreaming()) {
+            request.setStreaming(true);
+        }
+        config.getIncludeSubAgentStreamingEvents().ifPresent(request::setIncludeSubAgentStreamingEvents);
         request.setMcpServers(config.getMcpServers());
         request.setCustomAgents(config.getCustomAgents());
         request.setDefaultAgent(config.getDefaultAgent());

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

@@ -14,6 +14,9 @@
 import java.util.function.Supplier;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import java.util.Optional;
+import java.util.OptionalInt;
 
 /**
  * Configuration options for creating a
@@ -499,34 +502,47 @@ public CopilotClientOptions setTelemetry(TelemetryConfig telemetry) {
     /**
      * Gets the server-wide idle timeout for sessions in seconds.
      *
-     * @return the session idle timeout in seconds, or {@code null} to disable
-     *         (sessions live indefinitely)
+     * @return an {@link OptionalInt} containing the session idle timeout in
+     *         seconds, or {@link java.util.OptionalInt#empty()} if not set. Use
+     *         {@link #clearSessionIdleTimeoutSeconds()} to revert to the default.
      * @since 1.3.0
      */
-    public Integer getSessionIdleTimeoutSeconds() {
-        return sessionIdleTimeoutSeconds;
+    @JsonIgnore
+    public OptionalInt getSessionIdleTimeoutSeconds() {
+        return sessionIdleTimeoutSeconds == null ? OptionalInt.empty() : OptionalInt.of(sessionIdleTimeoutSeconds);
     }
 
     /**
      * Sets the server-wide idle timeout for sessions in seconds.
      * <p>
      * Sessions without activity for this duration are automatically cleaned up. Set
-     * to {@code 0} or leave as {@code null} to disable (sessions live
-     * indefinitely).
+     * to {@code 0} to disable (sessions live indefinitely). Use
+     * {@link #clearSessionIdleTimeoutSeconds()} to revert to the default.
      * <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 sessionIdleTimeoutSeconds
-     *            the idle timeout in seconds, or {@code null} to disable
+     *            the idle timeout in seconds
      * @return this options instance for method chaining
      * @since 1.3.0
      */
-    public CopilotClientOptions setSessionIdleTimeoutSeconds(Integer sessionIdleTimeoutSeconds) {
+    public CopilotClientOptions setSessionIdleTimeoutSeconds(int sessionIdleTimeoutSeconds) {
         this.sessionIdleTimeoutSeconds = sessionIdleTimeoutSeconds;
         return this;
     }
 
+    /**
+     * Clears the sessionIdleTimeoutSeconds setting, reverting to the default
+     * behavior.
+     *
+     * @return this instance for method chaining
+     */
+    public CopilotClientOptions clearSessionIdleTimeoutSeconds() {
+        this.sessionIdleTimeoutSeconds = null;
+        return this;
+    }
+
     /**
      * Gets the connection token for the headless CLI server (TCP only).
      *
@@ -555,11 +571,11 @@ public CopilotClientOptions setTcpConnectionToken(String tcpConnectionToken) {
     /**
      * Returns whether to use the logged-in user for authentication.
      *
-     * @return {@code true} to use logged-in user auth, {@code false} to use only
-     *         explicit tokens, or {@code null} to use default behavior
+     * @return an {@link Optional} containing the boolean value, or empty if not set
      */
-    public Boolean getUseLoggedInUser() {
-        return useLoggedInUser;
+    @JsonIgnore
+    public Optional<Boolean> getUseLoggedInUser() {
+        return Optional.ofNullable(useLoggedInUser);
     }
 
     /**
@@ -569,15 +585,23 @@ public Boolean getUseLoggedInUser() {
      * auth. When false, only explicit tokens (gitHubToken or environment variables)
      * are used. Default: true (but defaults to false when gitHubToken is provided).
      * <p>
-     * Passing {@code null} is equivalent to passing {@link Boolean#FALSE}.
      *
      * @param useLoggedInUser
-     *            {@code true} to use logged-in user auth, {@code false} or
-     *            {@code null} otherwise
+     *            {@code true} to use logged-in user auth, {@code false} otherwise
      * @return this options instance for method chaining
      */
-    public CopilotClientOptions setUseLoggedInUser(Boolean useLoggedInUser) {
-        this.useLoggedInUser = useLoggedInUser != null ? useLoggedInUser : Boolean.FALSE;
+    public CopilotClientOptions setUseLoggedInUser(boolean useLoggedInUser) {
+        this.useLoggedInUser = useLoggedInUser;
+        return this;
+    }
+
+    /**
+     * Clears the useLoggedInUser setting, reverting to the default behavior.
+     *
+     * @return this instance for method chaining
+     */
+    public CopilotClientOptions clearUseLoggedInUser() {
+        this.useLoggedInUser = null;
         return this;
     }