Java: Implement @CopilotTool ergonomics

[edburns]

PR 1792 Reviewer’s Guide — Java @CopilotTool Ergonomics

PR: #1792
Epic: #1682
ADR: java/docs/adr/adr-005-tool-definition.md

This PR introduces the Java high-level tool API (@CopilotTool + @Param) and compile-time metadata generation, while keeping low-level ToolDefinition.create(...) as the foundation.

What to optimize for in review

Please focus on API semantics, generated-invocation correctness, and schema fidelity rather than style. The main question is whether this design is robust enough for long-term Java SDK ergonomics and interoperability.

Scope mapped to epic child issues

Epic item	Delivered in PR 1792
#1758	@CopilotTool and @Param annotations
#1759	Compile-time SchemaGenerator (TypeMirror -> JSON Schema source)
#1760	JSR-269 CopilotToolProcessor generating $$CopilotToolMeta
#1761	ToolDefinition.fromObject(...) / fromClass(...) registration bridge
#1762	E2E integration test and snapshot for ergonomic path
#1789	Follow-up item remains open; related hardening landed here (default/optional handling)

Commit stream reading order (recommended)

Ignore WIP/prompt commits and review in this logical order:

1. feat(java): create @CopilotTool and @Param annotations (#1763)
2. feat(java): add SchemaGenerator compile-time type-to-JSON-Schema utility (#1766)
3. feat(java): Add CopilotToolProcessor annotation processor (task 4.3) (#1777)
4. feat(java): Add ToolDefinition.fromObject() and fromClass() registration API (#1779)
5. Add E2E integration test for ergonomic @CopilotTool + ToolDefinition.fromObject() API (#1787)
6. Hardening commits: Optional extraction fix, static-tool qualified-name fix, java.time schema format hints, CodeQL cleanup, snapshot stabilization, test generation fixes.

File-level review map

Area	Primary files
Public API surface	java/src/main/java/com/github/copilot/tool/CopilotTool.java, java/src/main/java/com/github/copilot/tool/Param.java, java/src/main/java/com/github/copilot/rpc/ToolDefinition.java
Metadata provider contract	java/src/main/java/com/github/copilot/tool/CopilotToolMetadataProvider.java
Processor/codegen	java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java, java/src/main/resources/META-INF/services/javax.annotation.processing.Processor, java/src/main/java/module-info.java
Schema mapping	java/src/main/java/com/github/copilot/tool/SchemaGenerator.java
Unit tests (processor)	java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java, java/src/test/java/com/github/copilot/tool/SchemaGeneratorTest.java
Unit tests (runtime bridge)	java/src/test/java/com/github/copilot/rpc/ToolDefinitionFromObjectTest.java + fixtures under java/src/test/java/com/github/copilot/rpc/fixtures/
E2E parity proof	java/src/test/java/com/github/copilot/e2e/ErgonomicToolDefinitionIT.java, test/snapshots/tools/ergonomic_tool_definition.yaml

Architectural intent (as implemented)

1. User-facing model: langchain4j-style method annotations.
2. Implementation strategy: Micronaut-style compile-time processor/codegen, not reflection-first.
3. Bridge: ToolDefinition.fromObject/fromClass loads generated $$CopilotToolMeta.
4. No silent fallback: missing generated metadata throws explicit IllegalStateException.
5. Low-level path preserved: ToolDefinition.create* remains available.

High-value review questions (actionable feedback requested)

1. Is @Retention(RUNTIME) on @CopilotTool/@Param still the right long-term choice now that fromObject() is processor-only by default (no runtime fallback path)?
2. Is requiring non-private tool methods the right constraint vs. adding MethodHandles-based access?
3. Is the current default-value policy complete and safe?
   • required=true + defaultValue is compile-time error
   • defaults applied only when key is absent
   • generated path semantics match intended runtime behavior
4. Is return-type handling policy correct for real agents?
   • String passthrough
   • void -> "Success"
   • CompletableFuture<String> passthrough (object-cast)
   • non-string results JSON-serialized
5. Is exception policy acceptable in generated lambdas (RuntimeException wrapping during serialization)?
6. Is SchemaGenerator coverage sufficient for v1 (primitives, boxed, collections, maps, records/classes, enums, sealed interfaces, java.time formats, Optional variants)?
7. Is Param.name() interaction with generated extraction/schema intuitive and predictable for advanced use?
8. Is the static-tool path (fromClass) now robust enough after qualified-class-name and instance-method guard fixes?
9. Is ToolDefer.NONE -> null wire behavior the right compatibility choice?
10. Any JPMS edge cases missed around generated metadata loading, module boundaries, or processor registration?

Deliberate non-goals / constraints in this PR

• No broad reflection fallback in fromObject() when metadata is missing (fail fast instead).
• No change to low-level tool-definition API contract.
• Ergonomic API remains @CopilotExperimental.

Extra context from iteration artifacts

The prompt/design trail in copilot-sdk-01/1682-java-tool-ergonomics-prompts-remove-before-merge tracks the ignorance-reduction phase and key decisions that shaped this PR (especially annotation shape, default semantics, processor-only direction, and schema coverage expansions).

If you see a mismatch between ADR intent and implementation behavior, that is exactly the class of feedback I want.

Note on CopilotToolMetadataProvider

CopilotToolMetadataProvider<T> is the runtime seam between generated metadata and ToolDefinition.fromObject(...) loading.
The processor emits $$CopilotToolMeta classes that implement this interface and expose:

List<ToolDefinition> definitions(T instance, ObjectMapper mapper)

This keeps fromObject/fromClass decoupled from generated-class internals, and also allows advanced/manual implementations of the provider contract when needed.

Usage sample snippets (from copilot-sdk-01/.../simple-weather-demo)

1. pom.xml — experimental + annotation processor

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.15.0</version>
    <configuration>
        <compilerArgs>
            <arg>-Acopilot.experimental.allowed=true</arg>
        </compilerArgs>
        <annotationProcessorPaths>
            <path>
                <groupId>com.github</groupId>
                <artifactId>copilot-sdk-java</artifactId>
                <version>${copilot.sdk.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

2. Tool declaration with @CopilotTool

@CopilotTool("Get the current weather for a given city")
public String getWeather(
        @Param(value = "The city to get weather for", required = true) String city,
        @Param(value = "Temperature unit: celsius or fahrenheit", required = false, defaultValue = "celsius") String unit) {
    // ...
}

3. Registration via ToolDefinition.fromObject(...)

WeatherTools weatherTools = new WeatherTools();
List<ToolDefinition> toolDefs = ToolDefinition.fromObject(weatherTools);

SessionConfig sessionConfig = new SessionConfig()
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
        .setAvailableTools(new ToolSet().addCustom("*"))
        .setTools(toolDefs);

[Copilot]

Pull request overview

This PR introduces an ergonomic, annotation-based Java tool definition API (@CopilotTool / @Param) backed by a JSR-269 annotation processor that generates $$CopilotToolMeta companion classes, enabling ToolDefinition.fromObject(...) (and fromClass(...)) to produce runnable ToolDefinition instances with generated JSON Schemas and handlers.

Changes:

• Add @CopilotTool / @Param annotations and CopilotToolProcessor to generate tool metadata classes at compile time.
• Add ToolDefinition.fromObject(...) / fromClass(...) runtime entry points to load generated tool definitions.
• Add unit/processor tests plus a Java E2E snapshot + integration test to validate wire-level behavior.

Show a summary per file

File	Description
test/snapshots/tools/ergonomic_tool_definition.yaml	New replay snapshot for ergonomic tool definition scenario
java/src/test/java/com/github/copilot/tool/SchemaGeneratorTest.java	Compilation-testing coverage for schema generator outputs
java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java	Processor compilation tests for generated meta + validation errors
java/src/test/java/com/github/copilot/tool/CopilotToolAnnotationTest.java	Annotation retention/targets/defaults verification
java/src/test/java/com/github/copilot/rpc/ToolDefinitionFromObjectTest.java	E2E-style unit tests for ToolDefinition.fromObject(...) behavior
java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools$$CopilotToolMeta.java	Hand-written fixture mimicking generated meta output (simple tools)
java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools.java	Fixture tool class annotated with @CopilotTool / @Param
java/src/test/java/com/github/copilot/rpc/fixtures/OverrideTools$$CopilotToolMeta.java	Fixture meta for override flag behavior
java/src/test/java/com/github/copilot/rpc/fixtures/OverrideTools.java	Fixture tool class for override flag
java/src/test/java/com/github/copilot/rpc/fixtures/MultiReturnTools$$CopilotToolMeta.java	Fixture meta for return-type handling patterns
java/src/test/java/com/github/copilot/rpc/fixtures/MultiReturnTools.java	Fixture tool class for return-type handling patterns
java/src/test/java/com/github/copilot/rpc/fixtures/DefaultValueTools$$CopilotToolMeta.java	Fixture meta for default parameter values
java/src/test/java/com/github/copilot/rpc/fixtures/DefaultValueTools.java	Fixture tool class for default parameter values
java/src/test/java/com/github/copilot/rpc/fixtures/DateTimeTools$$CopilotToolMeta.java	Fixture meta for java.time argument conversion
java/src/test/java/com/github/copilot/rpc/fixtures/DateTimeTools.java	Fixture tool class using LocalDateTime parameter
java/src/test/java/com/github/copilot/rpc/fixtures/ArgCoercionTools$$CopilotToolMeta.java	Fixture meta for mixed-argument coercion
java/src/test/java/com/github/copilot/rpc/fixtures/ArgCoercionTools.java	Fixture tool class for mixed-argument coercion
java/src/test/java/com/github/copilot/e2e/ErgonomicToolDefinitionIT.java	Failsafe IT validating end-to-end ergonomic tool usage with snapshot
java/src/test/java/com/github/copilot/e2e/ErgonomicTestTools$$CopilotToolMeta.java	Hand-written E2E meta fixture mimicking processor output
java/src/test/java/com/github/copilot/e2e/ErgonomicTestTools.java	Tool fixture class for E2E ergonomic test
java/src/main/resources/META-INF/services/javax.annotation.processing.Processor	Registers CopilotToolProcessor as an annotation processor
java/src/main/java/module-info.java	Exports com.github.copilot.tool and provides processor in module-info
java/src/main/java/com/github/copilot/tool/SchemaGenerator.java	New compile-time JSON-schema source generator
java/src/main/java/com/github/copilot/tool/Param.java	New @Param annotation
java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java	New processor generating $$CopilotToolMeta classes
java/src/main/java/com/github/copilot/tool/CopilotToolMetadataProvider.java	Contract interface for generated/manual metadata providers
java/src/main/java/com/github/copilot/tool/CopilotTool.java	New @CopilotTool annotation
java/src/main/java/com/github/copilot/rpc/ToolDefinition.java	Adds fromObject(...) / fromClass(...) + mapper holder
java/src/main/java/com/github/copilot/rpc/ToolDefer.java	Adds NONE sentinel + serialization safety adjustments
java/mvnw	Adds Maven wrapper script under java/

Copilot's findings

• Files reviewed: 29/30 changed files
• Comments generated: 3

[rotationtv1-crypto]

edburns/1682-java-tool-ergonomics-review-draft-01

[github-actions]

Cross-SDK Consistency Review ✅

This PR implements Java-idiomatic ergonomic tool definition (@CopilotTool, @Param, annotation processor) and is consistent with the equivalent features already present in all other SDKs.

Feature Parity Matrix

Feature	Java (this PR)	Python	Node.js	.NET	Go	Rust
Ergonomic tool definition	@CopilotTool annotation	@define_tool decorator	defineTool()	CopilotTool.DefineTool()	DefineTool[T]()	define_tool()
overridesBuiltInTool	✅ annotation attr	✅ kwarg	✅ config field	✅ CopilotToolOptions	✅ struct field	✅ builder method
skipPermission	✅ annotation attr	✅ kwarg	✅ config field	✅ CopilotToolOptions	✅ struct field	✅ builder method
defer	✅ annotation attr	✅ kwarg	✅ config field	✅ CopilotToolOptions	✅ struct field	✅ builder method
Schema auto-generation	✅ via SchemaGenerator	✅ via Pydantic	✅ via Zod	✅ via AIFunctionFactory	✅ via jsonschema-go	✅ via schemars

Observations

1. All three tool options (overridesBuiltInTool, skipPermission, defer) are properly surfaced in the @CopilotTool annotation, matching the options available in Python, Node.js, and .NET helper APIs.

2. ToolDefer.NONE sentinel is a Java-specific necessity (annotation defaults cannot be null). The Javadoc clearly documents that this must be mapped to null before being forwarded to ToolDefinition, which the annotation processor correctly handles. Other SDKs use the language's natural null/None/Optional semantics.

3. @Param annotation (description, name override, required, defaultValue) is Java-specific but consistent in spirit with Pydantic Field(...) in Python, JSON struct tags in Go, and [Description] / [JsonPropertyName] attributes in .NET.

4. All changes are scoped to java/ — no other SDK implementations are affected.

No cross-SDK consistency issues found. The Java annotation-based ergonomics are a well-designed language-idiomatic equivalent of the tool definition helpers in all other SDKs.

Generated by SDK Consistency Review Agent for issue #1792 · sonnet46 1.9M · ◷

[jdubois]

Optional primitives NPE at runtime. A @Param(required=false) int limit is correctly dropped from the schema's required, but this branch still emits int limit = ((Number) args.get("limit")).intValue();. When the model omits the arg, args.get("limit") is null and the unboxing throws NullPointerException: Cannot invoke "java.lang.Number.intValue()" because ... Map.get(Object) is null (confirmed by running the real processor).

A primitive simply can't represent "absent." I'd reject this at compile time — emit an error telling the user to use a boxed type (Integer), an Optional, or supply a defaultValue — which matches the existing compile-time validations for private methods and required+default conflicts.

[jdubois]

Single-record tools are broken — the schema and the handler disagree. generateSchemaWithParamMetadata nests the record under the parameter name (properties: { req: { ...fields... } }, required: [req]), but here the handler does mapper.convertValue(args, SearchArgs.class) against the whole args map. So when the model sends the schema-conformant {"req":{"query":"hello","limit":7}}, the record comes back with null/0 fields — silent data loss with the SDK's lenient mapper (FAIL_ON_UNKNOWN_PROPERTIES=false), or UnrecognizedPropertyException with a strict one. This is exactly the record pattern that ToolDefinition's own Javadoc recommends, and no fixture exercises it so it's green in CI.

I verified this by running the real processor: schema {properties={req={...}}, required=[req]}, payload {req:{query=hello,limit=7}} → handler returned query=null, limit=0.

Fix: flatten the schema for the single-record case so the record's components are the top-level properties (matching convertValue(args, Record.class)). Also, declaring the record straight from invocation.getArguments() avoids the secondary bug where a record param literally named args collides with the Map args local declared just above.

[jdubois]

Generics are erased here. qualifiedName + ".class" produces e.g. mapper.convertValue(args.get("ids"), java.util.List.class), so a List<UUID> parameter deserializes to a raw List whose elements stay String (or LinkedHashMap) — never UUID. The schema is correct (items: {type: string, format: uuid}), but real user code doing for (UUID id : ids) hits a ClassCastException. Same for List<MyRecord>, Set<Foo>, Map<String,Long>, etc.

Confirmed with the real processor: payload {ids:["...uuid..."]} → element class came back as java.lang.String.

Use Jackson's TypeReference built from the full generic type (type.toString(), which yields java.util.List<java.util.UUID>) instead of .class — e.g. mapper.convertValue(args.get("ids"), new com.fasterxml.jackson.core.type.TypeReference<java.util.List<java.util.UUID>>(){}).

[jdubois]

Array parameters generate code that doesn't compile. Arrays aren't primitive or DECLARED, so they fall through to (Object) args.get(...), while the variable is declared with the real array type. For @Param String[] names the processor emits:

java.lang.String[] names = (Object) args.get("names");

→ incompatible types: java.lang.Object cannot be converted to java.lang.String[] (confirmed by compiling the real generated output). SchemaGenerator already supports arrays, so any tool with an array param breaks the consumer's build entirely. Route arrays (and any non-scalar) through mapper.convertValue(args.get("x"), new TypeReference<T>(){}) — the same fix as the generics issue covers this.

[jdubois]

defaultValue is injected as a raw, unvalidated source token, in both the schema and the lambda. For @Param(required=false, defaultValue="abc") int count the processor emits ... withMeta(Map.of("type","integer"), "count", abc) and Object countRaw = ... : abc; → cannot find symbol: variable abc, i.e. the consumer's build fails (confirmed against the real processor). Even when it compiles, types can disagree: defaultValue="1.5" on an int advertises 1.5 in the schema's default but truncates to 1 at runtime.

Two things here: (1) validate the default against the parameter type at compile time and emit a clear error on unparseable values (consistent with the other @Param validations in process()); (2) emit a correctly-typed literal — quote strings/chars, append L/F/D for long/float/double — so the schema default and the runtime value match.