Prepare for archiving of copilot-sdk-java repo in favor of java directory in copilot-sdk#1811
Open
edburns wants to merge 4 commits into
Open
Conversation
…tory in copilot-sdk
github-actions
Bot
added
instructions
### 16:37 Prompt
I have added `copilot-sdk-00` to this VS Code workspace. The `copilot-sdk-00/java` directory **is** the Copilot SDK for which this `copilot-sdk-java.instructions.md` is the instructions.
Do a deep read of the source code in `copilot-sdk-00/java`.
Do a deep read of the existing `copilot-sdk-java.instructions.md`.
Suggest any updates based on what should be changed in `copilot-sdk-java.instructions.md`, based on your findings.
### 16:51 Response
Now I have a comprehensive picture. Let me summarize the findings and suggest updates:
---
Based on my deep read of the Java SDK source code and the current copilot-sdk-java.instructions.md, here are the updates I'd suggest:
## Issues Found
### 1. Incorrect: `session.setModel()` documentation is slightly wrong
The instructions show `session.setModel(modelId)` — this is actually correct (it exists on CopilotSession), but the full signatures should be documented:
- `setModel(String model)`
- `setModel(String model, String reasoningEffort)`
- `setModel(String model, String reasoningEffort, ModelCapabilitiesOverride modelCapabilities)` *(since 1.3.0)*
### 2. Incorrect: `PreToolUseHookOutput` API
The instructions show:
```java
var decision = new PreToolUseHookOutput().setKind("allow");
```
But actually `PreToolUseHookOutput` is a **record** with static factory methods:
- `PreToolUseHookOutput.allow()`
- `PreToolUseHookOutput.deny()`
- `PreToolUseHookOutput.deny(String reason)`
- `PreToolUseHookOutput.ask()`
### 3. Missing: `CopilotClientOptions` fields not documented
These are in the source but not in the instructions:
- `setRemote(boolean)` — Mission Control integration
- `setTelemetry(TelemetryConfig)` — OpenTelemetry export *(since 1.2.0)*
- `setSessionIdleTimeoutSeconds(int)` — Idle timeout *(since 1.3.0)*
- `setExecutor(Executor)` — Custom thread pool
- `setTcpConnectionToken(String)` — TCP security token
### 4. Missing: `ToolDefinition.createSkipPermission()`
A third factory method exists *(since 1.2.0)* that skips the CLI permission request entirely. The instructions only mention `create()` and `createOverride()`.
### 5. Missing: Session listing with filters
The instructions show `client.listSessions()` but don't mention the overload with `SessionListFilter` that can filter by `cwd`, `gitRoot`, `repository`, and `branch`.
### 6. Missing: `session.log()` with URL
The instructions show `log(message, level, ephemeral)` but there's also a 4-param overload:
```java
session.log(String message, String level, Boolean ephemeral, String url)
```
### 7. Missing: MCP Server Configuration
The instructions mention `setMcpServers()` in the SessionConfig options list but don't show how to configure them. There are two types:
- `McpStdioServerConfig` — Local/stdio-based servers
- `McpHttpServerConfig` — HTTP/SSE remote servers
### 8. Missing: Cloud Sessions / Remote features
The `setRemote(boolean)` option on client options and per-session GitHub token support for cloud/content-exclusion scenarios.
### 9. Missing: `ModelCapabilitiesOverride`
Vision/image support can be controlled via model capabilities override, but this isn't documented.
### 10. Missing: `EventErrorPolicy` enum values
The instructions mention `EventErrorPolicy.SUPPRESS_AND_LOG_ERRORS` but don't list the other value: `PROPAGATE_AND_LOG_ERRORS` (which is the default).
### 11. Missing: `onLifecycle()` typed overload
There's also `onLifecycle(String eventType, SessionLifecycleHandler handler)` for filtering specific lifecycle events.
### 12. Minor: `send()` return type
`session.send()` returns `CompletableFuture<String>` (the message ID), which is worth mentioning since it can be used for correlation.
---
## Recommended Priority
**High priority** (incorrect info):
- Fix github#2 (`PreToolUseHookOutput` API)
**Medium priority** (missing important features):
- Add github#4 (`createSkipPermission`)
- Add github#7 (MCP server configuration examples)
- Add github#3 (missing client options)
- Add github#5 (session list filters)
**Low priority** (nice-to-have completeness):
- Expand github#1 (setModel overloads)
- Add github#6 (log with URL)
- Add github#9-12 (minor additions)
Would you like me to apply any or all of these updates to the file?
### 16:52 Prompt
Yes. Apply all of these.
### 16:54 Response
Created 12 todos
Now I have the full file. Let me apply all the changes:
Starting: *Fix PreToolUseHookOutput API (incorrect)* (1/12)
Replacing 84 lines with 199 lines in [](file:///e%3A/workareas/awesome-copilot-00/instructions/copilot-sdk-java.instructions.md)
```
```
Completed: *Fix PreToolUseHookOutput API (incorrect)* (1/12)
All 12 updates have been applied to copilot-sdk-java.instructions.md:
1. **Fixed** `PreToolUseHookOutput` — now uses correct static factory methods (`allow()`, `deny()`, `ask()`) instead of the incorrect `new PreToolUseHookOutput().setKind("allow")`
2. **Added** `ToolDefinition.createSkipPermission()` section (since 1.2.0)
3. **Added** 5 missing `CopilotClientOptions` fields: `remote`, `telemetry`, `sessionIdleTimeoutSeconds`, `executor`, `tcpConnectionToken`
4. **Added** `SessionListFilter` with `setRepository()`, `setBranch()`, `setCwd()`, `setGitRoot()`
5. **Expanded** `setModel()` to show all 3 overloads (model, reasoning effort, capabilities)
6. **Added** `log(message, level, ephemeral, url)` overload
7. **Added** full MCP server configuration section with `McpStdioServerConfig` and `McpHttpServerConfig` examples
8. **Added** `EventErrorPolicy` enum values with explanations
9. **Added** `onLifecycle(String eventType, handler)` filtered overload
10. **Added** note that `send()` returns `CompletableFuture<String>` (message ID for correlation)
11. **Added** `ModelCapabilitiesOverride` section with vision/limits configuration (since 1.3.0)
12. **Added** `remote` option for Mission Control / cloud session integration
13. **Bonus:** Expanded `SessionHooks` example to include all 5 hook types (`onPreToolUse`, `onPostToolUse`, `onUserPromptSubmitted`, `onSessionStart`, `onSessionEnd`)
Made changes.
### 16:54 Prompt
In the "## Core Principles" section. Add a bullet point that describes how `Optional` is used in the API.
### 16:58 Response
Searched for text `Optional` (`copilot-sdk-00` · `java/src/main/java/com/github/copilot/sdk/json/*.java`), 10 results
Searched for text `Optional` (`copilot-sdk-00` · `java/src/main/java/com/github/copilot/sdk/json/InfiniteSessionConfig.java`), 13 results
Replacing 7 lines with 8 lines in [](file:///e%3A/workareas/awesome-copilot-00/instructions/copilot-sdk-java.instructions.md)
```
```
Added the bullet point describing how `Optional<T>`, `OptionalInt`, and `OptionalDouble` are used on config class getters to distinguish "not set" from explicit values, while setters accept raw types and return `this` for fluent chaining.
Made changes.
### 16:58 Prompt
Consider this code from the Java README.
```java
public class CopilotSDK {
public static void main(String[] args) throws Exception {
var lastMessage = new String[]{null};
// Create and start client
try (var client = new CopilotClient()) { // JDK 25+: comment out this line
// JDK 25+: uncomment the following 3 lines for virtual thread support
// var options = new CopilotClientOptions()
// .setExecutor(Executors.newVirtualThreadPerTaskExecutor());
// try (var client = new CopilotClient(options)) {
client.start().get();
// Create a session
var session = client.createSession(
new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5")).get();
// Handle assistant message events
session.on(AssistantMessageEvent.class, msg -> {
lastMessage[0] = msg.getData().content();
System.out.println(lastMessage[0]);
});
// Handle session usage info events
session.on(SessionUsageInfoEvent.class, usage -> {
var data = usage.getData();
System.out.println("\n--- Usage Metrics ---");
System.out.println("Current tokens: " + data.currentTokens().intValue());
System.out.println("Token limit: " + data.tokenLimit().intValue());
System.out.println("Messages count: " + data.messagesLength().intValue());
});
// Send a message
var completable = session.sendAndWait(new MessageOptions().setPrompt("What is 2+2?"));
// and wait for completion
completable.get();
}
boolean success = lastMessage[0] != null && lastMessage[0].contains("4");
System.exit(success ? 0 : -1);
}
}
```
I want to get across the very important JDK 25 comment. What's the best place to encode that knowledge in the instructions?
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Adds a new instruction document for the GitHub Copilot SDK for Java and surfaces it in the docs index so users can discover/install it.
Changes:
- Introduces
copilot-sdk-java.instructions.mdwith setup, session/event patterns, tools, and configuration guidance. - Updates the docs instructions index to include the new Java instructions entry.
Show a summary per file
| File | Description |
|---|---|
| instructions/copilot-sdk-java.instructions.md | New Java SDK instruction set covering installation, client/session lifecycle, streaming, tools, and hooks. |
| docs/README.instructions.md | Adds the Java instructions row to the instructions table with install links. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 6
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pull Request Checklist
npm startand verified thatREADME.mdis up to date.stagedbranch for this pull request.Description
Copy https://github.com/github/copilot-sdk-java/blob/aa96214a99b3e00482bf12cd46c93be4d231e179/instructions/copilot-sdk-java.instructions.md to this repo in anticipation of the archiving of that repo.
Type of Contribution
Additional Notes
See https://github.com/github/copilot-sdk-partners/issues/80 .
By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.