Add Java SDK cookbooks based on official .NET and Go SDKs

Co-authored-by: brunoborges <129743+brunoborges@users.noreply.github.com>

Author: Copilot

cookbook/README.md

@@ -0,0 +1,19 @@
+# GitHub Copilot SDK Cookbook — Java
+
+This folder hosts short, practical recipes for using the GitHub Copilot SDK with Java. Each recipe is concise, copy‑pasteable, and points to fuller examples and tests.
+
+## Recipes
+
+- [Error Handling](error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](persisting-sessions.md): Save and resume sessions across restarts.
+
+## Contributing
+
+Add a new recipe by creating a markdown file in this folder and linking it above. Follow repository guidance in [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Status
+
+These recipes are complete, practical examples and can be used directly or adapted for your own projects.

cookbook/error-handling.md

@@ -0,0 +1,224 @@
+# Error Handling Patterns
+
+Handle errors gracefully in your Copilot SDK applications.
+
+## Example scenario
+
+You need to handle various error conditions like connection failures, timeouts, and invalid responses.
+
+## Basic error handling
+
+```java
+import com.github.copilot.sdk.*;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+public class BasicErrorHandling {
+    public static void main(String[] args) {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setModel("gpt-5")).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Hello!")).get();
+
+            session.close();
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Handling specific error types
+
+```java
+import java.io.IOException;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeoutException;
+
+public class SpecificErrorHandling {
+    public static void startClient() {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+            // ... use client ...
+        } catch (IOException ex) {
+            System.err.println("Copilot CLI not found. Please install it first.");
+            System.err.println("Details: " + ex.getMessage());
+        } catch (TimeoutException ex) {
+            System.err.println("Could not connect to Copilot CLI server.");
+            System.err.println("Details: " + ex.getMessage());
+        } catch (ExecutionException ex) {
+            System.err.println("Unexpected error: " + ex.getCause().getMessage());
+            ex.getCause().printStackTrace();
+        } catch (Exception ex) {
+            System.err.println("Unexpected error: " + ex.getMessage());
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Timeout handling
+
+```java
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+public class TimeoutHandling {
+    public static void sendWithTimeout(CopilotSession session) {
+        try {
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            // Wait up to 30 seconds for response
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("Complex question..."))
+                .get(30, TimeUnit.SECONDS);
+
+        } catch (TimeoutException ex) {
+            System.err.println("Request timed out");
+        } catch (Exception ex) {
+            System.err.println("Error: " + ex.getMessage());
+        }
+    }
+}
+```
+
+## Aborting a request
+
+```java
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
+
+public class AbortRequest {
+    public static void abortAfterDelay(CopilotSession session) {
+        // Start a request (non-blocking)
+        session.send(new MessageOptions()
+            .setPrompt("Write a very long story..."));
+
+        // Schedule abort after 5 seconds
+        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
+        scheduler.schedule(() -> {
+            try {
+                session.abort().get();
+                System.out.println("Request aborted");
+            } catch (Exception ex) {
+                System.err.println("Failed to abort: " + ex.getMessage());
+            }
+        }, 5, TimeUnit.SECONDS);
+    }
+}
+```
+
+## Graceful shutdown
+
+```java
+public class GracefulShutdown {
+    public static void main(String[] args) {
+        var client = new CopilotClient();
+
+        // Set up shutdown hook
+        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
+            System.out.println("\nShutting down...");
+            try {
+                client.close();
+            } catch (Exception ex) {
+                System.err.println("Error during shutdown: " + ex.getMessage());
+            }
+        }));
+
+        try {
+            client.start().get();
+            // ... do work ...
+        } catch (Exception ex) {
+            ex.printStackTrace();
+        }
+    }
+}
+```
+
+## Try-with-resources pattern
+
+```java
+public class TryWithResources {
+    public static void doWork() throws Exception {
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            try (var session = client.createSession(
+                    new SessionConfig().setModel("gpt-5")).get()) {
+
+                session.on(AssistantMessageEvent.class, msg -> {
+                    System.out.println(msg.getData().getContent());
+                });
+
+                session.sendAndWait(new MessageOptions()
+                    .setPrompt("Hello!")).get();
+
+                // Session and client are automatically closed
+            }
+        }
+    }
+}
+```
+
+## Handling tool errors
+
+```java
+import java.util.Map;
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+public class ToolErrorHandling {
+    public static void handleToolErrors() throws Exception {
+        var errorTool = ToolDefinition.create(
+            "get_user_location",
+            "Gets the user's location",
+            Map.of("type", "object", "properties", Map.of()),
+            invocation -> {
+                // Return an error result
+                return CompletableFuture.completedFuture(
+                    ToolResultObject.error("Location service unavailable")
+                );
+            }
+        );
+
+        try (var client = new CopilotClient()) {
+            client.start().get();
+
+            var session = client.createSession(
+                new SessionConfig().setTools(List.of(errorTool))).get();
+
+            session.on(AssistantMessageEvent.class, msg -> {
+                System.out.println(msg.getData().getContent());
+            });
+
+            // Session continues even when tool fails
+            session.sendAndWait(new MessageOptions()
+                .setPrompt("What is my location? If you can't find out, just say 'unknown'."))
+                .get();
+
+            session.close();
+        }
+    }
+}
+```
+
+## Best practices
+
+1. **Always clean up**: Use try-with-resources to ensure `close()` is called
+2. **Handle connection errors**: The CLI might not be installed or running
+3. **Set appropriate timeouts**: Use `get(timeout, TimeUnit)` for long-running requests
+4. **Log errors**: Capture error details for debugging
+5. **Wrap operations**: Consider wrapping SDK operations in methods that handle common errors
+6. **Check error causes**: Use `ExecutionException.getCause()` to get the actual error from `CompletableFuture`