AGENTS.md@java git:20260922.51a0394A

Immutable. This exact content never changes and is served at /api/v1/blob/9b3e24f8656641cf.

<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->

# 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](README.md), the
[SDK documentation](../docs/getting-started.md), 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](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

Use Maven 3.9+ or the checked-in Maven wrapper. Tests also require a supported
[Node.js version](../nodejs/README.md#prerequisites) 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.

```bash
mvn clean verify
mvn -pl sdk spotless:apply
mvn -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](../.github/skills/sdk-java-e2e-test/SKILL.md).
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](README.md#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:

```bash
npm run generate:java
```

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