feat(java): implement ToolDefinition.from* lambda overloads (Phase 4.2)

[Copilot]

Phase 4.2 of #1810: adds typed ToolDefinition.from* factory methods so tools can be defined inline at the call site using standard JDK lambdas, without annotation processing.

New API surface

ToolDefinition factory overloads — 10 new @CopilotExperimental static methods:

Family	Arities
from(name, desc, …)	0-arg Supplier<R>, 1-arg Function<T1,R>, 2-arg BiFunction<T1,T2,R>
fromAsync(name, desc, …)	same shapes, handlers return CompletableFuture<R>
fromWithToolInvocation(name, desc, …)	0-arg Function<ToolInvocation,R>, 1-arg BiFunction<T1,ToolInvocation,R>
fromAsyncWithToolInvocation(name, desc, …)	same, async

Fluent copy-style modifiers on ToolDefinition (return a new record copy):

• overridesBuiltInTool(boolean), skipPermission(boolean), defer(ToolDefer)

Param<T> (from Phase 4.1 base branch) — runtime parameter metadata mirroring @CopilotToolParam semantics.

Example

Param<String> phase = Param.of(String.class, "phase", "Current phase");

// sync, 1 arg
ToolDefinition report = ToolDefinition.from(
        "report_phase", "Sets the current phase",
        phase,
        p -> "Phase set to " + p)
    .skipPermission(true);

// async + ToolInvocation context
ToolDefinition ctx = ToolDefinition.fromAsyncWithToolInvocation(
        "report_phase_async", "Sets phase, returns call id",
        phase,
        (p, inv) -> CompletableFuture.completedFuture(
                "phase=" + p + ", callId=" + inv.getToolCallId()));

Internals

• buildSchemaFromParams(Param<?>...) — runtime JSON Schema generation from Param<T> descriptors, mirroring the compile-time SchemaGenerator
• coerceArg() / coerceDefaultValue() — type-safe argument extraction via ObjectMapper; default values are parsed explicitly (integers, booleans, enums, etc.) rather than relying on Jackson string coercion
• formatResult() — enforces existing result contract: String passthrough, null → "Success", anything else JSON-serialized
• Fail-fast validation at construction: blank name/description, null params/handlers, duplicate param names

[Copilot]

Pull request overview

Adds a new Java ergonomic API for defining Copilot tools inline using JDK lambdas (sync/async, with/without ToolInvocation), plus fluent “copy” modifiers to set tool flags on ToolDefinition records. This expands the Java SDK’s tool-definition options beyond annotation processing while keeping schema generation and argument/result coercion inside the runtime.

Changes:

• Added 10 new ToolDefinition.from* static factory overloads to define tools via lambdas (sync/async, with/without ToolInvocation, 0–2 args).
• Added fluent copy-style modifiers on ToolDefinition to set overridesBuiltInTool, skipPermission, and defer.
• Implemented runtime JSON schema generation (buildSchemaFromParams / schemaForClass) and argument/default/result coercion helpers.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/rpc/ToolDefinition.java	Adds lambda-based tool factory overloads, fluent modifiers, and runtime schema/coercion helpers for Param<?>-described tool arguments.

Review details

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

[Copilot]

Review details

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

[Copilot]

Review details

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

[Copilot]

Review details

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

[Copilot]

Review details

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

[Copilot]

Review details

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

[github-actions]

✅ Cross-SDK Consistency Review

Summary: This PR brings Java to feature parity with the other five SDKs. No cross-SDK consistency issues found.

What this PR adds

New Java API	Equivalent in other SDKs
ToolDefinition.from(name, desc, () -> ...) — 0-arg	Node.js handler?, Python 0-param def fn(): ..., .NET/Rust
ToolDefinition.from(name, desc, p1, p -> ...) — 1 typed arg	Go DefineTool[T,U](...), Python 1-param handler, .NET Delegate
fromWithToolInvocation(...) — passes ToolInvocation context	Python 1-param def fn(inv: ToolInvocation): ..., Go func(T, inv), .NET binding
fromAsync(...) / fromAsyncWithToolInvocation(...)	Python async def, Node.js Promise, .NET Task, Rust async
.overridesBuiltInTool(bool) / .skipPermission(bool) / .defer(...) fluent modifiers	Node.js overridesBuiltInTool/skipPermission/defer fields, Python kwargs, Go struct fields, .NET CopilotToolOptions, Rust with_overrides_built_in_tool()/with_skip_permission()/with_defer()

Cross-SDK feature matrix (post-PR)

Capability	Node.js	Python	Go	.NET	Rust	Java
Inline 0-arg handler	✅	✅	✅	✅	✅	✅
Inline typed-param handler	✅	✅	✅	✅	✅	✅
ToolInvocation context in handler	✅	✅	✅	✅	✅	✅
Async handler support	✅	✅	✅	✅	✅	✅
overridesBuiltInTool	✅	✅	✅	✅	✅	✅
skipPermission	✅	✅	✅	✅	✅	✅
defer mode	✅	✅	✅	✅	✅	✅

The Param<T> metadata class is an idiomatic Java solution for carrying runtime parameter type information — other languages address this differently (Python Pydantic models, Go generics, .NET reflection, Rust schemars derive), so no changes are needed elsewhere.

API naming is consistent with each language's conventions: overridesBuiltInTool (camelCase) in Java and Node.js, overrides_built_in_tool (snake_case) in Python and Rust, OverridesBuiltInTool (PascalCase) in Go and .NET.

Generated by SDK Consistency Review Agent for issue #1857 · sonnet46 1.3M · ◷