Integrate Bruno's PR 1478 with Ed's desired CI/CD changes (#1483)

Bruno authored the core code with Copilot.

* feat(java): add JDK 25 default executor

Use a multi-release JAR to select virtual threads as the default internal executor on JDK 25+, while retaining the common pool on older JDKs. Keep user-provided executors caller-owned and only shut down SDK-owned defaults.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* test(java): cover owned default executor shutdown

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor(java): make default executor provider internal

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor(java): update InternalExecutorProvider to manage executor ownership and shutdown capability

* feat(java): add integration tests for multi-release JAR behavior and executor management

* feat(java): add JDK 25 multi-release overlay class verification and update documentation

* test(java): split InternalExecutorProvider unit test into single-assertion tests

Addresses PR #1478 review (Copilot AI): the existing
baseProviderUsesCommonPoolWithoutOwnership method bundled three unrelated
assertions (commonPool identity, user-executor ownership, package-private
visibility). Split into baseProviderReturnsCommonPool,
userProvidedExecutorIsNotOwned, and providerIsPackagePrivate so failures
point at a single condition each.

* fix(java): dispatch owned-executor shutdown off the executor in forceStop()

Addresses PR #1478 review (Copilot AI, discussion r3314987809):
CopilotClient#forceStop() chains shutdownOwnedExecutor() onto cleanupConnection()
via whenComplete(...), but cleanupConnection() is itself built on async work
scheduled on the SDK-owned executor (e.g. CompletableFuture.supplyAsync(...,
executor) in connection setup). On JDK 25+ this means the whenComplete lambda
can land on one of the owned executor's threads; awaitTermination(...) then
blocks waiting for the very thread it is running on, forcing the full
AUTOCLOSEABLE_TIMEOUT_SECONDS timeout followed by shutdownNow().

Fix: dispatch the shutdown continuation via whenCompleteAsync(...) onto a
private one-shot SHUTDOWN_DISPATCHER that spawns a fresh daemon thread named
"copilot-client-shutdown". This guarantees the awaitTermination call is never
made from inside the executor it is draining.

close() is unaffected: it calls stop().get(...) synchronously and runs
shutdownOwnedExecutor() in its finally block on the caller's thread.

* fix(java): short-circuit shutdownOwnedExecutor() when already shut down

Addresses PR #1478 review (Copilot AI, discussion r3314987870):
close() and forceStop() can each invoke shutdownOwnedExecutor() (e.g. user
calls forceStop() and then close() in try-with-resources). A second call
would redundantly invoke shutdown() and awaitTermination() on an already-
terminated ExecutorService. While the JDK handles this gracefully
(awaitTermination returns immediately after a prior shutdownNow), the redundant
call obscures diagnostics.

Short-circuit at the top of shutdownOwnedExecutor() when isShutdown() is
already true and log at FINE so the second invocation is visible without
spamming normal output.

* spotless:apply

* ci(java): build/publish on JDK 25 to include MR-JAR overlay; matrix SDK tests across JDK 17 and 25

The java25-multi-release Maven profile is activated only on JDK 25+
(<jdk>[25,)</jdk>). Without it, the build skips the compile-java25 execution,
the packaged JAR has no META-INF/versions/25/InternalExecutorProvider.class,
and the manifest lacks Multi-Release: true. The InternalExecutorProvider
JDK 25 overlay (Executors.newVirtualThreadPerTaskExecutor()) is then
effectively dead in CI and in published Maven Central artifacts -- consumers
on JDK 25+ silently fall back to ForkJoinPool.commonPool().

Changes:
- java-publish-snapshot.yml: set up JDK 25 (was 17). The pom keeps
  <maven.compiler.release>17</maven.compiler.release> so baseline bytecode
  remains JDK 17 compatible; --release 17 is supported by the JDK 25
  compiler.
- java-publish-maven.yml: same JDK bump for release:perform.
- java-sdk-tests.yml: matrix on java-version: [17, 25]. JDK 25 entry
  exercises the MR-JAR overlay end-to-end via InternalExecutorProviderIT
  (asserts feature >= 25 => canBeShutdown=true, virtual=true) and runs the
  new verify-java25-overlay antrun structural guard. Side-effects (site
  artifact upload, JaCoCo badge generation, badge-update PR) remain gated to
  the JDK 17 entry so the badge source-of-truth stays a single baseline.
  Failure artifact name suffixed with -jdk${matrix.java-version} to avoid
  collisions.

Branch protection note: the job's check name changes from "Java SDK Tests"
to "Java SDK Tests (JDK 17)" + "Java SDK Tests (JDK 25)". Update branch
protection rules accordingly after merge if required-checks reference the
old name.

* On branch edburns/review-brunoborges-pr-1478 Test invocation changes.
modified:   .github/workflows/java-sdk-tests.yml

- Have `test-jdk17` be a parameter, set to true by default.

- Do not use matrix. It is vital that the tests verify that the MR-JAR facility works when compiled using JDK 25 with `maven.compiler.release` set to 17. To that end, this workflow does not re-compile the jar or the tests, but uses a the JDK 17 just to run the tests.

- Use a separate banner for each variant.

- Use separate summary for 17 and 25 tests.

modified:   java/pom.xml

- Print banners for inspection during tests.

- Use Maven enforcer plugin to require using 25 when compiling.

modified:   java/README.md

- Add content for running the tests with 17.

* On branch edburns/review-brunoborges-pr-1478
modified:   .github/workflows/docs-validation.yml

- Use Java 25 per @brunoborges.

modified:   .github/workflows/java-sdk-tests.yml

- Update labels.

modified:   .vscode/settings.json

- Additional Java settings.

modified:   scripts/docs-validation/package.json

   The `--lang` parsing in validate.ts uses `args.find((a) => a.startsWith("--lang="))`, which won't match `--lang typescript` (space-separated). So `targetLang` is always `undefined`, and every job validates **all** languages. This is a pre-existing bug — but it was invisible before because `mvn install` succeeded with the pre-installed JDK 17 on all runners.

   However, the reason it matters **now** is: after fixing the `validate-java` job to use JDK 25, the other 4 jobs (TypeScript, Go, Python, C#) still don't have JDK 25. Since they also accidentally validate Java (due to the broken `--lang` filter), they'd continue to fail.

   So you actually have two options:

   **Option A:** Only fix JDK in `validate-java` AND fix `--lang` parsing so other jobs stop accidentally validating Java.

   **Option B:** Only fix JDK in `validate-java` AND add JDK 25 setup to all 4 other jobs too (ugly but works without touching the script).

   The `--lang` fix is the cleaner path, but it's a separate pre-existing bug, not something introduced by PR #1483. If you'd prefer to keep the changes minimal and just address the PR's breakage, I can revert the package.json change and instead add `setup-java` with JDK 25 to every job. What's your preference?

* On branch edburns/review-brunoborges-pr-1478
modified:   .github/actions/java-test-report/action.yml
modified:   .github/workflows/java-sdk-tests.yml

- Ensure the correct Copilot CLI is used for tests.

* On branch edburns/review-brunoborges-pr-1478
modified:   .github/workflows/java-sdk-tests.yml

Now the JDK 17 run:
1. `jacoco:prepare-agent@wire-up-coverage-instrumentation` — generates the JaCoCo agent arg compatible with JDK 17 and sets `testExecutionAgentArgs`
2. `antrun:run@print-test-jdk-banner` — prints the JDK banner
3. `surefire:test` — runs pre-compiled tests with the JaCoCo agent attached
4. `jacoco:report@build-coverage-report-from-tests` — generates the HTML/XML/CSV reports

The `-DtestExecutionAgentArgs=` override is removed so JaCoCo's prepared value flows through to Surefire's `<argLine>`. The test report action already reads from the default jacoco.xml path, so the coverage section will appear in both reports automatically.

* On branch edburns/review-brunoborges-pr-1478 Address copilot review comments.
modified:   .github/actions/java-test-report/action.yml

- Add failsafe tests to the report.

modified:   .github/workflows/java-sdk-tests.yml

- Ensure failsafe tests are invoked in the 17 case.

modified:   java/README.md

- Fix spelling error.

- Fix artifact version error.

- Fix 17 invocation.

* Ensure the Jar is produced

---------

Co-authored-by: Bruno Borges <brborges@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 4 people

.github/actions/java-test-report/action.yml

@@ -4,7 +4,7 @@ inputs:
   report-path:
     description: "Path to the test report XML files (glob pattern)"
     required: false
-    default: "java/target/surefire-reports*/TEST-*.xml"
+    default: "java/target/{surefire-reports*,failsafe-reports}/TEST-*.xml"
   jacoco-path:
     description: "Path to the JaCoCo XML report"
     required: false
@@ -17,13 +17,17 @@ inputs:
     description: "Name for the check run"
     required: false
     default: "Java SDK Test Results"
+  title:
+    description: "Title for the test report summary"
+    required: false
+    default: "Copilot Java SDK :: Test Results"
 runs:
   using: "composite"
   steps:
     - name: Generate Test Summary
       shell: bash
       run: |
-        echo "## 🧪 Copilot Java SDK :: Test Results" >> $GITHUB_STEP_SUMMARY
+        echo "## 🧪 ${{ inputs.title }}" >> $GITHUB_STEP_SUMMARY
         echo "" >> $GITHUB_STEP_SUMMARY
 
         if ls ${{ inputs.report-path }} 1>/dev/null 2>&1; then

.github/workflows/docs-validation.yml

@@ -143,7 +143,7 @@ jobs:
       - uses: actions/setup-java@v4
         with:
           distribution: 'microsoft'
-          java-version: '17'
+          java-version: '25'
           cache: 'maven'
 
       - name: Install SDK to local repo

.github/workflows/java-publish-maven.yml

@@ -54,10 +54,10 @@ jobs:
 
       - uses: ./.github/actions/setup-copilot
 
-      - name: Set up JDK 17
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
         with:
-          java-version: "17"
+          java-version: "25"
           distribution: "microsoft"
           cache: "maven"
           server-id: central

.github/workflows/java-publish-snapshot.yml

@@ -30,10 +30,10 @@ jobs:
 
       - uses: ./.github/actions/setup-copilot
 
-      - name: Set up JDK 17
+      - name: Set up JDK 25
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
         with:
-          java-version: "17"
+          java-version: "25"
           distribution: "microsoft"
           cache: "maven"
           server-id: central

.github/workflows/java-sdk-tests.yml

@@ -37,10 +37,14 @@ permissions:
 
 jobs:
   java-sdk:
-    name: "Java SDK Tests"
+    name: "Java SDK Tests (JDK ${{ matrix.test-jdk }})"
     if: github.event.repository.fork == false
 
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        test-jdk: ["25", "17"]
     defaults:
       run:
         shell: bash
@@ -52,22 +56,26 @@ jobs:
 
       - uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
         with:
-          java-version: "17"
+          java-version: "25"
           distribution: "microsoft"
           cache: "maven"
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: 22
 
-      - uses: ./.github/actions/setup-copilot
-        id: setup-copilot
+      - name: Build SDK and set up test harness
+        run: mvn test-compile jar:jar
+
+      - name: Verify Javadoc generation
+        if: matrix.test-jdk == '25'
+        run: mvn javadoc:javadoc -q
 
-      - name: Install test harness dependencies
-        working-directory: ./test/harness
-        run: npm ci --ignore-scripts
+      - name: Verify CLI works
+        run: node target/copilot-sdk/nodejs/node_modules/@github/copilot/index.js --version
 
       - name: Run spotless check
+        if: matrix.test-jdk == '25'
         run: |
           mvn spotless:check
           if [ $? -ne 0 ]; then
@@ -76,18 +84,30 @@ jobs:
           fi
           echo "✅ spotless:check passed"
 
-      - name: Verify Javadoc generation
-        run: mvn compile javadoc:javadoc -q
+      - name: Run Java SDK tests (JDK 25)
+        if: matrix.test-jdk == '25'
+        env:
+          CI: "true"
+        run: mvn verify -Dskip.test.harness=true
 
-      - name: Run Java SDK tests
+      - name: Switch to JDK 17
+        if: matrix.test-jdk == '17'
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5
+        with:
+          java-version: "17"
+          distribution: "microsoft"
+
+      - name: Run Java SDK tests (JDK 17, no recompilation)
+        if: matrix.test-jdk == '17'
         env:
           CI: "true"
-          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
-          COPILOT_CLI_PATH: ${{ steps.setup-copilot.outputs.cli-path }}
-        run: mvn verify
+        run: |
+          echo "Running tests against JDK 25-built classes using JDK 17 runtime..."
+          java -version
+          mvn jacoco:prepare-agent@wire-up-coverage-instrumentation antrun:run@print-test-jdk-banner surefire:test failsafe:integration-test failsafe:verify jacoco:report@build-coverage-report-from-tests -Denforcer.skip=true
 
       - name: Upload test results for site generation
-        if: success() && github.ref == 'refs/heads/main'
+        if: success() && github.ref == 'refs/heads/main' && matrix.test-jdk == '25'
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: test-results-for-site
@@ -98,12 +118,12 @@ jobs:
           retention-days: 1
 
       - name: Generate JaCoCo badge
-        if: success() && github.ref == 'refs/heads/main'
+        if: success() && github.ref == 'refs/heads/main' && matrix.test-jdk == '25'
         working-directory: .
         run: .github/scripts/generate-java-coverage-badge.sh java/target/site/jacoco-coverage/jacoco.csv .github/badges
 
       - name: Create PR for JaCoCo badge update
-        if: success() && github.ref == 'refs/heads/main'
+        if: success() && github.ref == 'refs/heads/main' && matrix.test-jdk == '25'
         uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v7
         with:
           commit-message: "Update Java JaCoCo coverage badge"
@@ -116,12 +136,14 @@ jobs:
       - name: Generate Test Report Summary
         if: always()
         uses: ./.github/actions/java-test-report
+        with:
+          title: "Copilot Java SDK :: Test Results JDK ${{ matrix.test-jdk }}"
 
       - name: Upload test results on failure
         if: failure()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
-          name: java-test-results
+          name: java-test-results-jdk-${{ matrix.test-jdk }}
           path: |
             java/target/surefire-reports/
             java/target/surefire-reports-isolated/

.vscode/settings.json

@@ -25,5 +25,6 @@
   "[go]": {
     "editor.defaultFormatter": "golang.go"
   },
-  "java.configuration.updateBuildConfiguration": "automatic"
+  "java.configuration.updateBuildConfiguration": "automatic",
+  "java.compile.nullAnalysis.mode": "automatic"
 }

java/README.md

@@ -19,21 +19,27 @@ Java SDK for programmatic control of GitHub Copilot CLI, enabling you to build A
 
 ## Installation
 
-### Requirements
+### Runtime 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 CLI 1.0.17 or later installed and in `PATH` (or provide custom `cliPath`)
+- Java 17 or later. **JDK 25 recommended**. The distributed jar is a multi-release jar (MR-JAR) and is compiled on JDK 25 with `maven.compiler.release` set to 17. This means, when run on JDK 25 and later, the SDK automatically uses virtual threads for its default internal executor.
+- GitHub Copilot CLI 1.0.55-5. or later installed and in `PATH` (or provide custom `cliPath`)
 
 ### Maven
 
 ```xml
 <dependency>
     <groupId>com.github</groupId>
     <artifactId>copilot-sdk-java</artifactId>
-    <version>1.0.0-beta-java.4</version>
+    <version>1.0.0-beta-10-java.0</version>
 </dependency>
 ```
 
+### Gradle
+
+```groovy
+implementation 'com.github:copilot-sdk-java:1.0.0-beta-10-java.0'
+
+
 #### Snapshot Builds
 
 Snapshot builds of the next development version are published to Maven Central Snapshots. To use them, add the repository and update the dependency version in your `pom.xml`:
@@ -50,14 +56,14 @@ Snapshot builds of the next development version are published to Maven Central S
 <dependency>
     <groupId>com.github</groupId>
     <artifactId>copilot-sdk-java</artifactId>
-    <version>1.0.0-beta-java.5-SNAPSHOT</version>
+    <version>1.0.0-beta-10-java.0-SNAPSHOT</version>
 </dependency>
 ```
 
 ### Gradle
 
 ```groovy
-implementation 'com.github:copilot-sdk-java:1.0.0-beta-java.4'
+implementation 'com.github:copilot-sdk-java:1.0.0-beta-10-java.0-SNAPSHOT'
 ```
 
 ## Quick Start
@@ -66,23 +72,16 @@ implementation 'com.github:copilot-sdk-java:1.0.0-beta-java.4'
 import com.github.copilot.CopilotClient;
 import com.github.copilot.generated.AssistantMessageEvent;
 import com.github.copilot.generated.SessionUsageInfoEvent;
-import com.github.copilot.rpc.CopilotClientOptions;
 import com.github.copilot.rpc.MessageOptions;
 import com.github.copilot.rpc.PermissionHandler;
 import com.github.copilot.rpc.SessionConfig;
 
-import java.util.concurrent.Executors;
-
 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)) {
+        try (var client = new CopilotClient()) {
             client.start().get();
 
             // Create a session
@@ -160,6 +159,8 @@ This SDK tracks the official [Copilot SDK](https://github.com/github/copilot-sdk
 
 ### Development Setup
 
+Requires JDK 25 or later for development.
+
 ```bash
 # Clone the repository
 git clone https://github.com/github/copilot-sdk.git
@@ -168,8 +169,12 @@ cd copilot-sdk/java
 # Enable git hooks for code formatting
 git config core.hooksPath .githooks
 
-# Build and test
+# Build and test with JDK 25
 mvn clean verify
+
+# Set your paths for JDK 17
+# Run the JDK 25 built jar with JDK 17 JVM for tests. Do not re-compile the jar.
+mvn jacoco:prepare-agent@wire-up-coverage-instrumentation antrun:run@print-test-jdk-banner surefire:test failsafe:integration-test failsafe:verify jacoco:report@build-coverage-report-from-tests -Denforcer.skip=true
 ```
 
 The tests require the official [copilot-sdk](https://github.com/github/copilot-sdk) test harness, which is automatically cloned during build.
@@ -190,6 +195,3 @@ See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities.
 
 MIT — see [LICENSE](LICENSE) for details.
 
-## Acknowledgement
-
-- Initially developed with Copilot and [Bruno Borges](https://www.linkedin.com/in/brunocborges/).