java-coding-skill

name java-coding-skill description Use this skill whenever editing `*.java` files in the `java/` directore of the SDK in order to write idiomatic, well-structured Java code for the Copilot SDK Java Coding Skill Core Principles Requires Java 25 or later for building the jar artifact for Copilot SDK for java. Uses the Multi-Relase jar feature JEP 238 https://openjdk.org/jeps/238 with maven.compiler.release 17 so that uses running JDK 17 can use the jar. Requires GitHub Copilot CLI installed and in PATH. Uses CompletableFuture for all async operations. Implements AutoCloseable for resource cleanup (try-with-resources). Installation Maven < dependency > < groupId > com.github </ groupId > < artifactId > copilot-sdk-java </ artifactId > < version > ${copilot-sdk-java.version} </ version > </ dependency > Gradle implementation "com.github:copilot-sdk-java:${copilotSdkJavaVersion}" Client Initialization Basic Client Setup try ( var client = new CopilotClient ()) { client.start().get(); // Use client... } Client Configuration Options When creating a CopilotClient, use CopilotClientOptions : cliPath - Path to CLI executable (default: "copilot" from PATH) cliArgs - Extra arguments prepended before SDK-managed flags cliUrl - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process port - Server port (default: 0 for random, only when useStdio is false) useStdio - Use stdio transport instead of TCP (default: true) logLevel - Log level: "error", "warn", "info", "debug", "trace" (default: "info") autoStart - Auto-start server on first request (default: true) autoRestart - Auto-restart on crash (default: true) cwd - Working directory for the CLI process environment - Environment variables for the CLI process gitHubToken - GitHub token for authentication useLoggedInUser - Use logged-in gh CLI auth (default: true unless token provided) onListModels - Custom model list handler for BYOK scenarios var options = new CopilotClientOptions () .setCliPath( "/path/to/copilot" ) .setLogLevel( "debug" ) .setAutoStart( true ) .setAutoRestart( true ) .setGitHubToken(System.getenv( "GITHUB_TOKEN" )); try ( var client = new CopilotClient (options)) { client.start().get(); // Use client... } Manual Server Control For explicit control: var client = new CopilotClient ( new CopilotClientOptions ().setAutoStart( false )); client.start().get(); // Use client... client.stop().get(); Use forceStop() when stop() takes too long. Session Management Creating Sessions Use SessionConfig for configuration. The permission handler is required : var session = client.createSession( new SessionConfig () .setModel( "gpt-5" ) .setStreaming( true ) .setTools(List.of(...)) .setSystemMessage( new SystemMessageConfig () .setMode(SystemMessageMode.APPEND) .setContent( "Custom instructions" )) .setAvailableTools(List.of( "tool1" , "tool2" )) .setExcludedTools(List.of( "tool3" )) .setProvider( new ProviderConfig ().setType( "openai" )) .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) ).get(); Session Config Options sessionId - Custom session ID clientName - Application name model - Model name ("gpt-5", "claude-sonnet-4.5", etc.) reasoningEffort - "low", "medium", "high", "xhigh" tools - Custom tools exposed to the CLI systemMessage - System message customization availableTools - Allowlist of tool names excludedTools - Blocklist of tool names provider - Custom API provider configuration (BYOK) streaming - Enable streaming response chunks (default: false) workingDirectory - Session working directory mcpServers - MCP server configurations customAgents - Custom agent configurations agent - Pre-select agent by name infiniteSessions - Infinite sessions configuration skillDirectories - Skill SKILL.md directories disabledSkills - Skills to disable configDir - Config directory path hooks - Session lifecycle hooks onPermissionRequest - REQUIRED permission handler onUserInputRequest - User input handler onEvent - Event handler registered before session creation All setters return SessionConfig for method chaining. Resuming Sessions var session = client.resumeSession(sessionId, new ResumeSessionConfig () .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) ).get(); Session Operations session.getSessionId() - Get session identifier session.send(prompt) / session.send(MessageOptions) - Send message, returns message ID session.sendAndWait(prompt) / session.sendAndWait(MessageOptions) - Send and wait for response (60s timeout) session.sendAndWait(options, timeoutMs) - Send and wait with custom timeout session.abort() - Abort current processing session.getMessages() - Get all events/messages session.setModel(modelId) - Switch to a different model session.log(message) / session.log(message, "warning", false) / session.log(message, "error", false) - Log to session timeline with level "info" , "warning" , or "error" session.close() - Clean up resources Event Handling Event Subscription Pattern Use CompletableFuture for waiting on session events: var done = new CompletableFuture <Void>(); session.on(event -> { if (event instanceof AssistantMessageEvent msg) { System.out.println(msg.getData().content()); } else if (event instanceof SessionIdleEvent) { done.complete( null ); } }); session.send( new MessageOptions ().setPrompt( "Hello" )); done.get(); Type-Safe Event Handling Use the typed on() overload for compile-time safety: session.on(AssistantMessageEvent.class, msg -> { System.out.println(msg.getData().content()); }); session.on(SessionIdleEvent.class, idle -> { done.complete( null ); }); Unsubscribing from Events The on() method returns a Closeable : var subscription = session.on(event -> { /* handler */ }); // Later... subscription.close(); Event Types Use pattern matching (Java 17+) for event handling: session.on(event -> { if (event instanceof UserMessageEvent userMsg) { // Handle user message } else if (event instanceof AssistantMessageEvent assistantMsg) { System.out.println(assistantMsg.getData().content()); } else if (event instanceof AssistantMessageDeltaEvent delta) { System.out.print(delta.getData().deltaContent()); } else if (event instanceof ToolExecutionStartEvent toolStart) { // Tool execution started } else if (event instanceof ToolExecutionCompleteEvent toolComplete) { // Tool execution completed } else if (event instanceof SessionStartEvent start) { // Session started } else if (event instanceof SessionIdleEvent idle) { // Session is idle (processing complete) } else if (event instanceof SessionErrorEvent error) { System.err.println( "Error: " + error.getData().message()); } }); Event Error Handling Control how errors in event handlers are handled: // Set a custom error handler session.setEventErrorHandler(ex -> { logger.error( "Event handler error" , ex); }); // Or set the error propagation policy session.setEventErrorPolicy(EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS); Streaming Responses Enabling Streaming Set streaming(true) in SessionConfig: var session = client.createSession( new SessionConfig () .setModel( "gpt-5" ) .setStreaming( true ) .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) ).get(); Handling Streaming Events Handle both delta events (incremental) and final events: var done = new CompletableFuture <Void>(); session.on(event -> { switch (event) { case AssistantMessageDeltaEvent delta -> // Incremental text chunk System.out.print(delta.getData().deltaContent()); case AssistantReasoningDeltaEvent reasoningDelta -> // Incremental reasoning chunk (model-dependent) System.out.print(reasoningDelta.getData().deltaContent()); case AssistantMessageEvent msg -> // Final complete message System.out.println( "\n--- Final ---\n" + msg.getData().content()); case AssistantReasoningEvent reasoning -> // Final reasoning content System.out.println( "--- Reasoning ---\n" + reasoning.getData().content()); case SessionIdleEvent idle -> done.complete( null ); default -> { } } }); session.send( new MessageOptions ().setPrompt( "Tell me a story" )); done.get(); Note: Final events ( AssistantMessageEvent , AssistantReasoningEvent ) are ALWAYS sent regardless of streaming setting. Custom Tools Defining Tools Use ToolDefinition.create() with JSON Schema parameters and a ToolHandler : var tool = ToolDefinition.create( "get_weather" , "Get weather for a location" , Map.of( "type" , "object" , "properties" , Map.of( "location" , Map.of( "type" , "string" , "description" , "City name" ) ), "required" , List.of( "location" ) ), invocation -> { String location = (String) invocation.getArguments().get( "location" ); return CompletableFuture.completedFuture( "Sunny in " + location); } ); var session = client.createSession( new SessionConfig () .setModel( "gpt-5" ) .setTools(List.of(tool)) .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) ).get(); Type-Safe Tool Arguments Use getArgumentsAs() for deserialization into a typed record or class: record WeatherArgs (String location, String unit) {} var tool = ToolDefinition.create( "get_weather" , "Get weather for a location" , Map.of( "type" , "object" , "properties" , Map.of( "location" , Map.of( "type" , "string" ), "unit" , Map.of( "type" , "string" , "enum" , List.of( "celsius" , "fahrenheit" )) ), "required" , List.of( "location" ) ), invocation -> { var args = invocation.getArgumentsAs(WeatherArgs.class); return CompletableFuture.completedFuture( Map.of( "temp" , 72 , "unit" , args.unit(), "location" , args.location()) ); } ); Overriding Built-In Tools var override = ToolDefinition.createOverride( "built_in_tool_name" , "Custom description" , Map.of( "type" , "object" , "properties" , Map.of(...)), invocation -> CompletableFuture.completedFuture( "custom result" ) ); Tool Return Types Return any JSON-serializable value (String, Map, List, record, POJO) The SDK automatically serializes the return value and sends it back to the CLI Tool Execution Flow When Copilot invokes a tool, the client automatically: Deserializes the arguments Runs your handler function Serializes the return value Responds to the CLI Permission Handling Required Permission Handler A permission handler is mandatory when creating or resuming sessions: // Approve all requests (for development/testing) new SessionConfig () .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) // Custom permission logic new SessionConfig () .setOnPermissionRequest((request, invocation) -> { if ( "dangerous-action" .equals(request.getKind())) { return CompletableFuture.completedFuture( new PermissionRequestResult ().setKind(PermissionRequestResultKind.DENIED) ); } return CompletableFuture.completedFuture( new PermissionRequestResult ().setKind(PermissionRequestResultKind.APPROVED) ); }) User Input Handling Handle user input requests from the agent: new SessionConfig () .setOnUserInputRequest((request, invocation) -> {