feat(java): implement ParamSchema + ParamCoercion internals for Param (Phase 4.3)

[Copilot]

Phase 4.3 of #1810. Adds the runtime schema/coercion layer that backs Param<T>-based lambda tool definitions, as the internal foundation consumed by the ToolDefinition.from* overloads added in Phase 4.2.

New classes (com.github.copilot.tool, package-private)

ParamSchema

• buildSchema(toolName, mapper, params...) — produces the full Map<String,Object> JSON Schema; validates duplicate parameter names at construction time with a clear error identifying tool name and offending name
• forType(Class<?>) — maps Java Class to JSON Schema type descriptor; runtime counterpart to the compile-time SchemaGenerator, covering the exact same type surface (primitives, String, UUID, temporal, enums, collections, arrays, maps, POJOs/records)

ParamCoercion

• coerce(args, param, mapper) — resolves invocation arg → string default → empty-optional → missing-required-error; delegates complex conversion to ObjectMapper.convertValue matching existing policy
• coerceDefault(param, mapper) — parses validated string defaults into the declared Java type
• emptyOptionalOrNull(type) — returns empty OptionalInt/OptionalLong/OptionalDouble or null

Key constraints honored

• Both classes are package-private — no new public types added to the exported module surface (resolution 3.8)
• coerce() takes Map<String,Object> rather than ToolInvocation to avoid a tool → rpc package dependency
• Type mapping and coercion policy are identical to the existing inline private methods in ToolDefinition, maintaining behavioral parity with the baseline contract from Phase 2

// Schema generation
Map<String, Object> schema = ParamSchema.buildSchema(
    "greet", mapper,
    Param.of(String.class, "name", "User's name"),
    Param.of(Integer.class, "limit", "Max results", false, "10")
);
// → { type: object, properties: { name: {type:string,...}, limit: {type:integer,default:10,...} }, required: [name] }

// Coercion
String name = ParamCoercion.coerce(invocation.getArguments(), nameParam, mapper);
Integer limit = ParamCoercion.coerce(invocation.getArguments(), limitParam, mapper); // returns 10 if absent

[Copilot]

Pull request overview

Adds extracted, package-private runtime helpers in the Java SDK to (a) build JSON Schema from Param<?> descriptors and (b) coerce invocation argument maps into typed Java values, intended as internal foundations for the Param<T>-based lambda tool ergonomics work (Phase 4.3 of #1810).

Changes:

• Added ParamSchema to build JSON Schema Map<String, Object> structures from Param<?>... and map Class<?> → schema fragments.
• Added ParamCoercion to coerce Map<String,Object> invocation args into typed values and parse validated string defaults.
• Updated the internal Phase 4 checklist document to mark Phase 4.3 complete.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/tool/ParamSchema.java	New internal schema builder and Class<?>→schema mapper for Param<?> descriptors.
java/src/main/java/com/github/copilot/tool/ParamCoercion.java	New internal argument/default coercion helper for Param<T> invocation.
1810-java-tool-ergonomics-tool-as-lambda-remove-before-merge/1810-ignorance-reduction-for-implementation-plan.md	Marks Phase 4.3 as completed in the implementation plan.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 5
• Review effort level: Low

[Copilot]

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Low

[github-actions]

Cross-SDK Consistency Review ✅

This PR adds two package-private Java classes (ParamSchema, ParamCoercion) as internal implementation details backing the Param<T> public API (introduced in Phase 4.1). No new public API surface is exposed.

Cross-SDK Alignment

The Java Param<T> ergonomic pattern introduced in this series is functionally equivalent to the idiomatic parameter-typing approaches in all other SDKs:

SDK	Typed parameter mechanism	Schema generation	Arg coercion
Java	Param<T> descriptors	ParamSchema.buildSchema() (this PR)	ParamCoercion.coerce() (this PR)
Python	Pydantic BaseModel	model_json_schema()	model_validate()
Go	Typed struct + struct tags	google/jsonschema-go reflection	json.Unmarshal into typed struct
Rust	#[derive(JsonSchema)] struct	schemars::schema_for!()	serde_json::from_value()
.NET	Delegate params / AIFunction	Microsoft.Extensions.AI factory	Parameter binding via MEAI

Assessment

No cross-SDK inconsistencies introduced. The ParamSchema and ParamCoercion internals are implementation details of a Java-idiomatic API equivalent to what all other SDKs already provide through their own ecosystem tools. The choice to use explicit Param<T> descriptors rather than reflection-on-records (like Go/Rust/Python) is appropriate for Java given its annotation processing and generic type erasure constraints.

Generated by SDK Consistency Review Agent for issue #1877 · sonnet46 851.4K · ◷