feat(java): Add CopilotToolProcessor annotation processor (task 4.3)

[Copilot]

Fixes #1760 .

Implements the JSR 269 annotation processor that finds @CopilotTool-annotated methods and generates $$CopilotToolMeta companion classes at compile time — zero reflection, zero -parameters flag requirement.

Changes

• CopilotToolProcessor.java — The processor that:

  • Groups @CopilotTool methods by enclosing class, generates one $$CopilotToolMeta per class in the same package
  • Emits compile errors for private methods and required=true + defaultValue conflicts
  • Converts method names to snake_case (or uses explicit @CopilotTool(name=...))
  • Delegates to SchemaGenerator for type→JSON Schema mapping, adds @Param description/default via withMeta helper
  • Generates invocation lambdas with correct return-type handling and argument deserialization patterns
  • Routes to ToolDefinition.create / createOverride / createSkipPermission / createWithDefer based on annotation attributes
  • Maps ToolDefer.NONE → null (regular create), non-NONE → createWithDefer

• META-INF/services/javax.annotation.processing.Processor — Registers CopilotToolProcessor

• module-info.java — Adds to provides clause

• CopilotToolProcessorTest.java — Programmatic javax.tools.JavaCompiler tests covering generation, error cases, return types, arg coercion, schema output, and service registration

Generated code shape

// GENERATED by CopilotToolProcessor — do not edit
package com.example;

final class MyTools$$CopilotToolMeta {
    private static final ObjectMapper objectMapper = new ObjectMapper();

    @SuppressWarnings({"unchecked", "rawtypes"})
    static List<ToolDefinition> definitions(MyTools instance) {
        return List.of(
            ToolDefinition.create(
                "set_current_phase",
                "Sets the current phase",
                Map.of("type", "object", "properties", Map.ofEntries(
                    Map.entry("phase", (Map<String, Object>)(Map) withMeta(Map.of("type", "string"), "The phase", null))
                ), "required", List.of("phase")),
                invocation -> {
                    Map<String, Object> args = invocation.getArguments();
                    java.lang.String phase = (String) args.get("phase");
                    return CompletableFuture.completedFuture(instance.setCurrentPhase(phase));
                }
            )
        );
    }
}

[edburns]

@copilot

Both the JDK 25 and JDK 17 tests failed.
https://github.com/github/copilot-sdk/actions/runs/28055309594/
Please investigate, fix, run-tests locally, and then push commits.

[Copilot]

@copilot

Both the JDK 25 and JDK 17 tests failed....

Investigated and fixed both CI failures across multiple iterations:

JDK 25 (Spotless formatting): Applied all Eclipse formatter-required changes to CopilotToolProcessor.java and CopilotToolProcessorTest.java — boolean expression line breaks (&& at start of continuation), ternary formatting, sb.append() chain formatting, unused import removal, and array initializer formatting. Spotless check passed as of run 28058839052.

JDK 17 (test classpath): The resolveClasspath() method only returned the SDK classes directory via CodeSource, missing Jackson dependencies. Fixed by collecting classpath entries from System.getProperty("java.class.path") combined with CodeSource paths from key classes (CopilotTool, ObjectMapper, JsonFactory, JsonProperty, ToolDefinition). JDK 17 tests passed as of run 28058839052.

Latest commit: 1ac82f6 — fixes the last Spotless formatting issue (keyClasses array initializer). CI should be green on this push.

[github-actions]

Generated by SDK Consistency Review Agent for issue #1777 · sonnet46 1.8M

[Copilot]

Pull request overview

Adds a Java JSR-269 annotation processor to generate $$CopilotToolMeta companion classes for @CopilotTool methods (compile-time tool metadata + invocation wiring), and wires it into the Java module and service loader with compiler-based tests.

Changes:

• Implement CopilotToolProcessor to discover @CopilotTool methods, validate invalid usages, and generate per-class $$CopilotToolMeta sources.
• Register the processor via META-INF/services and module-info.java.
• Add JavaCompiler-driven tests validating generation, errors, and key codegen behaviors.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/tool/CopilotToolProcessor.java	Implements the annotation processor and code generation for $$CopilotToolMeta.
java/src/main/resources/META-INF/services/javax.annotation.processing.Processor	Registers the new processor for service loading.
java/src/main/java/module-info.java	Adds the processor to the module provides clause.
java/src/test/java/com/github/copilot/tool/CopilotToolProcessorTest.java	Programmatic compiler tests for generation and validation behaviors.

Copilot's findings

• Files reviewed: 4/4 changed files
• Comments generated: 4

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds a Java-specific annotation processor (@CopilotTool / @Param) for ergonomic tool definition. Here's how it maps to the other SDKs:

SDK	Ergonomic tool definition mechanism
Node.js	defineTool() function with options
Python	@define_tool decorator
Go	DefineTool[T]() generic function
.NET	CopilotTool.DefineTool() with delegate + options
Rust	ToolHandler trait + builder methods
Java (this PR)	@CopilotTool annotation processor

Feature parity ✅

The three tool option attributes introduced by @CopilotTool are consistent with all other SDKs:

Feature	Node.js	Python	Go	.NET	Rust	Java (this PR)
overridesBuiltInTool	✅	✅	✅ (on Tool struct)	✅	✅	✅
skipPermission	✅	✅	✅ (on Tool struct)	✅	✅	✅
defer: auto|never	✅	✅	✅	✅	✅	✅

ToolDefer.NONE sentinel ✅

Adding NONE as an annotation-default sentinel is appropriate and consistent. All other SDKs represent "no defer specified" as null/None/omitted (nullable), and NONE→null on the wire matches that behavior exactly.

No action needed

This is a Java-idiomatic feature (JSR 269 annotation processing, compile-time codegen) that doesn't require mirroring in other SDKs — each SDK already has its own idiomatic approach to ergonomic tool definition. The API surface and wire semantics are consistent across all six implementations.

Generated by SDK Consistency Review Agent for issue #1777 · sonnet46 1.6M · ◷