Add tests, documentation, and update .lastmerge to f7fd757

Agent-Logs-Url: https://github.com/github/copilot-sdk-java/sessions/16d575c4-83f4-4d20-99d9-b48635b3791d

Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Author: Copilot

.lastmerge

@@ -1 +1 @@
-40887393a9e687dacc141a645799441b0313ff15
+f7fd7577109d64e261456b16c49baa56258eae4e

README.md

@@ -25,7 +25,7 @@ Java SDK for programmatic control of GitHub Copilot CLI, enabling you to build A
 ### Requirements
 
 - Java 17 or later. **JDK 25 recommended**. Selecting JDK 25 enables the use of virtual threads, as shown in the [Quick Start](#quick-start).
-- GitHub Copilot 1.0.15-0 or later installed and in `PATH` (or provide custom `cliPath`)
+- GitHub Copilot 1.0.17 or later installed and in `PATH` (or provide custom `cliPath`)
 
 ### Maven
 

src/site/markdown/advanced.md

@@ -1093,6 +1093,143 @@ See [TelemetryConfig](apidocs/com/github/copilot/sdk/json/TelemetryConfig.html)
 
 ---
 
+## Slash Commands
+
+Register custom slash commands that users can invoke from the CLI TUI with `/commandname`.
+
+### Registering Commands
+
+```java
+var config = new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setCommands(List.of(
+        new CommandDefinition()
+            .setName("deploy")
+            .setDescription("Deploy the current branch")
+            .setHandler(context -> {
+                System.out.println("Deploying with args: " + context.getArgs());
+                // perform deployment ...
+                return CompletableFuture.completedFuture(null);
+            }),
+        new CommandDefinition()
+            .setName("rollback")
+            .setDescription("Roll back the last deployment")
+            .setHandler(context -> {
+                // perform rollback ...
+                return CompletableFuture.completedFuture(null);
+            })
+    ));
+
+try (CopilotClient client = new CopilotClient()) {
+    client.start().get();
+    var session = client.createSession(config).get();
+    // Users can now type /deploy or /rollback in the TUI
+}
+```
+
+Each `CommandDefinition` requires a `name` (without the leading `/`), an optional `description` shown in the TUI's command completion UI, and a `CommandHandler` that is invoked when the user executes the command.
+
+The `CommandContext` passed to the handler provides:
+- `getSessionId()` — the ID of the session where the command was invoked
+- `getCommand()` — the full command text (e.g., `/deploy production`)
+- `getCommandName()` — command name without the leading `/` (e.g., `deploy`)
+- `getArgs()` — the argument string after the command name (e.g., `production`)
+
+---
+
+## Elicitation (UI Dialogs)
+
+Elicitation allows your application to present structured UI dialogs to the user. There are two directions:
+
+1. **Incoming** — The server or an MCP tool requests input from the user via your `onElicitationRequest` handler.
+2. **Outgoing** — Your session-side code proactively requests input via `session.getUi()`.
+
+### Incoming Elicitation Handler
+
+Register a handler to receive elicitation requests from the server:
+
+```java
+var config = new SessionConfig()
+    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+    .setOnElicitationRequest(context -> {
+        System.out.println("Elicitation request: " + context.getMessage());
+        // Show the form to the user ...
+        var content = Map.of("confirmed", true);
+        return CompletableFuture.completedFuture(
+            new ElicitationResult()
+                .setAction(ElicitationResultAction.ACCEPT)
+                .setContent(content)
+        );
+    });
+```
+
+When `onElicitationRequest` is set, the SDK reports elicitation as a supported capability and the server will route elicitation requests to your handler.
+
+### Session Capabilities
+
+After `createSession` or `resumeSession`, check `session.getCapabilities()` to see what the host supports:
+
+```java
+var session = client.createSession(config).get();
+
+var caps = session.getCapabilities();
+if (caps.getUi() != null && Boolean.TRUE.equals(caps.getUi().getElicitation())) {
+    System.out.println("Elicitation is supported");
+}
+```
+
+Capabilities are updated in real time when a `capabilities.changed` event is received.
+
+### Outgoing Elicitation via `session.getUi()`
+
+If the host reports elicitation support, you can call the convenience methods on `session.getUi()`:
+
+```java
+var ui = session.getUi();
+
+// Boolean confirmation
+boolean confirmed = ui.confirm("Are you sure you want to proceed?").get();
+
+// Selection from options
+String choice = ui.select("Choose an environment", new String[]{"dev", "staging", "prod"}).get();
+
+// Text input
+String value = ui.input("Enter your name", null).get();
+
+// Custom schema
+var result = ui.elicitation(new ElicitationParams()
+    .setMessage("Enter deployment details")
+    .setRequestedSchema(new ElicitationSchema()
+        .setProperties(Map.of(
+            "branch", Map.of("type", "string"),
+            "environment", Map.of("type", "string", "enum", List.of("dev", "staging", "prod"))
+        ))
+        .setRequired(List.of("branch", "environment"))
+    )).get();
+```
+
+All `getUi()` methods throw `IllegalStateException` if the host does not support elicitation. Always check capabilities first.
+
+---
+
+## Getting Session Metadata by ID
+
+Retrieve metadata for a specific session without listing all sessions:
+
+```java
+SessionMetadata metadata = client.getSessionMetadata("session-123").get();
+if (metadata != null) {
+    System.out.println("Session: " + metadata.getSessionId());
+    System.out.println("Started: " + metadata.getStartTime());
+} else {
+    System.out.println("Session not found");
+}
+```
+
+This is more efficient than `listSessions()` when you already know the session ID, as it performs a direct O(1) lookup instead of scanning all sessions.
+
+---
+
 ## Next Steps
 
 - 📖 **[Documentation](documentation.html)** - Core concepts, events, streaming, models, tool filtering, reasoning effort

src/site/markdown/index.md

@@ -9,7 +9,7 @@ Welcome to the documentation for the **GitHub Copilot SDK for Java** — a Java
 ### Requirements
 
 - Java 17 or later
-- GitHub Copilot CLI 0.0.411-1 or later installed and in PATH (or provide custom `cliPath`)
+- GitHub Copilot CLI 1.0.17 or later installed and in PATH (or provide custom `cliPath`)
 
 ### Installation
 

src/test/java/com/github/copilot/sdk/CommandsTest.java

@@ -0,0 +1,138 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.sdk;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+import org.junit.jupiter.api.Test;
+
+import com.github.copilot.sdk.json.CommandContext;
+import com.github.copilot.sdk.json.CommandDefinition;
+import com.github.copilot.sdk.json.CommandHandler;
+import com.github.copilot.sdk.json.CommandWireDefinition;
+import com.github.copilot.sdk.json.PermissionHandler;
+import com.github.copilot.sdk.json.ResumeSessionConfig;
+import com.github.copilot.sdk.json.SessionConfig;
+
+/**
+ * Unit tests for the Commands feature (CommandDefinition, CommandContext,
+ * SessionConfig.commands, ResumeSessionConfig.commands, and the wire
+ * representation).
+ *
+ * <p>
+ * Ported from {@code CommandsTests.cs} in the upstream dotnet SDK.
+ * </p>
+ */
+class CommandsTest {
+
+    @Test
+    void commandDefinitionHasRequiredProperties() {
+        CommandHandler handler = context -> CompletableFuture.completedFuture(null);
+        var cmd = new CommandDefinition().setName("deploy").setDescription("Deploy the app").setHandler(handler);
+
+        assertEquals("deploy", cmd.getName());
+        assertEquals("Deploy the app", cmd.getDescription());
+        assertNotNull(cmd.getHandler());
+    }
+
+    @Test
+    void commandContextHasAllProperties() {
+        var ctx = new CommandContext().setSessionId("session-1").setCommand("/deploy production")
+                .setCommandName("deploy").setArgs("production");
+
+        assertEquals("session-1", ctx.getSessionId());
+        assertEquals("/deploy production", ctx.getCommand());
+        assertEquals("deploy", ctx.getCommandName());
+        assertEquals("production", ctx.getArgs());
+    }
+
+    @Test
+    void sessionConfigCommandsAreCloned() {
+        CommandHandler handler = ctx -> CompletableFuture.completedFuture(null);
+        var config = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                .setCommands(List.of(new CommandDefinition().setName("deploy").setHandler(handler)));
+
+        var clone = config.clone();
+
+        assertNotNull(clone.getCommands());
+        assertEquals(1, clone.getCommands().size());
+        assertEquals("deploy", clone.getCommands().get(0).getName());
+
+        // Collections should be independent — clone list is a copy
+        assertNotSame(config.getCommands(), clone.getCommands());
+    }
+
+    @Test
+    void resumeConfigCommandsAreCloned() {
+        CommandHandler handler = ctx -> CompletableFuture.completedFuture(null);
+        var config = new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
+                .setCommands(List.of(new CommandDefinition().setName("deploy").setHandler(handler)));
+
+        var clone = config.clone();
+
+        assertNotNull(clone.getCommands());
+        assertEquals(1, clone.getCommands().size());
+        assertEquals("deploy", clone.getCommands().get(0).getName());
+    }
+
+    @Test
+    void buildCreateRequestIncludesCommandWireDefinitions() {
+        CommandHandler handler = ctx -> CompletableFuture.completedFuture(null);
+        var config = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setCommands(
+                List.of(new CommandDefinition().setName("deploy").setDescription("Deploy").setHandler(handler),
+                        new CommandDefinition().setName("rollback").setHandler(handler)));
+
+        var request = SessionRequestBuilder.buildCreateRequest(config);
+
+        assertNotNull(request.getCommands());
+        assertEquals(2, request.getCommands().size());
+        assertEquals("deploy", request.getCommands().get(0).getName());
+        assertEquals("Deploy", request.getCommands().get(0).getDescription());
+        assertEquals("rollback", request.getCommands().get(1).getName());
+        assertNull(request.getCommands().get(1).getDescription());
+    }
+
+    @Test
+    void buildResumeRequestIncludesCommandWireDefinitions() {
+        CommandHandler handler = ctx -> CompletableFuture.completedFuture(null);
+        var config = new ResumeSessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setCommands(
+                List.of(new CommandDefinition().setName("deploy").setDescription("Deploy").setHandler(handler)));
+
+        var request = SessionRequestBuilder.buildResumeRequest("session-1", config);
+
+        assertNotNull(request.getCommands());
+        assertEquals(1, request.getCommands().size());
+        assertEquals("deploy", request.getCommands().get(0).getName());
+        assertEquals("Deploy", request.getCommands().get(0).getDescription());
+    }
+
+    @Test
+    void buildCreateRequestWithNoCommandsHasNullCommandsList() {
+        var config = new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL);
+
+        var request = SessionRequestBuilder.buildCreateRequest(config);
+
+        assertNull(request.getCommands());
+    }
+
+    @Test
+    void commandWireDefinitionHasNameAndDescription() {
+        var wire = new CommandWireDefinition("deploy", "Deploy the app");
+
+        assertEquals("deploy", wire.getName());
+        assertEquals("Deploy the app", wire.getDescription());
+    }
+
+    @Test
+    void commandWireDefinitionNullDescriptionAllowed() {
+        var wire = new CommandWireDefinition("rollback", null);
+
+        assertEquals("rollback", wire.getName());
+        assertNull(wire.getDescription());
+    }
+}

src/test/java/com/github/copilot/sdk/CopilotSessionTest.java

@@ -7,6 +7,7 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.junit.jupiter.api.Assertions.fail;
 
@@ -821,4 +822,31 @@ void testSessionListFilterFluentAPI() throws Exception {
             session.close();
         }
     }
+
+    /**
+     * Verifies that getSessionMetadata returns metadata for a known session ID.
+     *
+     * @see Snapshot: session/should_get_session_metadata_by_id
+     */
+    @Test
+    void testShouldGetSessionMetadataById() throws Exception {
+        ctx.configureForTest("session", "should_get_session_metadata_by_id");
+
+        try (CopilotClient client = ctx.createClient()) {
+            var session = client
+                    .createSession(new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL)).get();
+
+            session.sendAndWait(new MessageOptions().setPrompt("Say hello")).get(60, TimeUnit.SECONDS);
+
+            var metadata = client.getSessionMetadata(session.getSessionId()).get(30, TimeUnit.SECONDS);
+            assertNotNull(metadata, "Metadata should not be null for known session");
+            assertEquals(session.getSessionId(), metadata.getSessionId(), "Metadata session ID should match");
+
+            // A non-existent session should return null
+            var notFound = client.getSessionMetadata("non-existent-session-id").get(30, TimeUnit.SECONDS);
+            assertNull(notFound, "Non-existent session should return null");
+
+            session.close();
+        }
+    }
 }