Enhance documentation: add exception isolation details for event handlers

Author: brunoborges

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

@@ -297,6 +297,10 @@ public CompletableFuture<AssistantMessageEvent> sendAndWait(MessageOptions optio
      * instead.
      *
      * <p>
+     * <b>Exception isolation:</b> If a handler throws an exception, the error is
+     * logged and remaining handlers still execute.
+     *
+     * <p>
      * <b>Example:</b>
      *
      * <pre>{@code
@@ -324,6 +328,10 @@ public Closeable on(Consumer<AbstractSessionEvent> handler) {
      * matching the specified type.
      *
      * <p>
+     * <b>Exception isolation:</b> If a handler throws an exception, the error is
+     * logged and remaining handlers still execute.
+     *
+     * <p>
      * <b>Example Usage</b>
      * </p>
      *
@@ -367,7 +375,10 @@ public <T extends AbstractSessionEvent> Closeable on(Class<T> eventType, Consume
     /**
      * Dispatches an event to all registered handlers.
      * <p>
-     * This is called internally when events are received from the server.
+     * This is called internally when events are received from the server. Each
+     * handler is invoked in its own try/catch block so that an exception thrown by
+     * one handler does not prevent subsequent handlers from executing. Exceptions
+     * are logged at {@link Level#SEVERE}.
      *
      * @param event
      *            the event to dispatch

src/site/markdown/advanced.md

@@ -419,3 +419,26 @@ session.send(new MessageOptions().setPrompt("Hello"))
         return null;
     });
 ```
+
+### Event Handler Exceptions
+
+If an event handler throws an exception, the SDK catches it, logs it at
+`SEVERE` level, and continues dispatching to remaining handlers. This means
+one faulty handler will never block others from receiving events:
+
+```java
+// This handler throws, but the second handler still runs
+session.on(AssistantMessageEvent.class, msg -> {
+    throw new RuntimeException("bug in handler 1");
+});
+
+session.on(AssistantMessageEvent.class, msg -> {
+    // This handler executes normally despite the exception above
+    System.out.println(msg.getData().getContent());
+});
+```
+
+> **Note:** This exception isolation behavior is consistent with the Node.js,
+> Go, and Python Copilot SDKs, which all catch handler errors per-handler. The
+> .NET SDK is an exception — handler errors propagate there and can prevent
+> subsequent handlers from running.

src/site/markdown/documentation.md

@@ -57,6 +57,10 @@ 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.
+
 ```java
 var done = new CompletableFuture<Void>();