[Java] Add Param<T> public API type for lambda-defined tools

[Copilot]

Phase 4.1 of #1810: introduces the runtime parameter metadata class needed by the upcoming ToolDefinition.from(...) lambda overloads.

Changes

• Param<T> (com.github.copilot.tool) — immutable, fluent parameter descriptor with construction-time validation:
  • Rejects blank name/description
  • Rejects required=true combined with a non-empty defaultValue
  • Validates defaultValue against declared Class<T> (String, numeric primitives/boxed, Boolean, enums; unsupported types throw)
• ParamTest — 27 unit tests covering factory methods, fluent mutators, all validation rules, and equality semantics
• Plan file — Phase 4.1 checkbox marked complete

Usage

// Required param, no default
Param<String> query = Param.of(String.class, "query", "Search query text");

// Optional param with validated default
Param<Integer> limit = Param.of(Integer.class, "limit", "Max results", false, "10");

// Fluent mutation (returns new instance)
Param<String> renamed = query.name("search_query");
Param<String> optional = query.defaultValue("*"); // implicitly sets required=false

No changes to module-info.java needed — com.github.copilot.tool is already exported.

[github-actions]

SDK Consistency Review ✅

Reviewed cross-SDK consistency for the Param<T> type introduced in this PR.

Finding: No consistency issues — Java-specific gap fill

The Param<T> class is a legitimate Java-specific type that fills a gap in Java's tool definition API. Every other SDK already addresses the same underlying need through its own language-native idiom:

SDK	How individual parameter metadata (name, description, type, required, default) is carried
Node.js/TS	Zod fluent API: z.string().describe("..."), .optional(), .default(...)
Python	Pydantic BaseModel fields: Field(description="..."), Optional[T], Field(default=...)
Go	Struct tags: json:"name", jsonschema:"description", *T for optional
.NET	[Description("...")] attribute + C# nullable/default params via AIFunctionFactory reflection
Rust	/// doc comments + schemars derive + Option<T> for optional
Java (this PR)	Param<T> with factory methods and fluent mutators

Java lacks any of the other languages' built-in mechanisms for attaching per-parameter metadata inline (no Zod, no Pydantic, no struct tags, no C# attributes for a lambda/method-reference style call). The Param<T> class is the Java equivalent — it gives the upcoming ToolDefinition.from(...) lambda overloads (Phase 4.2) a way to carry the same rich metadata the other SDKs already have.

API shape mirrors existing @CopilotToolParam

The five attributes on Param<T> (type, name, description, required, defaultValue) map exactly to the four elements of the existing @CopilotToolParam annotation (+ the Java type token, which annotations can't carry as a runtime generic). Good internal consistency within Java.

No action required in other SDKs

This PR completes parity (each SDK can now fully describe tool parameters); it does not introduce new behaviour that needs to be mirrored elsewhere.

Generated by SDK Consistency Review Agent for issue #1845 · sonnet46 2.9M · ◷