docs: add Java language tabs across all SDK documentation (#1021)

* docs: add Java language tabs across all SDK documentation

Add Java code examples to all 22 language-tabbed documentation files,
matching the existing Node.js, Python, Go, and .NET tabs.

Files updated:
- docs/getting-started.md (8 sections + telemetry table + text refs)
- docs/features/ (7 files: index, hooks, custom-agents, image-input,
  streaming-events, steering-and-queueing, skills)
- docs/hooks/ (6 files: index, pre-tool-use, post-tool-use,
  user-prompt-submitted, session-lifecycle, error-handling)
- docs/auth/ (2 files: index, byok)
- docs/setup/ (4 files: local-cli, bundled-cli, backend-services,
  github-oauth)
- docs/observability/opentelemetry.md
- docs/troubleshooting/debugging.md
- docs/integrations/microsoft-agent-framework.md

All Java examples use idiomatic patterns: CompletableFuture,
try-with-resources, ToolDefinition.create(), PermissionHandler.APPROVE_ALL,
typed event handlers, and builder-style configuration.

* Update docs/setup/local-cli.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/setup/bundled-cli.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/integrations/microsoft-agent-framework.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/integrations/microsoft-agent-framework.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Address review feedback on Java code snippets

- Fix Maven coordinates: com.github:copilot-sdk-java with version property
- Fix accessor: getContent() → content() (record-style) across all files
- Fix accessor: input.toolName() → input.getToolName() (class-style)
- Fix accessor: event.deltaContent() → event.getData().deltaContent()
- Fix ToolDefinition: use factory method create() instead of constructor
- Add missing imports (json.*, events.*) to feature doc snippets
- Add client.start().get() and try-with-resources to hooks quickstart
- Wrap OAuth usage example in try-with-resources

* fix: audit Java code samples against SDK implementation

- Fix PreToolUseHookOutput: record cannot use setters, use deny() factory
- Fix SessionStartHookOutput: record cannot use setters, use constructor
- Fix session.getId() → session.getSessionId()
- Fix input.getPrompt() → input.prompt() (record accessor)
- Fix response.data() → response.getData() (class accessor)
- Fix setOnListModels: wrap return in CompletableFuture.completedFuture()
- Fix custom-agents event handler: use instanceof pattern matching
  (AbstractSessionEvent has no getData() method)
- Fix streaming-events: remove event.getData() from generic handler
- Fix SubagentCompleted/Failed: use agentName() not agentDisplayName()
- Fix CopilotClientOptions import: class is in json package, not sdk
- Fix hook type signatures: use PreToolUseHandler etc. instead of BiFunction

* Update docs/getting-started.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/getting-started.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/setup/local-cli.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/setup/backend-services.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/observability/opentelemetry.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update docs/getting-started.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: brunoborges

docs/auth/byok.md

@@ -164,6 +164,36 @@ Console.WriteLine(response?.Data.Content);
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+var client = new CopilotClient();
+client.start().get();
+
+var session = client.createSession(new SessionConfig()
+    .setModel("gpt-5.2-codex")  // Your deployment name
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setProvider(new ProviderConfig()
+        .setType("openai")
+        .setBaseUrl("https://your-resource.openai.azure.com/openai/v1/")
+        .setWireApi("responses")  // Use "completions" for older models
+        .setApiKey(System.getenv("FOUNDRY_API_KEY")))
+).get();
+
+var response = session.sendAndWait(new MessageOptions()
+    .setPrompt("What is 2+2?")).get();
+System.out.println(response.getData().content());
+
+client.stop().get();
+```
+
+</details>
+
 ## Provider Configuration Reference
 
 ### ProviderConfig Fields
@@ -412,6 +442,28 @@ var client = new CopilotClient(new CopilotClientOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.json.*;
+import java.util.concurrent.CompletableFuture;
+
+var client = new CopilotClient(new CopilotClientOptions()
+    .setOnListModels(() -> CompletableFuture.completedFuture(List.of(
+        new ModelInfo()
+            .setId("my-custom-model")
+            .setName("My Custom Model")
+            .setCapabilities(new ModelCapabilities()
+                .setSupports(new ModelSupports().setVision(false).setReasoningEffort(false))
+                .setLimits(new ModelLimits().setMaxContextWindowTokens(128000)))
+    )))
+);
+```
+
+</details>
+
 Results are cached after the first call, just like the default behavior. The handler completely replaces the CLI's `models.list` RPC — no fallback to the server occurs.
 
 ## Limitations

docs/auth/index.md

@@ -85,6 +85,19 @@ await using var client = new CopilotClient();
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+
+// Default: uses logged-in user credentials
+var client = new CopilotClient();
+client.start().get();
+```
+
+</details>
+
 **When to use:**
 - Desktop applications where users interact directly
 - Development and testing environments
@@ -189,6 +202,22 @@ await using var client = new CopilotClient(new CopilotClientOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.json.*;
+
+var client = new CopilotClient(new CopilotClientOptions()
+    .setGitHubToken(userAccessToken)  // Token from OAuth flow
+    .setUseLoggedInUser(false)        // Don't use stored CLI credentials
+);
+client.start().get();
+```
+
+</details>
+
 **Supported token types:**
 - `gho_` - OAuth user access tokens
 - `ghu_` - GitHub App user access tokens  
@@ -351,6 +380,21 @@ await using var client = new CopilotClient(new CopilotClientOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.json.*;
+
+var client = new CopilotClient(new CopilotClientOptions()
+    .setUseLoggedInUser(false)  // Only use explicit tokens
+);
+client.start().get();
+```
+
+</details>
+
 ## Next Steps
 
 - [BYOK Documentation](./byok.md) - Learn how to use your own API keys

docs/features/custom-agents.md

@@ -205,6 +205,41 @@ await using var session = await client.CreateSessionAsync(new SessionConfig
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setModel("gpt-4.1")
+            .setCustomAgents(List.of(
+                new CustomAgentConfig()
+                    .setName("researcher")
+                    .setDisplayName("Research Agent")
+                    .setDescription("Explores codebases and answers questions using read-only tools")
+                    .setTools(List.of("grep", "glob", "view"))
+                    .setPrompt("You are a research assistant. Analyze code and answer questions. Do not modify any files."),
+                new CustomAgentConfig()
+                    .setName("editor")
+                    .setDisplayName("Editor Agent")
+                    .setDescription("Makes targeted code changes")
+                    .setTools(List.of("view", "edit", "bash"))
+                    .setPrompt("You are a code editor. Make minimal, surgical changes to files as requested.")
+            ))
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+}
+```
+
+</details>
+
 ## Configuration Reference
 
 | Property | Type | Required | Description |
@@ -316,6 +351,28 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+<!-- docs-validate: skip -->
+```java
+var session = client.createSession(
+    new SessionConfig()
+        .setCustomAgents(List.of(
+            new CustomAgentConfig()
+                .setName("researcher")
+                .setPrompt("You are a research assistant. Analyze code and answer questions."),
+            new CustomAgentConfig()
+                .setName("editor")
+                .setPrompt("You are a code editor. Make minimal, surgical changes.")
+        ))
+        .setAgent("researcher") // Pre-select the researcher agent
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+).get();
+```
+
+</details>
+
 ## How Sub-Agent Delegation Works
 
 When you send a prompt to a session with custom agents, the runtime evaluates whether to delegate to a sub-agent:
@@ -561,6 +618,34 @@ await session.SendAndWaitAsync(new MessageOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+session.on(event -> {
+    if (event instanceof SubagentStartedEvent e) {
+        System.out.println("▶ Sub-agent started: " + e.getData().agentDisplayName());
+        System.out.println("  Description: " + e.getData().agentDescription());
+        System.out.println("  Tool call ID: " + e.getData().toolCallId());
+    } else if (event instanceof SubagentCompletedEvent e) {
+        System.out.println("✅ Sub-agent completed: " + e.getData().agentName());
+    } else if (event instanceof SubagentFailedEvent e) {
+        System.out.println("❌ Sub-agent failed: " + e.getData().agentName());
+        System.out.println("  Error: " + e.getData().error());
+    } else if (event instanceof SubagentSelectedEvent e) {
+        System.out.println("🎯 Agent selected: " + e.getData().agentDisplayName());
+    } else if (event instanceof SubagentDeselectedEvent e) {
+        System.out.println("↩ Agent deselected, returning to parent");
+    }
+});
+
+var response = session.sendAndWait(
+    new MessageOptions().setPrompt("Research how authentication works in this codebase")
+).get();
+```
+
+</details>
+
 ## Building an Agent Tree UI
 
 Sub-agent events include `toolCallId` fields that let you reconstruct the execution tree. Here's a pattern for tracking agent activity:

docs/features/hooks.md

@@ -195,6 +195,33 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var hooks = new SessionHooks()
+        .setOnSessionStart((input, inv) -> CompletableFuture.completedFuture(null))
+        .setOnPreToolUse((input, inv) -> CompletableFuture.completedFuture(null))
+        .setOnPostToolUse((input, inv) -> CompletableFuture.completedFuture(null));
+        // ... add only the hooks you need
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setHooks(hooks)
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+}
+```
+
+</details>
+
 > **Tip:** Every hook handler receives an `invocation` parameter containing the `sessionId`, which is useful for correlating logs and maintaining per-session state.
 
 ---
@@ -380,6 +407,32 @@ var session = await client.CreateSessionAsync(new SessionConfig
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+var readOnlyTools = Set.of("read_file", "glob", "grep", "view");
+
+var hooks = new SessionHooks()
+    .setOnPreToolUse((input, invocation) -> {
+        if (!readOnlyTools.contains(input.getToolName())) {
+            return CompletableFuture.completedFuture(
+                PreToolUseHookOutput.deny(
+                    "Only read-only tools are allowed. \"" + input.getToolName() + "\" was blocked.")
+            );
+        }
+        return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
+    });
+
+var session = client.createSession(
+    new SessionConfig()
+        .setHooks(hooks)
+        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+).get();
+```
+
+</details>
+
 ### Restrict file access to specific directories
 
 ```typescript

docs/features/image-input.md

@@ -219,6 +219,34 @@ await session.SendAsync(new MessageOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setModel("gpt-4.1")
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    session.send(new MessageOptions()
+        .setPrompt("Describe what you see in this image")
+        .setAttachments(List.of(
+            new Attachment("file", "/absolute/path/to/screenshot.png", "screenshot.png")
+        ))
+    ).get();
+}
+```
+
+</details>
+
 ## Quick Start — Blob Attachment
 
 When you already have image data in memory (e.g., a screenshot captured by your app, or an image fetched from an API), use a blob attachment to send it directly without writing to disk.
@@ -400,6 +428,38 @@ await session.SendAsync(new MessageOptions
 
 </details>
 
+<details>
+<summary><strong>Java</strong></summary>
+
+```java
+import com.github.copilot.sdk.CopilotClient;
+import com.github.copilot.sdk.events.*;
+import com.github.copilot.sdk.json.*;
+
+try (var client = new CopilotClient()) {
+    client.start().get();
+
+    var session = client.createSession(
+        new SessionConfig()
+            .setModel("gpt-4.1")
+            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    ).get();
+
+    var base64ImageData = "..."; // your base64-encoded image
+    session.send(new MessageOptions()
+        .setPrompt("Describe what you see in this image")
+        .setAttachments(List.of(
+            new BlobAttachment()
+                .setData(base64ImageData)
+                .setMimeType("image/png")
+                .setDisplayName("screenshot.png")
+        ))
+    ).get();
+}
+```
+
+</details>
+
 ## Supported Formats
 
 Supported image formats include JPG, PNG, GIF, and other common image types. For file attachments, the runtime reads the image from disk and converts it as needed. For blob attachments, you provide the base64 data and MIME type directly. Use PNG or JPEG for best results, as these are the most widely supported formats.

docs/features/index.md

@@ -1,6 +1,6 @@
 # Features
 
-These guides cover the capabilities you can add to your Copilot SDK application. Each guide includes examples in all supported languages (TypeScript, Python, Go, and .NET).
+These guides cover the capabilities you can add to your Copilot SDK application. Each guide includes examples in all supported languages (TypeScript, Python, Go, .NET, and Java).
 
 > **New to the SDK?** Start with the [Getting Started tutorial](../getting-started.md) first, then come back here to add more capabilities.