feat(java): Add ToolDefinition.fromObject() and fromClass() registration API

[Copilot]

Fixes #1761 .

Adds the runtime registration API that loads processor-generated $$CopilotToolMeta companion classes and returns List<ToolDefinition> with fully working handlers. This is task 4.4 in the tool ergonomics epic.

Changes

• ToolDefinition.java — two new @CopilotExperimental static methods:

  • fromObject(Object) — for instance methods annotated with @CopilotTool
  • fromClass(Class<?>) — for static @CopilotTool methods (passes null instance)
  • Private loadDefinitions() uses Class.forName with the target classloader, setAccessible(true), and passes a configured ObjectMapper
  • ConfiguredMapperHolder — lazy-init mapper matching JsonRpcClient.createObjectMapper() (JavaTimeModule, lenient unknown-props, ISO dates, NON_NULL)
  • Throws IllegalStateException with actionable message if $$CopilotToolMeta not found — no reflection fallback

• ToolDefinitionFromObjectTest.java — 13 gating tests with hand-written meta fixtures covering: tool discovery, schema validation, handler invocation (String/void/CompletableFuture), argument coercion (primitives + enum), default values, missing-class error, java.time deserialization via ObjectMapper contract, override flag, and ToolDefer.NONE → null JSON omission

Usage

class MyTools {
    @CopilotTool("Get weather for a city")
    public String getWeather(@Param("City name") String city) {
        return fetchWeather(city);
    }
}

// At runtime — processor must have run at compile time
List<ToolDefinition> tools = ToolDefinition.fromObject(new MyTools());
session.setTools(tools);

[Copilot]

Pull request overview

Adds a Java runtime registration API for Copilot tools by loading processor-generated $$CopilotToolMeta companion classes and returning List<ToolDefinition> with invocation handlers, plus a new end-to-end-style test suite and fixtures to validate tool discovery and invocation behavior.

Changes:

• Added ToolDefinition.fromObject(Object) and ToolDefinition.fromClass(Class<?>) plus reflective loading of $$CopilotToolMeta.definitions(...) with an SDK-configured ObjectMapper.
• Added a comprehensive ToolDefinitionFromObjectTest covering discovery, schema, handler invocation patterns, argument coercion, default values, override flag, and java.time deserialization behavior.
• Added multiple @CopilotTool fixture classes and corresponding $$CopilotToolMeta fixtures used by the new tests.

Show a summary per file

File	Description
java/src/main/java/com/github/copilot/rpc/ToolDefinition.java	Adds experimental tool discovery/registration APIs and shared ObjectMapper config used by generated meta handlers.
java/src/test/java/com/github/copilot/rpc/ToolDefinitionFromObjectTest.java	Adds tests validating fromObject(...) behavior end-to-end, including serialization expectations.
java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools.java	Fixture: basic instance tools with string/int args.
java/src/test/java/com/github/copilot/rpc/fixtures/SimpleTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers for SimpleTools.
java/src/test/java/com/github/copilot/rpc/fixtures/MultiReturnTools.java	Fixture: covers String/void/CompletableFuture return patterns.
java/src/test/java/com/github/copilot/rpc/fixtures/MultiReturnTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers for MultiReturnTools.
java/src/test/java/com/github/copilot/rpc/fixtures/ArgCoercionTools.java	Fixture: mixed primitive/boolean/enum argument coercion.
java/src/test/java/com/github/copilot/rpc/fixtures/ArgCoercionTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers for ArgCoercionTools.
java/src/test/java/com/github/copilot/rpc/fixtures/DefaultValueTools.java	Fixture: defaulted parameter behavior.
java/src/test/java/com/github/copilot/rpc/fixtures/DefaultValueTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers for DefaultValueTools.
java/src/test/java/com/github/copilot/rpc/fixtures/DateTimeTools.java	Fixture: java.time parameter support.
java/src/test/java/com/github/copilot/rpc/fixtures/DateTimeTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers using ObjectMapper conversion for LocalDateTime.
java/src/test/java/com/github/copilot/rpc/fixtures/OverrideTools.java	Fixture: overriding a built-in tool name.
java/src/test/java/com/github/copilot/rpc/fixtures/OverrideTools$$CopilotToolMeta.java	Fixture meta: tool definitions + handlers validating override flag propagation.

Copilot's findings

• Files reviewed: 14/14 changed files
• Comments generated: 4

[github-actions]

Cross-SDK Consistency Review ✅

All 16 changed files in this PR are Java-only (java/src/). The new ToolDefinition.fromObject() / fromClass() methods are Java-idiomatic and do not create inconsistencies with other SDK implementations.

Tool registration approaches across SDKs

SDK	Pattern
Node.js/TypeScript	defineTool<T>() — generic function with Zod/type-inferred schema
Python	@define_tool decorator — per-function, Pydantic model schema inference
Go	DefineTool[T, U] — generic function with struct-based schema
.NET	CopilotTool.DefineTool(Delegate, ...) — reflection-based via AIFunctionFactory
Rust	ToolHandler trait — explicit per-tool trait implementation
Java	ToolDefinition.create() + new fromObject() / fromClass() — annotation + processor

Rationale

The annotation-processor pattern (@CopilotTool + $$CopilotToolMeta companion class) is specific to Java's APT/javac ecosystem. Each other SDK already ships its own idiomatic "define a tool" ergonomic API:

• Python's @define_tool decorator is already the equivalent of Java's @CopilotTool.
• .NET delegates to AIFunctionFactory.Create for schema inference.
• Go and TypeScript use generics for typed parameter schema generation.
• Rust uses the ToolHandler trait.

The @CopilotExperimental gate is appropriate since the feature depends on the annotation processor running at compile time. No changes are needed in other SDKs.

Generated by SDK Consistency Review Agent for issue #1779 · sonnet46 1.2M · ◷