feat(java): create @copilotTool and @PARAM annotations with tests

- Add NONE constant to ToolDefer enum for annotation default value
- Create com.github.copilot.tool.CopilotTool annotation
- Create com.github.copilot.tool.Param annotation
- Export com.github.copilot.tool package in module-info.java
- Add CopilotToolAnnotationTest verifying retention, targets, defaults

Closes #1758

Author: Copilot

java/src/main/java/com/github/copilot/rpc/ToolDefer.java

@@ -21,6 +21,12 @@
  */
 public enum ToolDefer {
 
+    /**
+     * No deferral preference set. Used as the default for annotation-based
+     * tool definitions where the user has not explicitly chosen a mode.
+     */
+    NONE(""),
+
     /** The tool can be deferred and surfaced through tool search. */
     AUTO("auto"),
 

java/src/main/java/com/github/copilot/tool/CopilotTool.java

@@ -0,0 +1,53 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.tool;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import com.github.copilot.CopilotExperimental;
+import com.github.copilot.rpc.ToolDefer;
+
+/**
+ * Marks a method as a Copilot tool. The annotated method will be exposed to the
+ * model as a callable tool during a session.
+ *
+ * <p>
+ * Example usage:
+ *
+ * <pre>
+ * &#64;CopilotTool("Get weather for a location")
+ * public CompletableFuture&lt;String&gt; getWeather(
+ *         &#64;Param(value = "City name", required = true) String location) {
+ *     return CompletableFuture.completedFuture("Sunny in " + location);
+ * }
+ * </pre>
+ *
+ * @since 1.0.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+@CopilotExperimental
+public @interface CopilotTool {
+
+    /** Tool description (sent to the model). */
+    String value();
+
+    /** Tool name. Defaults to method name converted to snake_case. */
+    String name() default "";
+
+    /** Whether this tool overrides a built-in tool. */
+    boolean overridesBuiltInTool() default false;
+
+    /** Whether to skip permission checks. */
+    boolean skipPermission() default false;
+
+    /** Defer configuration for this tool. */
+    ToolDefer defer() default ToolDefer.NONE;
+}

java/src/main/java/com/github/copilot/tool/Param.java

@@ -0,0 +1,47 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.tool;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotates a parameter of a {@link CopilotTool}-annotated method to provide
+ * metadata about the parameter that is sent to the model.
+ *
+ * <p>
+ * Example usage:
+ *
+ * <pre>
+ * &#64;CopilotTool("Search for issues")
+ * public CompletableFuture&lt;String&gt; searchIssues(
+ *         &#64;Param(value = "Search query", required = true) String query,
+ *         &#64;Param(value = "Max results", required = false, defaultValue = "10") int limit) {
+ *     // ...
+ * }
+ * </pre>
+ *
+ * @since 1.0.0
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface Param {
+
+    /** Parameter description (sent to the model). */
+    String value() default "";
+
+    /** Parameter name override. Defaults to the actual parameter name. */
+    String name() default "";
+
+    /** Whether this parameter is required. Default true. */
+    boolean required() default true;
+
+    /** Optional default value when the argument is omitted. */
+    String defaultValue() default "";
+}

java/src/main/java/module-info.java

@@ -19,6 +19,7 @@
     exports com.github.copilot.generated;
     exports com.github.copilot.generated.rpc;
     exports com.github.copilot.rpc;
+    exports com.github.copilot.tool;
 
     opens com.github.copilot to com.fasterxml.jackson.databind;
     opens com.github.copilot.generated to com.fasterxml.jackson.databind;

java/src/test/java/com/github/copilot/tool/CopilotToolAnnotationTest.java

@@ -0,0 +1,149 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.tool;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.concurrent.CompletableFuture;
+
+import org.junit.jupiter.api.Test;
+
+import com.github.copilot.CopilotExperimental;
+import com.github.copilot.rpc.ToolDefer;
+
+/**
+ * Unit tests for {@link CopilotTool} and {@link Param} annotations.
+ */
+public class CopilotToolAnnotationTest {
+
+    // --- @CopilotTool attribute verification ---
+
+    @Test
+    void copilotToolHasRuntimeRetention() {
+        Retention retention = CopilotTool.class.getAnnotation(Retention.class);
+        assertNotNull(retention);
+        assertEquals(RetentionPolicy.RUNTIME, retention.value());
+    }
+
+    @Test
+    void copilotToolTargetsMethod() {
+        Target target = CopilotTool.class.getAnnotation(Target.class);
+        assertNotNull(target);
+        assertArrayEquals(new ElementType[] {ElementType.METHOD}, target.value());
+    }
+
+    @Test
+    void copilotToolIsAnnotatedWithCopilotExperimental() {
+        // @CopilotExperimental has CLASS retention so it is not visible via
+        // reflection at runtime. However, we can confirm:
+        // 1. The annotation type targets TYPE (which includes @interface declarations).
+        // 2. Compilation succeeded with @CopilotExperimental on @CopilotTool
+        //    (the CopilotExperimentalProcessor would reject usage otherwise).
+        Target expTarget = CopilotExperimental.class.getAnnotation(Target.class);
+        assertNotNull(expTarget);
+        boolean includesType = false;
+        for (ElementType et : expTarget.value()) {
+            if (et == ElementType.TYPE) {
+                includesType = true;
+                break;
+            }
+        }
+        assertTrue(includesType,
+                "@CopilotExperimental must target TYPE to be applicable to annotation declarations");
+    }
+
+    @Test
+    void copilotToolDefaultValues() throws Exception {
+        Method nameMethod = CopilotTool.class.getDeclaredMethod("name");
+        assertEquals("", nameMethod.getDefaultValue());
+
+        Method overridesMethod = CopilotTool.class.getDeclaredMethod("overridesBuiltInTool");
+        assertEquals(false, overridesMethod.getDefaultValue());
+
+        Method skipMethod = CopilotTool.class.getDeclaredMethod("skipPermission");
+        assertEquals(false, skipMethod.getDefaultValue());
+
+        Method deferMethod = CopilotTool.class.getDeclaredMethod("defer");
+        assertEquals(ToolDefer.NONE, deferMethod.getDefaultValue());
+    }
+
+    // --- @Param attribute verification ---
+
+    @Test
+    void paramHasRuntimeRetention() {
+        Retention retention = Param.class.getAnnotation(Retention.class);
+        assertNotNull(retention);
+        assertEquals(RetentionPolicy.RUNTIME, retention.value());
+    }
+
+    @Test
+    void paramTargetsParameter() {
+        Target target = Param.class.getAnnotation(Target.class);
+        assertNotNull(target);
+        assertArrayEquals(new ElementType[] {ElementType.PARAMETER}, target.value());
+    }
+
+    @Test
+    void paramDefaultValues() throws Exception {
+        Method valueMethod = Param.class.getDeclaredMethod("value");
+        assertEquals("", valueMethod.getDefaultValue());
+
+        Method nameMethod = Param.class.getDeclaredMethod("name");
+        assertEquals("", nameMethod.getDefaultValue());
+
+        Method requiredMethod = Param.class.getDeclaredMethod("required");
+        assertEquals(true, requiredMethod.getDefaultValue());
+
+        Method defaultValueMethod = Param.class.getDeclaredMethod("defaultValue");
+        assertEquals("", defaultValueMethod.getDefaultValue());
+    }
+
+    // --- Applicability test ---
+
+    @SuppressWarnings("unused")
+    static class SampleToolHolder {
+
+        @CopilotTool(value = "Get weather for a location", name = "get_weather", defer = ToolDefer.AUTO)
+        public CompletableFuture<String> getWeather(
+                @Param(value = "City name", required = true) String location,
+                @Param(value = "Temperature unit", required = false, defaultValue = "celsius") String unit) {
+            return CompletableFuture.completedFuture("Sunny in " + location);
+        }
+    }
+
+    @Test
+    void annotationsAreAccessibleViaReflection() throws Exception {
+        Method method = SampleToolHolder.class.getDeclaredMethod("getWeather", String.class, String.class);
+
+        CopilotTool toolAnnotation = method.getAnnotation(CopilotTool.class);
+        assertNotNull(toolAnnotation);
+        assertEquals("Get weather for a location", toolAnnotation.value());
+        assertEquals("get_weather", toolAnnotation.name());
+        assertFalse(toolAnnotation.overridesBuiltInTool());
+        assertFalse(toolAnnotation.skipPermission());
+        assertEquals(ToolDefer.AUTO, toolAnnotation.defer());
+
+        Parameter[] params = method.getParameters();
+        assertEquals(2, params.length);
+
+        Param locationParam = params[0].getAnnotation(Param.class);
+        assertNotNull(locationParam);
+        assertEquals("City name", locationParam.value());
+        assertTrue(locationParam.required());
+        assertEquals("", locationParam.defaultValue());
+
+        Param unitParam = params[1].getAnnotation(Param.class);
+        assertNotNull(unitParam);
+        assertEquals("Temperature unit", unitParam.value());
+        assertFalse(unitParam.required());
+        assertEquals("celsius", unitParam.defaultValue());
+    }
+}