java: add schema attribute to @CopilotToolParam and lambda for custom type schema override

.vscode/settings.json

@@ -25,6 +25,7 @@
   "[go]": {
     "editor.defaultFormatter": "golang.go"
   },
+  "java.autobuild.enabled": false,
   "java.configuration.updateBuildConfiguration": "automatic",
   "java.compile.nullAnalysis.mode": "automatic"
 }

java/pom.xml

@@ -76,6 +76,8 @@
             require npm or network access.
         -->
         <skip.cli.install>${skip.test.harness}</skip.cli.install>
+        <!-- Override with -Dnpm.loglevel=verbose when troubleshooting npm. -->
+        <npm.loglevel>notice</npm.loglevel>
         <!-- Extra JVM args for Surefire; overridden by the jdk21+ profile -->
         <surefire.jvm.args />
         <!--
@@ -213,6 +215,8 @@
                             <workingDirectory>${copilot.sdk.root}/test/harness</workingDirectory>
                             <arguments>
                                 <argument>ci</argument>
+                                <argument>--loglevel</argument>
+                                <argument>${npm.loglevel}</argument>
                             </arguments>
                         </configuration>
                     </execution>
@@ -235,6 +239,8 @@
                             <arguments>
                                 <argument>ci</argument>
                                 <argument>--ignore-scripts</argument>
+                                <argument>--loglevel</argument>
+                                <argument>${npm.loglevel}</argument>
                             </arguments>
                         </configuration>
                     </execution>

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

@@ -14,6 +14,7 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.github.copilot.tool.Param;
 
@@ -84,7 +85,21 @@ static Map<String, Object> buildSchema(String toolName, ObjectMapper mapper, Par
         Map<String, Object> properties = new LinkedHashMap<>();
 
         for (Param<?> param : params) {
-            Map<String, Object> typeSchema = forType(param.type());
+            Map<String, Object> typeSchema;
+            if (!param.schema().isEmpty()) {
+                try {
+                    @SuppressWarnings("unchecked")
+                    Map<String, Object> parsed = mapper.readerFor(Map.class)
+                            .with(DeserializationFeature.FAIL_ON_TRAILING_TOKENS)
+                            .with(DeserializationFeature.USE_BIG_DECIMAL_FOR_FLOATS).readValue(param.schema());
+                    typeSchema = parsed;
+                } catch (Exception e) {
+                    throw new IllegalArgumentException("Invalid schema JSON for parameter '" + param.name()
+                            + "' in tool '" + toolName + "': " + e.getMessage(), e);
+                }
+            } else {
+                typeSchema = forType(param.type());
+            }
             Map<String, Object> enriched = new LinkedHashMap<>(typeSchema);
             enriched.put("description", param.description());
             if (param.hasDefaultValue()) {

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

@@ -47,4 +47,22 @@
 
     /** Optional default value when the argument is omitted. */
     String defaultValue() default "";
+
+    /**
+     * Optional explicit JSON Schema for this parameter as a JSON string literal.
+     * When non-empty, bypasses automatic schema generation from the parameter type.
+     * The value must be a valid JSON object string.
+     *
+     * <p>
+     * Example:
+     *
+     * <pre>
+     * &#64;CopilotTool("Schedule meeting")
+     * public String schedule(
+     * 		&#64;CopilotToolParam(value = "When to meet", schema = "{\"type\":\"string\",\"format\":\"date-time\"}") MyCustomDateTime when) {
+     * 	// ...
+     * }
+     * </pre>
+     */
+    String schema() default "";
 }