Skip to content

Fix documentation coverage gaps #186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brunoborges merged 2 commits into from
Mar 12, 2026
+89 −0
Merged

Fix documentation coverage gaps #186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
48e3960
Fix documentation coverage gaps
brunoborges Mar 12, 2026
7215df0
Update src/site/markdown/documentation.md
brunoborges Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions src/site/markdown/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ This guide covers advanced scenarios for extending and customizing your Copilot
- [Loading Skills](#Loading_Skills)
- [Disabling Skills](#Disabling_Skills)
- [Custom Configuration Directory](#Custom_Configuration_Directory)
- [Session Logging](#Session_Logging)
- [Early Event Registration](#Early_Event_Registration)
- [User Input Handling](#User_Input_Handling)
- [Permission Handling](#Permission_Handling)
- [Session Hooks](#Session_Hooks)
Expand Down Expand Up @@ -506,6 +508,54 @@ This is useful when you need to isolate session configuration or use different s

---

## Session Logging

Send log messages to the session for debugging, status updates, or UI feedback.

```java
// Simple log message (defaults to "info" level)
session.log("Processing step 1 of 3").get();

// Log with explicit level and ephemeral flag
session.log("Downloading dependencies...", "info", true).get();
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | String | The log message text |
| `level` | String | Log level: `"info"`, `"warning"`, `"error"` |
| `ephemeral` | Boolean | If `true`, the message is transient and may not be persisted |

Use cases:
- Displaying progress in a UI while the session processes a request
- Sending status updates to the session log
- Debugging session behavior with contextual messages

See [CopilotSession.log()](apidocs/com/github/copilot/sdk/CopilotSession.html#log(java.lang.String)) Javadoc for details.

---

## Early Event Registration

Register an event handler *before* the `session.create` RPC is issued, ensuring no early events are missed.

When you register handlers with `session.on()` after `createSession()` returns, you may miss events emitted during session creation (e.g., `SessionStartEvent`). Use `SessionConfig.setOnEvent()` to guarantee delivery of all events from the very start:

```java
var events = new CopyOnWriteArrayList<AbstractSessionEvent>();

var session = client.createSession(
new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
.setOnEvent(events::add) // Registered before session.create RPC
).get();

// events list now includes SessionStartEvent and any other early events
```

This is equivalent to calling `session.on(handler)` immediately after creation, but executes earlier in the lifecycle. The same option is available on `ResumeSessionConfig.setOnEvent()` for resumed sessions.

---

## User Input Handling

Handle user input requests when the AI uses the `ask_user` tool to gather information from the user.
Expand Down
38 changes: 38 additions & 0 deletions src/site/markdown/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,9 @@ The SDK supports event types organized by category. All events extend `AbstractS
| `SessionInfoEvent` | `session.info` | Informational message from the session |
| `SessionShutdownEvent` | `session.shutdown` | Session is shutting down (includes reason and exit code) |
| `SessionModelChangeEvent` | `session.model_change` | The model was changed mid-session |
| `SessionModeChangedEvent` | `session.mode_changed` | Session mode changed (e.g., plan mode) |
| `SessionPlanChangedEvent` | `session.plan_changed` | Session plan was updated |
| `SessionWorkspaceFileChangedEvent` | `session.workspace_file_changed` | A file in the workspace was modified |
| `SessionHandoffEvent` | `session.handoff` | Session handed off to another agent |
| `SessionTruncationEvent` | `session.truncation` | Context was truncated due to limits |
| `SessionSnapshotRewindEvent` | `session.snapshot_rewind` | Session rewound to a previous snapshot |
Expand Down Expand Up @@ -220,8 +223,37 @@ The SDK supports event types organized by category. All events extend `AbstractS
| `HookStartEvent` | `hook.start` | Hook execution started |
| `HookEndEvent` | `hook.end` | Hook execution completed |
| `SystemMessageEvent` | `system.message` | System-level message |
| `SystemNotificationEvent` | `system.notification` | System notification (informational) |
| `SkillInvokedEvent` | `skill.invoked` | A skill was invoked |

### External Tool Events

| Event | Type String | Description |
|-------|-------------|-------------|
| `ExternalToolRequestedEvent` | `external_tool.requested` | An external tool invocation was requested |
| `ExternalToolCompletedEvent` | `external_tool.completed` | An external tool invocation completed |

### Permission Events

| Event | Type String | Description |
|-------|-------------|-------------|
| `PermissionRequestedEvent` | `permission.requested` | A permission request was issued |
| `PermissionCompletedEvent` | `permission.completed` | A permission request was resolved |

### Command Events

| Event | Type String | Description |
|-------|-------------|-------------|
| `CommandQueuedEvent` | `command.queued` | A command was queued for execution |
| `CommandCompletedEvent` | `command.completed` | A queued command completed |

### Plan Mode Events

| Event | Type String | Description |
|-------|-------------|-------------|
| `ExitPlanModeRequestedEvent` | `exit_plan_mode.requested` | Exit from plan mode was requested |
| `ExitPlanModeCompletedEvent` | `exit_plan_mode.completed` | Exit from plan mode completed |

See the [events package Javadoc](apidocs/com/github/copilot/sdk/events/package-summary.html) for detailed event data structures.

---
Expand Down Expand Up @@ -598,9 +630,12 @@ When resuming a session, you can optionally reconfigure many settings. This is u
| `configDir` | Override configuration directory |
| `mcpServers` | Configure MCP servers |
| `customAgents` | Configure custom agents |
| `agent` | Pre-select a custom agent at session start |
| `skillDirectories` | Directories to load skills from |
| `disabledSkills` | Skills to disable |
| `infiniteSessions` | Configure infinite session behavior |
| `disableResume` | When `true`, resumes without emitting a `session.resume` event |
| `onEvent` | Event handler registered before session resumption |

**Example: Changing Model on Resume**

Expand Down Expand Up @@ -637,6 +672,7 @@ Complete list of all `SessionConfig` options for `createSession()`:
| Option | Type | Description | Guide |
|--------|------|-------------|-------|
| `sessionId` | String | Custom session ID (auto-generated if omitted) | — |
| `clientName` | String | Client name for User-Agent identification | — |
| `model` | String | AI model to use | [Choosing a Model](#Choosing_a_Model) |
| `reasoningEffort` | String | Reasoning depth: `"low"`, `"medium"`, `"high"`, `"xhigh"` | [Reasoning Effort](#Reasoning_Effort) |
| `tools` | List&lt;ToolDefinition&gt; | Custom tools the assistant can invoke | [Custom Tools](advanced.html#Custom_Tools) |
Expand All @@ -651,10 +687,12 @@ Complete list of all `SessionConfig` options for `createSession()`:
| `streaming` | boolean | Enable streaming response chunks | [Streaming Responses](#Streaming_Responses) |
| `mcpServers` | Map&lt;String, Object&gt; | MCP server configurations | [MCP Servers](mcp.html) |
| `customAgents` | List&lt;CustomAgentConfig&gt; | Custom agent definitions | [Custom Agents](advanced.html#Custom_Agents) |
| `agent` | String | Pre-select a custom agent at session start | [Custom Agents](advanced.html#Custom_Agents) |
| `infiniteSessions` | InfiniteSessionConfig | Auto-compaction for long conversations | [Infinite Sessions](advanced.html#Infinite_Sessions) |
| `skillDirectories` | List&lt;String&gt; | Directories to load skills from | [Skills](advanced.html#Skills_Configuration) |
| `disabledSkills` | List&lt;String&gt; | Skills to disable by name | [Skills](advanced.html#Skills_Configuration) |
| `configDir` | String | Custom configuration directory | [Config Dir](advanced.html#Custom_Configuration_Directory) |
| `onEvent` | Consumer&lt;AbstractSessionEvent&gt; | Event handler registered before session creation | [Early Event Registration](advanced.html#Early_Event_Registration) |

### Cloning SessionConfig

Expand Down
1 change: 1 addition & 0 deletions src/site/markdown/setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,7 @@ Complete list of `CopilotClientOptions` settings:
| `logLevel` | String | CLI log level | `"info"` |
| `environment` | Map | Environment variables | inherited |
| `cwd` | String | Working directory | current dir |
| `onListModels` | Supplier | Custom model listing implementation | `null` (use CLI) |

### Extra CLI Arguments

Expand Down
Loading