Copilot SDK Cookbook

cookbook/README.md

@@ -0,0 +1,86 @@
+# GitHub Copilot SDK Cookbook
+
+This cookbook collects small, focused recipes showing how to accomplish common tasks with the GitHub Copilot SDK across languages. Each recipe is intentionally short and practical, with copy‑pasteable snippets and pointers to fuller examples and tests.
+
+## Recipes by Language
+
+### .NET (C#)
+
+- [Error Handling](dotnet/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](dotnet/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](dotnet/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](dotnet/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](dotnet/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
+
+### Node.js / TypeScript
+
+- [Error Handling](nodejs/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](nodejs/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](nodejs/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](nodejs/cookbook/pr-visialisation.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](nodejs/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
+
+### Python
+
+- [Error Handling](python/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](python/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](python/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](python/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](python/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
+
+### Go
+
+- [Error Handling](go/cookbook/error-handling.md): Handle errors gracefully including connection failures, timeouts, and cleanup.
+- [Multiple Sessions](go/cookbook/multiple-sessions.md): Manage multiple independent conversations simultaneously.
+- [Managing Local Files](go/cookbook/managing-local-files.md): Organize files by metadata using AI-powered grouping strategies.
+- [PR Visualization](go/cookbook/pr-visualization.md): Generate interactive PR age charts using GitHub MCP Server.
+- [Persisting Sessions](go/cookbook/persisting-sessions.md): Save and resume sessions across restarts.
+
+## How to Use
+
+- Browse your language section above and open the recipe links
+- Each recipe includes runnable examples in a `recipe/` subfolder with language-specific tooling
+- See existing examples and tests for working references:
+  - Node.js examples: `nodejs/examples/basic-example.ts`
+  - E2E tests: `go/e2e`, `python/e2e`, `nodejs/test/e2e`, `dotnet/test/Harness`
+
+## Running Examples
+
+### .NET
+
+```bash
+cd dotnet/cookbook/recipe
+dotnet run <filename>.cs
+```
+
+### Node.js
+
+```bash
+cd nodejs/cookbook/recipe
+npm install
+npx tsx <filename>.ts
+```
+
+### Python
+
+```bash
+cd python/cookbook/recipe
+pip install -r requirements.txt
+python <filename>.py
+```
+
+### Go
+
+```bash
+cd go/cookbook/recipe
+go run <filename>.go
+```
+
+## Contributing
+
+- Propose or add a new recipe by creating a markdown file in your language's `cookbook/` folder and a runnable example in `recipe/`
+- Follow repository guidance in [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Status
+
+Cookbook structure is complete with 4 recipes across all 4 supported languages. Each recipe includes both markdown documentation and runnable examples.

dotnet/cookbook/README.md

@@ -0,0 +1,19 @@
+# GitHub Copilot SDK Cookbook — .NET (C#)
+
+This folder hosts short, practical recipes for using the GitHub Copilot SDK with .NET. 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
+
+This README is a scaffold; recipe files are placeholders until populated.

dotnet/cookbook/error-handling.md

@@ -0,0 +1,156 @@
+# Error Handling Patterns
+
+Handle errors gracefully in your Copilot SDK applications.
+
+> **Runnable example:** [recipe/error-handling.cs](recipe/error-handling.cs)
+>
+> ```bash
+> dotnet run recipe/error-handling.cs
+> ```
+
+## Example scenario
+
+You need to handle various error conditions like connection failures, timeouts, and invalid responses.
+
+## Basic try-catch
+
+```csharp
+using GitHub.Copilot.SDK;
+
+var client = new CopilotClient();
+
+try
+{
+    await client.StartAsync();
+    var session = await client.CreateSessionAsync(new SessionConfig
+    {
+        Model = "gpt-5"
+    });
+
+    var done = new TaskCompletionSource<string>();
+    session.On(evt =>
+    {
+        if (evt is AssistantMessageEvent msg)
+        {
+            done.SetResult(msg.Data.Content);
+        }
+    });
+
+    await session.SendAsync(new MessageOptions { Prompt = "Hello!" });
+    var response = await done.Task;
+    Console.WriteLine(response);
+
+    await session.DisposeAsync();
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"Error: {ex.Message}");
+}
+finally
+{
+    await client.StopAsync();
+}
+```
+
+## Handling specific error types
+
+```csharp
+try
+{
+    await client.StartAsync();
+}
+catch (FileNotFoundException)
+{
+    Console.WriteLine("Copilot CLI not found. Please install it first.");
+}
+catch (HttpRequestException ex) when (ex.Message.Contains("connection"))
+{
+    Console.WriteLine("Could not connect to Copilot CLI server.");
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"Unexpected error: {ex.Message}");
+}
+```
+
+## Timeout handling
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
+
+try
+{
+    var done = new TaskCompletionSource<string>();
+    session.On(evt =>
+    {
+        if (evt is AssistantMessageEvent msg)
+        {
+            done.SetResult(msg.Data.Content);
+        }
+    });
+
+    await session.SendAsync(new MessageOptions { Prompt = "Complex question..." });
+
+    // Wait with timeout (30 seconds)
+    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
+    var response = await done.Task.WaitAsync(cts.Token);
+
+    Console.WriteLine(response);
+}
+catch (OperationCanceledException)
+{
+    Console.WriteLine("Request timed out");
+}
+```
+
+## Aborting a request
+
+```csharp
+var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
+
+// Start a request
+await session.SendAsync(new MessageOptions { Prompt = "Write a very long story..." });
+
+// Abort it after some condition
+await Task.Delay(5000);
+await session.AbortAsync();
+Console.WriteLine("Request aborted");
+```
+
+## Graceful shutdown
+
+```csharp
+Console.CancelKeyPress += async (sender, e) =>
+{
+    e.Cancel = true;
+    Console.WriteLine("Shutting down...");
+
+    var errors = await client.StopAsync();
+    if (errors.Count > 0)
+    {
+        Console.WriteLine($"Cleanup errors: {string.Join(", ", errors)}");
+    }
+
+    Environment.Exit(0);
+};
+```
+
+## Using await using for automatic disposal
+
+```csharp
+await using var client = new CopilotClient();
+await client.StartAsync();
+
+var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });
+
+// ... do work ...
+
+// client.StopAsync() is automatically called when exiting scope
+```
+
+## Best practices
+
+1. **Always clean up**: Use try-finally or `await using` to ensure `StopAsync()` is called
+2. **Handle connection errors**: The CLI might not be installed or running
+3. **Set appropriate timeouts**: Use `CancellationToken` for long-running requests
+4. **Log errors**: Capture error details for debugging