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 adds the ergonomic @CopilotTool + @Param annotation API for Java, which brings Java into parity with the ergonomic tool-definition helpers that already exist in other SDKs:

SDK	Ergonomic Tool API
Node.js	defineTool(name, { description, handler, ... })
Python	@define_tool(description=...) decorator
Go	DefineTool[T](name, description, handler) generic function
.NET	CopilotTool.DefineTool(delegate, options)
Rust	ToolHandler trait + schema_for<T>()
Java (this PR)	@CopilotTool("description") annotation + processor

Cross-cutting options are consistent ✅

The new @CopilotTool annotation correctly exposes all three options that every other SDK exposes on its ergonomic API:

• overridesBuiltInTool — matches all SDKs
• skipPermission — matches all SDKs
• defer — matches all SDKs

ToolDefer.NONE sentinel ✅

The NONE sentinel added to ToolDefer is a necessary and well-documented Java annotation idiom (annotation element defaults can't be null). The Javadoc is explicit that:

• NONE must not be passed to ToolDefinition factory methods
• NONE → null field reference on the wire, which matches the nullable/optional semantics of all other SDKs

The getValue() → null for NONE provides a reasonable secondary safety net.

@Param parameter metadata ✅

The @Param(value, required, defaultValue) annotation is a Java-idiomatic approach that doesn't create a consistency gap — other SDKs use language-specific mechanisms for per-parameter metadata (Pydantic Field(...) in Python, struct tags in Go, [Description] in .NET, Zod .describe() in Node.js).

Pre-existing observation (non-blocking)

Go's DefineTool[T] helper only accepts name, description, and handler — SkipPermission, OverridesBuiltInTool, and Defer must be set on the returned struct afterward. With Java's ergonomic API now inline with the full option set, this pre-existing Go ergonomics gap becomes more visible by comparison. Not a concern for this PR, but worth tracking for a follow-up.

---

No blocking cross-SDK consistency issues found. The Java ergonomic API faithfully mirrors the intent and capabilities of the equivalent helpers in all other SDKs.

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

[edburns]

Comment	Verdict	Evidence
3480477597	Yes	45b539cf adds compile-time validation for optional primitives without defaults, plus the regression test.
3480477599	Yes	2e6aa4fc flattens single-record schema generation and switches handler binding to direct invocation.getArguments() mapping; it also rejects wrapper-only @Param metadata.
3480477601	Yes	31ee6e32 changes generic declared-parameter extraction to use TypeReference, preserving element/value types.
3480477605	Yes, with caveat	The fix is the processor change that uses the same TypeReference path for arrays; 92193c94 is the regression test that confirms array params now compile.
3480477612	Yes	2096937d validates defaultValue against the target type and rejects mismatched numeric defaults like 1.5 for int.