feat: add Connection State & Diagnostics and Message Delivery Mode sections to documentation

Author: brunoborges

src/site/markdown/advanced.md

@@ -15,6 +15,7 @@ This guide covers advanced scenarios for extending and customizing your Copilot
 - [Infinite Sessions](#Infinite_Sessions)
   - [Compaction Events](#Compaction_Events)
 - [MCP Servers](#MCP_Servers)
+- [Custom Agents](#Custom_Agents)
 - [Skills Configuration](#Skills_Configuration)
   - [Loading Skills](#Loading_Skills)
   - [Disabling Skills](#Disabling_Skills)
@@ -236,6 +237,65 @@ var session = client.createSession(
 
 ---
 
+## Custom Agents
+
+Extend the base Copilot assistant with specialized agents that have their own tools, prompts, and behavior. Users can invoke agents using the `@agent-name` mention syntax in messages.
+
+```java
+var reviewer = new CustomAgentConfig()
+    .setName("code-reviewer")
+    .setDisplayName("Code Reviewer")
+    .setDescription("Reviews code for best practices and security")
+    .setPrompt("You are a code review expert. Focus on security, performance, and maintainability.")
+    .setTools(List.of("read_file", "search_code"));
+
+var session = client.createSession(
+    new SessionConfig()
+        .setCustomAgents(List.of(reviewer))
+).get();
+
+// The user can now mention @code-reviewer in messages
+session.send("@code-reviewer Review src/Main.java").get();
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | String | Unique identifier used for `@mentions` (alphanumeric and hyphens) |
+| `displayName` | String | Human-readable name shown to users |
+| `description` | String | Describes the agent's capabilities |
+| `prompt` | String | System prompt that defines the agent's behavior |
+| `tools` | List<String> | Tool names available to this agent |
+| `mcpServers` | Map | MCP servers available to this agent |
+| `infer` | Boolean | Whether the agent can be auto-selected based on context |
+
+### Multiple Agents
+
+Register multiple agents for different tasks:
+
+```java
+var agents = List.of(
+    new CustomAgentConfig()
+        .setName("reviewer")
+        .setDescription("Code review")
+        .setPrompt("You review code for issues."),
+    new CustomAgentConfig()
+        .setName("documenter")
+        .setDescription("Documentation writer")
+        .setPrompt("You write clear documentation.")
+        .setInfer(true)  // Auto-select when appropriate
+);
+
+var session = client.createSession(
+    new SessionConfig().setCustomAgents(agents)
+).get();
+```
+
+See [CustomAgentConfig](apidocs/com/github/copilot/sdk/json/CustomAgentConfig.html) Javadoc for full details.
+
+---
+
 ## Skills Configuration
 
 Load custom skills from directories to extend the AI's capabilities with domain-specific knowledge.

src/site/markdown/documentation.md

@@ -12,6 +12,8 @@ This guide covers common use cases for the Copilot SDK for Java. For complete AP
 - [Streaming Responses](#Streaming_Responses)
 - [Session Operations](#Session_Operations)
 - [Choosing a Model](#Choosing_a_Model)
+- [Connection State & Diagnostics](#Connection_State__Diagnostics)
+- [Message Delivery Mode](#Message_Delivery_Mode)
 - [Session Management](#Session_Management)
 
 ---
@@ -310,6 +312,93 @@ var session = client.createSession(
 
 ---
 
+## Connection State & Diagnostics
+
+### Checking Connection State
+
+Query the client's connection state at any time without making a server call:
+
+```java
+ConnectionState state = client.getState();
+switch (state) {
+    case CONNECTED -> System.out.println("Ready");
+    case CONNECTING -> System.out.println("Starting up...");
+    case DISCONNECTED -> System.out.println("Not connected");
+    case ERROR -> System.out.println("Connection failed");
+}
+```
+
+The four states are:
+
+| State | Description |
+|-------|-------------|
+| `DISCONNECTED` | Client has not been started yet |
+| `CONNECTING` | `start()` was called but hasn't completed |
+| `CONNECTED` | Client is connected and ready |
+| `ERROR` | Connection failed (check logs for details) |
+
+### Server Status
+
+Get CLI version and protocol information:
+
+```java
+var status = client.getStatus().get();
+System.out.println("CLI version: " + status.getVersion());
+System.out.println("Protocol version: " + status.getProtocolVersion());
+```
+
+### Authentication Status
+
+Check whether the current connection is authenticated and how:
+
+```java
+var auth = client.getAuthStatus().get();
+if (auth.isAuthenticated()) {
+    System.out.println("Logged in as: " + auth.getLogin());
+    System.out.println("Auth type: " + auth.getAuthType());
+    System.out.println("Host: " + auth.getHost());
+} else {
+    System.out.println("Not authenticated: " + auth.getStatusMessage());
+}
+```
+
+### Ping
+
+Verify server connectivity:
+
+```java
+var pong = client.ping("hello").get();
+System.out.println("Server responded, protocol version: " + pong.protocolVersion());
+```
+
+See [ConnectionState](apidocs/com/github/copilot/sdk/ConnectionState.html), [GetStatusResponse](apidocs/com/github/copilot/sdk/json/GetStatusResponse.html), and [GetAuthStatusResponse](apidocs/com/github/copilot/sdk/json/GetAuthStatusResponse.html) Javadoc for details.
+
+---
+
+## Message Delivery Mode
+
+Control how messages are delivered to the session:
+
+```java
+// Default: message is enqueued for processing
+session.send(new MessageOptions()
+    .setPrompt("Analyze this codebase")
+).get();
+
+// Immediate: process the message right away
+session.send(new MessageOptions()
+    .setPrompt("Quick question")
+    .setMode("immediate")
+).get();
+```
+
+| Mode | Description |
+|------|-------------|
+| `"enqueue"` | Queue the message for processing (default) |
+| `"immediate"` | Process the message immediately |
+
+---
+
 ## Session Management
 
 ### Multiple Concurrent Sessions