Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (73 loc) · 4.22 KB

AGENTS.md

File metadata and controls

89 lines (73 loc) · 4.22 KB
Raw

Java SDK

This directory is the Java SDK's Maven reactor. Paths and commands below are relative to this directory, whether it is nested at src/sdk/java or exported as java. Keep API usage examples in README.md, the SDK documentation, and public Javadoc rather than duplicating them in these contributor instructions.

Layout and compatibility

  • sdk/src/main/java/ contains the handwritten client, session, and RPC APIs. sdk/src/test/java/ contains unit and integration tests.
  • sdk/src/generated/java/ contains generated protocol and event types.
  • copilot-native/ packages platform-specific runtime artifacts separately from the pure-Java SDK.
  • Build with JDK 25 or later, as required by sdk/pom.xml. The base sources target Java 17; Java 25-specific implementations belong in the existing sdk/src/main/java25/ multi-release overlay. Do not raise the base target or introduce newer APIs into the Java 17 sources.

API conventions

  • Preserve the CompletableFuture-based asynchronous API and fluent setters on configuration classes. Preserve wire names and serialization behavior when changing RPC types.
  • Use try-with-resources for CopilotClient and CopilotSession. Close event and lifecycle subscriptions when no longer needed.
  • Use typed event handlers and the existing ToolDefinition and ToolInvocation helpers rather than ad hoc wire payloads. Prefer getArgumentsAs() for typed tool arguments.
  • Creating and resuming sessions requires a permission handler. PermissionHandler.APPROVE_ALL is for scenarios that do not exercise permission decisions; it cannot bypass managed-settings approval.
  • Handle exceptional future completion and SessionErrorEvent. Streaming consumers must handle both incremental delta events and final messages.
  • Add Javadoc for public APIs and follow the existing four-space, Spotless/Eclipse formatting. Checkstyle defines the Javadoc checks and exclusions in sdk/config/checkstyle/checkstyle.xml.

Build, format, and test

Prefer the checked-in Maven wrapper (./mvnw, or .\mvnw.cmd on Windows). Follow SDK setup for the JDK and layout-appropriate Node.js version. Tests use Node.js for the replay harness and runtime preparation tooling. Maven's generate-test-resources phase installs their dependencies from the SDK tree. In the runtime repository, prefer npm --prefix <SDK_ROOT> run test:java; it refreshes the selected schemas and Java projection and requests a current host CLI before running the tests. Direct Maven commands bypass those prerequisites and are appropriate after preparing the checkout, or in the standalone SDK repository.

./mvnw clean verify
./mvnw -pl sdk spotless:apply
./mvnw -pl sdk spotless:check checkstyle:check

Run verify without -q or piping through grep so failures remain visible. verify does not run Spotless: apply and check formatting separately for Java source changes. Tests must exercise public APIs, not expose internals solely for tests.

For replay-backed Java integration tests, use the on-demand sdk-java-e2e-test skill. Its snapshot workflow and companion examples are not required for unrelated Java edits. For JDK 17 compatibility testing, run the JDK 25-built artifact on JDK 17 without recompiling it, following Development Setup.

Generated sources

Do not edit sdk/src/generated/java/ by hand. Update the generator in scripts/codegen/java.ts when needed. From <SDK_ROOT>, regenerate with the SDK facade so the runtime layout selects checked-out schemas and the standalone layout selects its pinned release schemas:

npm run generate:java

The protocol constant sdk/src/main/java/com/github/copilot/SdkProtocolVersion.java is also generated, despite living outside src/generated/. Change the shared <SDK_ROOT>/sdk-protocol-version.json and run npm --prefix <SDK_ROOT>/nodejs run update:protocol-version to update all six SDKs.

Use the SDK's selected schema inputs; do not update release-derived CLI pins as an incidental part of implementation work.