Add EventErrorHandler for custom event handler error handling

Introduce a session-level EventErrorHandler functional interface that lets
developers react to event handler exceptions programmatically instead of
relying on the default SEVERE logging.

- Add EventErrorHandler @FunctionalInterface in com.github.copilot.sdk
- Add setEventErrorHandler() method on CopilotSession
- Update dispatchEvent() to delegate to custom handler when set
- Add 6 JUnit tests covering custom handler, null reset, error handler
  throwing, and event type verification
- Update advanced.md and documentation.md with usage examples

Author: brunoborges

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

@@ -95,6 +95,7 @@ public final class CopilotSession implements AutoCloseable {
     private final AtomicReference<PermissionHandler> permissionHandler = new AtomicReference<>();
     private final AtomicReference<UserInputHandler> userInputHandler = new AtomicReference<>();
     private final AtomicReference<SessionHooks> hooksHandler = new AtomicReference<>();
+    private volatile EventErrorHandler eventErrorHandler;
 
     /**
      * Creates a new session with the given ID and RPC client.
@@ -152,6 +153,38 @@ public String getWorkspacePath() {
         return workspacePath;
     }
 
+    /**
+     * Sets a custom error handler for exceptions thrown by event handlers.
+     * <p>
+     * When an event handler registered via {@link #on(Consumer)} or
+     * {@link #on(Class, Consumer)} throws an exception during event dispatch, the
+     * error handler is invoked instead of the default behavior (logging at
+     * {@link Level#SEVERE}).
+     *
+     * <p>
+     * If the error handler itself throws an exception, that exception is silently
+     * caught and logged to prevent cascading failures.
+     *
+     * <p>
+     * <b>Example:</b>
+     *
+     * <pre>{@code
+     * session.setEventErrorHandler((event, exception) -> {
+     * 	metrics.increment("handler.errors");
+     * 	logger.error("Handler failed on {}: {}", event.getType(), exception.getMessage());
+     * });
+     * }</pre>
+     *
+     * @param handler
+     *            the error handler, or {@code null} to restore default logging
+     *            behavior
+     * @see EventErrorHandler
+     * @since 1.0.8
+     */
+    public void setEventErrorHandler(EventErrorHandler handler) {
+        this.eventErrorHandler = handler;
+    }
+
     /**
      * Sends a simple text message to the Copilot session.
      * <p>
@@ -377,18 +410,31 @@ public <T extends AbstractSessionEvent> Closeable on(Class<T> eventType, Consume
      * <p>
      * 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}.
+     * one handler does not prevent subsequent handlers from executing.
+     * <p>
+     * If a custom {@link EventErrorHandler} has been set via
+     * {@link #setEventErrorHandler(EventErrorHandler)}, it is called with the event
+     * and exception. Otherwise, exceptions are logged at {@link Level#SEVERE}.
      *
      * @param event
      *            the event to dispatch
+     * @see #setEventErrorHandler(EventErrorHandler)
      */
     void dispatchEvent(AbstractSessionEvent event) {
         for (Consumer<AbstractSessionEvent> handler : eventHandlers) {
             try {
                 handler.accept(event);
             } catch (Exception e) {
-                LOG.log(Level.SEVERE, "Error in event handler", e);
+                EventErrorHandler errorHandler = this.eventErrorHandler;
+                if (errorHandler != null) {
+                    try {
+                        errorHandler.handleError(event, e);
+                    } catch (Exception errorHandlerException) {
+                        LOG.log(Level.SEVERE, "Error in event error handler", errorHandlerException);
+                    }
+                } else {
+                    LOG.log(Level.SEVERE, "Error in event handler", e);
+                }
             }
         }
     }

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

@@ -0,0 +1,49 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.sdk;
+
+import com.github.copilot.sdk.events.AbstractSessionEvent;
+
+/**
+ * A handler for errors thrown by event handlers during event dispatch.
+ * <p>
+ * When an event handler registered via
+ * {@link CopilotSession#on(java.util.function.Consumer)} or
+ * {@link CopilotSession#on(Class, java.util.function.Consumer)} throws an
+ * exception, the {@code EventErrorHandler} is invoked with the event that was
+ * being dispatched and the exception that was thrown.
+ *
+ * <p>
+ * The default behavior logs errors at {@link java.util.logging.Level#SEVERE}.
+ * You can override this to integrate with your own logging, metrics, or
+ * error-reporting systems:
+ *
+ * <pre>{@code
+ * session.setEventErrorHandler((event, exception) -> {
+ * 	metrics.increment("handler.errors");
+ * 	logger.error("Handler failed on {}: {}", event.getType(), exception.getMessage());
+ * });
+ * }</pre>
+ *
+ * <p>
+ * If the error handler itself throws an exception, that exception is silently
+ * caught and logged to prevent cascading failures.
+ *
+ * @see CopilotSession#setEventErrorHandler(EventErrorHandler)
+ * @since 1.0.8
+ */
+@FunctionalInterface
+public interface EventErrorHandler {
+
+    /**
+     * Called when an event handler throws an exception during event dispatch.
+     *
+     * @param event
+     *            the event that was being dispatched when the error occurred
+     * @param exception
+     *            the exception thrown by the event handler
+     */
+    void handleError(AbstractSessionEvent event, Exception exception);
+}

src/site/markdown/advanced.md

@@ -442,3 +442,28 @@ session.on(AssistantMessageEvent.class, msg -> {
 > 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.
+
+### Custom Event Error Handler
+
+By default, handler exceptions are logged at `SEVERE` level using
+`java.util.logging`. You can replace this with a custom
+`EventErrorHandler` to integrate with your own logging, metrics, or
+error-reporting systems:
+
+```java
+session.setEventErrorHandler((event, exception) -> {
+    metrics.increment("handler.errors");
+    logger.error("Handler failed on {}: {}",
+        event.getType(), exception.getMessage());
+});
+```
+
+The error handler receives both the event that was being dispatched and the
+exception that was thrown. If the error handler itself throws, that exception
+is silently caught and logged to prevent cascading failures.
+
+Pass `null` to restore the default logging behavior:
+
+```java
+session.setEventErrorHandler(null);
+```

src/site/markdown/documentation.md

@@ -59,7 +59,9 @@ 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.
+> will never prevent others from executing. You can customize error handling with
+> `session.setEventErrorHandler()` — see the
+> [Advanced Usage](advanced.html#Custom_Event_Error_Handler) guide.
 
 ```java
 var done = new CompletableFuture<Void>();

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

@@ -376,6 +376,165 @@ void testConcurrentDispatchFromMultipleThreads() throws Exception {
     }
 
     // Helper methods to dispatch events using reflection
+    // ====================================================================
+    // EventErrorHandler tests
+    // ====================================================================
+
+    @Test
+    void testDefaultErrorHandlerLogsException() {
+        // Without a custom error handler, exceptions should be logged (no crash)
+        Logger sessionLogger = Logger.getLogger(CopilotSession.class.getName());
+        Level originalLevel = sessionLogger.getLevel();
+        sessionLogger.setLevel(Level.OFF);
+
+        try {
+            session.on(AssistantMessageEvent.class, msg -> {
+                throw new RuntimeException("boom");
+            });
+
+            assertDoesNotThrow(() -> dispatchEvent(createAssistantMessageEvent("Test")));
+        } finally {
+            sessionLogger.setLevel(originalLevel);
+        }
+    }
+
+    @Test
+    void testCustomEventErrorHandlerReceivesEventAndException() {
+        var capturedEvents = new ArrayList<AbstractSessionEvent>();
+        var capturedExceptions = new ArrayList<Exception>();
+
+        session.setEventErrorHandler((event, exception) -> {
+            capturedEvents.add(event);
+            capturedExceptions.add(exception);
+        });
+
+        var thrownException = new RuntimeException("test error");
+        session.on(AssistantMessageEvent.class, msg -> {
+            throw thrownException;
+        });
+
+        var event = createAssistantMessageEvent("Hello");
+        dispatchEvent(event);
+
+        assertEquals(1, capturedEvents.size());
+        assertSame(event, capturedEvents.get(0));
+        assertEquals(1, capturedExceptions.size());
+        assertSame(thrownException, capturedExceptions.get(0));
+    }
+
+    @Test
+    void testCustomErrorHandlerReplacesDefaultLogging() {
+        var errorCount = new AtomicInteger(0);
+
+        session.setEventErrorHandler((event, exception) -> {
+            errorCount.incrementAndGet();
+        });
+
+        session.on(AssistantMessageEvent.class, msg -> {
+            throw new RuntimeException("error 1");
+        });
+        session.on(AssistantMessageEvent.class, msg -> {
+            throw new RuntimeException("error 2");
+        });
+
+        dispatchEvent(createAssistantMessageEvent("Test"));
+
+        // Both handler errors should be reported to the custom error handler
+        assertEquals(2, errorCount.get());
+    }
+
+    @Test
+    void testErrorHandlerItselfThrowingDoesNotBreakDispatch() {
+        var received = new ArrayList<String>();
+
+        Logger sessionLogger = Logger.getLogger(CopilotSession.class.getName());
+        Level originalLevel = sessionLogger.getLevel();
+        sessionLogger.setLevel(Level.OFF);
+
+        try {
+            session.setEventErrorHandler((event, exception) -> {
+                throw new RuntimeException("error handler also broke");
+            });
+
+            // First handler throws
+            session.on(AssistantMessageEvent.class, msg -> {
+                throw new RuntimeException("handler error");
+            });
+
+            // Second handler should still execute
+            session.on(AssistantMessageEvent.class, msg -> {
+                received.add(msg.getData().getContent());
+            });
+
+            assertDoesNotThrow(() -> dispatchEvent(createAssistantMessageEvent("Still works")));
+            assertEquals(1, received.size());
+            assertEquals("Still works", received.get(0));
+        } finally {
+            sessionLogger.setLevel(originalLevel);
+        }
+    }
+
+    @Test
+    void testSetEventErrorHandlerToNullRestoresDefaultBehavior() {
+        var errorCount = new AtomicInteger(0);
+
+        // Set custom handler
+        session.setEventErrorHandler((event, exception) -> {
+            errorCount.incrementAndGet();
+        });
+
+        session.on(AssistantMessageEvent.class, msg -> {
+            throw new RuntimeException("error");
+        });
+
+        dispatchEvent(createAssistantMessageEvent("Test1"));
+        assertEquals(1, errorCount.get());
+
+        // Reset to null (restore default logging)
+        session.setEventErrorHandler(null);
+
+        // Suppress default logging for the next dispatch
+        Logger sessionLogger = Logger.getLogger(CopilotSession.class.getName());
+        Level originalLevel = sessionLogger.getLevel();
+        sessionLogger.setLevel(Level.OFF);
+
+        try {
+            dispatchEvent(createAssistantMessageEvent("Test2"));
+        } finally {
+            sessionLogger.setLevel(originalLevel);
+        }
+
+        // Custom handler should NOT have been called again
+        assertEquals(1, errorCount.get());
+    }
+
+    @Test
+    void testErrorHandlerReceivesCorrectEventType() {
+        var capturedEvents = new ArrayList<AbstractSessionEvent>();
+
+        session.setEventErrorHandler((event, exception) -> {
+            capturedEvents.add(event);
+        });
+
+        session.on(event -> {
+            throw new RuntimeException("always fails");
+        });
+
+        var msgEvent = createAssistantMessageEvent("msg");
+        var idleEvent = createSessionIdleEvent();
+
+        dispatchEvent(msgEvent);
+        dispatchEvent(idleEvent);
+
+        assertEquals(2, capturedEvents.size());
+        assertInstanceOf(AssistantMessageEvent.class, capturedEvents.get(0));
+        assertInstanceOf(SessionIdleEvent.class, capturedEvents.get(1));
+    }
+
+    // ====================================================================
+    // Helper methods
+    // ====================================================================
+
     private void dispatchEvent(AbstractSessionEvent event) {
         try {
             Method dispatchMethod = CopilotSession.class.getDeclaredMethod("dispatchEvent", AbstractSessionEvent.class);