fix: update Javadoc for Optional-based API and fix test assertions

- Update @return tags to describe Optional.empty()/OptionalInt.empty() instead of null
- Update @param tags to remove null references on primitive setters
- Fix exception message in CopilotSession to use valid Java syntax
- Fix ElicitationTest to use assertEquals(Boolean.TRUE, ...) to avoid NPE

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

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

@@ -1120,7 +1120,7 @@ private void assertElicitation() {
         SessionCapabilities caps = capabilities;
         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.");
         }
     }
 

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

@@ -503,7 +503,8 @@ public CopilotClientOptions setTelemetry(TelemetryConfig telemetry) {
      * Gets the server-wide idle timeout for sessions in seconds.
      *
      * @return an {@link OptionalInt} containing the session idle timeout in
-     *         seconds, or empty to disable (sessions live indefinitely)
+     *         seconds, or {@link java.util.OptionalInt#empty()} if not set. Use
+     *         {@link #clearSessionIdleTimeoutSeconds()} to revert to the default.
      * @since 1.3.0
      */
     @JsonIgnore

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

@@ -199,7 +199,8 @@ public CustomAgentConfig setMcpServers(Map<String, McpServerConfig> mcpServers)
     /**
      * Gets whether inference mode is enabled.
      *
-     * @return the infer flag, or {@code null} if not set
+     * @return an {@link java.util.Optional} containing the infer flag, or
+     *         {@link java.util.Optional#empty()} if not set
      */
     @JsonIgnore
     public Optional<Boolean> getInfer() {

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

@@ -49,7 +49,12 @@ public InputOptions setDescription(String description) {
         return this;
     }
 
-    /** Gets the minimum character length. @return the min length */
+    /**
+     * Gets the minimum character length.
+     *
+     * @return an {@link java.util.OptionalInt} containing the min length, or
+     *         {@link java.util.OptionalInt#empty()} if not set
+     */
     @JsonIgnore
     public OptionalInt getMinLength() {
         return minLength == null ? OptionalInt.empty() : OptionalInt.of(minLength);
@@ -74,7 +79,12 @@ public InputOptions clearMinLength() {
         return this;
     }
 
-    /** Gets the maximum character length. @return the max length */
+    /**
+     * Gets the maximum character length.
+     *
+     * @return an {@link java.util.OptionalInt} containing the max length, or
+     *         {@link java.util.OptionalInt#empty()} if not set
+     */
     @JsonIgnore
     public OptionalInt getMaxLength() {
         return maxLength == null ? OptionalInt.empty() : OptionalInt.of(maxLength);

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

@@ -109,20 +109,21 @@ public static class Supports {
         /**
          * Gets the vision override.
          *
-         * @return {@code true} to enable vision, {@code false} to disable, or
-         *         {@code null} to use the runtime default
+         * @return an {@link java.util.Optional} containing {@code true} to enable
+         *         vision or {@code false} to disable, or
+         *         {@link java.util.Optional#empty()} to use the runtime default
          */
         @JsonIgnore
         public Optional<Boolean> getVision() {
             return Optional.ofNullable(vision);
         }
 
         /**
-         * Sets whether vision (image input) is enabled.
+         * Sets whether vision (image input) is enabled. Use {@link #clearVision()} to
+         * revert to the runtime default.
          *
          * @param vision
-         *            {@code true} to enable, {@code false} to disable, or {@code null}
-         *            to use the runtime default
+         *            {@code true} to enable, {@code false} to disable
          * @return this instance for method chaining
          */
         public Supports setVision(boolean vision) {
@@ -143,20 +144,21 @@ public Supports clearVision() {
         /**
          * Gets the reasoning effort override.
          *
-         * @return {@code true} to enable reasoning effort, {@code false} to disable, or
-         *         {@code null} to use the runtime default
+         * @return an {@link java.util.Optional} containing {@code true} to enable
+         *         reasoning effort or {@code false} to disable, or
+         *         {@link java.util.Optional#empty()} to use the runtime default
          */
         @JsonIgnore
         public Optional<Boolean> getReasoningEffort() {
             return Optional.ofNullable(reasoningEffort);
         }
 
         /**
-         * Sets whether reasoning effort configuration is enabled.
+         * Sets whether reasoning effort configuration is enabled. Use
+         * {@link #clearReasoningEffort()} to revert to the runtime default.
          *
          * @param reasoningEffort
-         *            {@code true} to enable, {@code false} to disable, or {@code null}
-         *            to use the runtime default
+         *            {@code true} to enable, {@code false} to disable
          * @return this instance for method chaining
          */
         public Supports setReasoningEffort(boolean reasoningEffort) {

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

@@ -298,7 +298,8 @@ public ProviderConfig setWireModel(String wireModel) {
     /**
      * Gets the maximum prompt token override.
      *
-     * @return the max prompt tokens, or {@code null} if not set
+     * @return an {@link java.util.OptionalInt} containing the max prompt tokens, or
+     *         {@link java.util.OptionalInt#empty()} if not set
      */
     @JsonIgnore
     public OptionalInt getMaxPromptTokens() {
@@ -335,7 +336,8 @@ public ProviderConfig clearMaxPromptTokens() {
     /**
      * Gets the maximum output token override.
      *
-     * @return the max output tokens, or {@code null} if not set
+     * @return an {@link java.util.OptionalInt} containing the max output tokens, or
+     *         {@link java.util.OptionalInt#empty()} if not set
      */
     @JsonIgnore
     public OptionalInt getMaxOutputTokens() {

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

@@ -236,15 +236,16 @@ public ResumeSessionConfig setProvider(ProviderConfig provider) {
 
     /**
      * Enables or disables internal session telemetry for this session. When
-     * {@code false}, disables session telemetry. When {@code null} (the default) or
+     * {@code false}, disables session telemetry. When unset (the default) or
      * {@code true}, telemetry is enabled for GitHub-authenticated sessions. When a
      * custom {@link ProviderConfig} (BYOK) is configured, session telemetry is
      * always disabled regardless of this setting. This is independent of
      * {@link com.github.copilot.sdk.json.CopilotClientOptions#getTelemetry()
      * CopilotClientOptions.TelemetryConfig}, which configures OpenTelemetry export
      * for observability.
      *
-     * @return whether session telemetry is enabled
+     * @return an {@link java.util.Optional} containing whether session telemetry is
+     *         enabled, or {@link java.util.Optional#empty()} for the default
      */
     @JsonIgnore
     public Optional<Boolean> getEnableSessionTelemetry() {
@@ -253,7 +254,7 @@ public Optional<Boolean> getEnableSessionTelemetry() {
 
     /**
      * Enables or disables internal session telemetry for this session. When
-     * {@code false}, disables session telemetry. When {@code null} (the default) or
+     * {@code false}, disables session telemetry. When unset (the default) or
      * {@code true}, telemetry is enabled for GitHub-authenticated sessions. When a
      * custom {@link ProviderConfig} (BYOK) is configured, session telemetry is
      * always disabled regardless of this setting.

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

@@ -290,15 +290,16 @@ public SessionConfig setProvider(ProviderConfig provider) {
 
     /**
      * Enables or disables internal session telemetry for this session. When
-     * {@code false}, disables session telemetry. When {@code null} (the default) or
+     * {@code false}, disables session telemetry. When unset (the default) or
      * {@code true}, telemetry is enabled for GitHub-authenticated sessions. When a
      * custom {@link ProviderConfig} (BYOK) is configured, session telemetry is
      * always disabled regardless of this setting. This is independent of
      * {@link com.github.copilot.sdk.json.CopilotClientOptions#getTelemetry()
      * CopilotClientOptions.TelemetryConfig}, which configures OpenTelemetry export
      * for observability.
      *
-     * @return whether session telemetry is enabled
+     * @return an {@link java.util.Optional} containing whether session telemetry is
+     *         enabled, or {@link java.util.Optional#empty()} for the default
      */
     @JsonIgnore
     public Optional<Boolean> getEnableSessionTelemetry() {
@@ -307,7 +308,7 @@ public Optional<Boolean> getEnableSessionTelemetry() {
 
     /**
      * Enables or disables internal session telemetry for this session. When
-     * {@code false}, disables session telemetry. When {@code null} (the default) or
+     * {@code false}, disables session telemetry. When unset (the default) or
      * {@code true}, telemetry is enabled for GitHub-authenticated sessions. When a
      * custom {@link ProviderConfig} (BYOK) is configured, session telemetry is
      * always disabled regardless of this setting.
@@ -671,8 +672,9 @@ public SessionConfig setConfigDir(String configDir) {
     /**
      * Gets whether automatic configuration discovery is enabled.
      *
-     * @return {@code true} to enable discovery, {@code false} to disable, or
-     *         {@code null} to use the runtime default
+     * @return an {@link java.util.Optional} containing {@code true} to enable
+     *         discovery or {@code false} to disable, or
+     *         {@link java.util.Optional#empty()} to use the runtime default
      */
     @JsonIgnore
     public Optional<Boolean> getEnableConfigDiscovery() {
@@ -690,8 +692,7 @@ public Optional<Boolean> getEnableConfigDiscovery() {
      * name collision.
      *
      * @param enableConfigDiscovery
-     *            {@code true} to enable discovery, {@code false} to disable, or
-     *            {@code null} to use the runtime default
+     *            {@code true} to enable discovery, {@code false} to disable
      * @return this config instance for method chaining
      */
     public SessionConfig setEnableConfigDiscovery(boolean enableConfigDiscovery) {
@@ -712,8 +713,9 @@ public SessionConfig clearEnableConfigDiscovery() {
     /**
      * Gets whether sub-agent streaming events are included.
      *
-     * @return {@code true} to include sub-agent streaming events, {@code false} to
-     *         suppress them, or {@code null} to use the runtime default
+     * @return an {@link java.util.Optional} containing {@code true} to include
+     *         sub-agent streaming events or {@code false} to suppress them, or
+     *         {@link java.util.Optional#empty()} to use the runtime default
      */
     @JsonIgnore
     public Optional<Boolean> getIncludeSubAgentStreamingEvents() {

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

@@ -132,8 +132,9 @@ public TelemetryConfig setSourceName(String sourceName) {
      * Maps to the {@code OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT}
      * environment variable.
      *
-     * @return {@code true} to capture content, {@code false} to suppress it, or
-     *         {@code null} to use the default
+     * @return an {@link java.util.Optional} containing {@code true} to capture
+     *         content or {@code false} to suppress it, or
+     *         {@link java.util.Optional#empty()} to use the default
      */
     @JsonIgnore
     public Optional<Boolean> getCaptureContent() {

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

@@ -77,7 +77,8 @@ public UserInputRequest setChoices(List<String> choices) {
     /**
      * Returns whether freeform text input is allowed.
      *
-     * @return {@code true} if freeform input is allowed, {@code null} if not
+     * @return an {@link java.util.Optional} containing {@code true} if freeform
+     *         input is allowed, or {@link java.util.Optional#empty()} if not
      *         specified
      */
     @JsonIgnore

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

@@ -164,7 +164,7 @@ void buildCreateRequestSetsRequestElicitationWhenHandlerPresent() {
 
         var request = SessionRequestBuilder.buildCreateRequest(config);
 
-        assertTrue(request.getRequestElicitation());
+        assertEquals(Boolean.TRUE, request.getRequestElicitation());
     }
 
     @Test
@@ -186,6 +186,6 @@ void buildResumeRequestSetsRequestElicitationWhenHandlerPresent() {
 
         var request = SessionRequestBuilder.buildResumeRequest("session-1", config);
 
-        assertTrue(request.getRequestElicitation());
+        assertEquals(Boolean.TRUE, request.getRequestElicitation());
     }
 }