feat: add AUTOCLOSEABLE_TIMEOUT_SECONDS constant and enhance documentation for graceful shutdown and event handling troubleshooting

Author: brunoborges

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

@@ -61,6 +61,11 @@ public final class CopilotClient implements AutoCloseable {
 
     private static final Logger LOG = Logger.getLogger(CopilotClient.class.getName());
 
+    /**
+     * Timeout, in seconds, used by {@link #close()} when waiting for graceful
+     * shutdown via {@link #stop()}.
+     */
+    public static final int AUTOCLOSEABLE_TIMEOUT_SECONDS = 10;
     private final CopilotClientOptions options;
     private final CliServerManager serverManager;
     private final LifecycleEventManager lifecycleManager = new LifecycleEventManager();
@@ -221,6 +226,7 @@ public CompletableFuture<Void> stop() {
      * @return A future that completes when the client is stopped
      */
     public CompletableFuture<Void> forceStop() {
+        disposed = true;
         sessions.clear();
         return cleanupConnection();
     }
@@ -554,13 +560,27 @@ private CompletableFuture<Connection> ensureConnected() {
         return connectionFuture;
     }
 
+    /**
+     * Closes this client using graceful shutdown semantics.
+     * <p>
+     * This method is intended for {@code try-with-resources} usage and blocks while
+     * waiting for {@link #stop()} to complete, up to
+     * {@link #AUTOCLOSEABLE_TIMEOUT_SECONDS} seconds. If shutdown fails or times
+     * out, the error is logged at {@link Level#FINE} and the method returns.
+     * <p>
+     * This method is idempotent.
+     *
+     * @see #stop()
+     * @see #forceStop()
+     * @see #AUTOCLOSEABLE_TIMEOUT_SECONDS
+     */
     @Override
     public void close() {
         if (disposed)
             return;
         disposed = true;
         try {
-            forceStop().get(5, TimeUnit.SECONDS);
+            stop().get(AUTOCLOSEABLE_TIMEOUT_SECONDS, TimeUnit.SECONDS);
         } catch (Exception e) {
             LOG.log(Level.FINE, "Error during close", e);
         }

src/site/markdown/advanced.md

@@ -495,7 +495,8 @@ Use `forceStop()` when you need to terminate immediately, such as during error r
 client.forceStop().get();
 ```
 
-> **Tip:** In `try-with-resources` blocks, `close()` delegates to `stop()`, so graceful cleanup happens automatically.
+> **Tip:** In `try-with-resources` blocks, `close()` delegates to `stop()`, so graceful session cleanup happens automatically.
+> `close()` is blocking and waits up to `CopilotClient.AUTOCLOSEABLE_TIMEOUT_SECONDS` seconds for shutdown to complete.
 
 ---
 

src/site/markdown/documentation.md

@@ -8,6 +8,7 @@ This guide covers common use cases for the Copilot SDK for Java. For complete AP
 
 - [Basic Usage](#Basic_Usage)
 - [Handling Responses](#Handling_Responses)
+- [Troubleshooting Event Handling](#Troubleshooting_Event_Handling)
 - [Event Types Reference](#Event_Types_Reference)
 - [Streaming Responses](#Streaming_Responses)
 - [Session Operations](#Session_Operations)
@@ -64,11 +65,38 @@ System.out.println(response.getData().getContent());
 For more control, subscribe to events and use `send()`:
 
 > **Exception isolation:** If a handler throws an exception, the SDK logs the
-> error and continues dispatching to remaining handlers. One misbehaving handler
-> will never prevent others from executing. You can customize error handling with
-> `session.setEventErrorHandler()` — see the
+> error. By default, dispatch stops after the first handler error
+> (`PROPAGATE_AND_LOG_ERRORS`). To continue dispatching to remaining handlers,
+> set `EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS`. You can customize error
+> handling with `session.setEventErrorHandler()` — see the
 > [Advanced Usage](advanced.html#Custom_Event_Error_Handler) guide.
 
+## Troubleshooting Event Handling
+
+### Symptoms of policy misconfiguration
+
+- You registered multiple `session.on(...)` handlers, but only the first one runs
+- A handler throws once and later handlers stop receiving events
+- You expected "best effort" fan-out, but dispatch halts on errors
+
+### Fix
+
+Set the event error policy to suppress-and-continue:
+
+```java
+session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS);
+```
+
+Optionally add a custom error handler for observability:
+
+```java
+session.setEventErrorHandler((event, exception) -> {
+    System.err.println("Handler failed for event " + event.getType() + ": " + exception.getMessage());
+});
+```
+
+Use `PROPAGATE_AND_LOG_ERRORS` when you want fail-fast behavior.
+
 ```java
 var done = new CompletableFuture<Void>();