Add Java low-level tool definition E2E test and skill [1/6]

[edburns]

Summary

Adds a new Java failsafe integration test (LowLevelToolDefinitionIT) and the accompanying replay proxy YAML snapshot that exercise the current explicit tool-definition APIs.

This is the first of six focused PRs that break apart the changes originally combined in #1692. It does not fix issue #1682; rather it establishes baseline E2E coverage of the low-level tool-definition API before the ergonomic annotations are introduced.

Changes

New: Java E2E integration test

• \java/src/test/java/com/github/copilot/LowLevelToolDefinitionIT.java
  Covers \CopilotTool.create, \createOverride, \getArgumentsAs(record),
  \getArguments(), available-tools filtering (\custom:*\ + \�uiltin:web_fetch),
  and mutable handler state (\currentPhase) asserted after tool execution.

New: Replay snapshot

• \ est/snapshots/tools/low_level_tool_definition.yaml
  Multi-turn replay snapshot: first exchange triggers the tool call, second
  exchange supplies the tool result and receives the final response.
  This snapshot is also used by PRs Fix snapshot filename collisions on case-insensitive filesystems #2–Fix issue-triage workflow to add labels via add-labels safe-output #6 (go, nodejs, python, rust, dotnet).

New: Copilot skill

• .github/skills/new-java-e2e-test-yaml-and-test/SKILL.md\ and \�xamples.md
  Packages the knowledge of creating net-new Java E2E integration tests with
  handcrafted YAML snapshots into a reusable Copilot skill.

Fix: abort snapshot

• \ est/snapshots/abort/should_abort_during_active_streaming.yaml
  Adds a second conversation entry to handle the cleared-history recovery
  code path that can occur after an abort during active streaming.

Related

• Issue: Java: Ergonomics: Defining tools #1682 (not fixed by this PR)
• Original combined PR: Start iterating on #1682 On branch edburns/1682-java-tool-ergonomics #1692 (will be closed once all 6 breakout PRs merge)

[Copilot]

Pull request overview

This PR adds baseline Java E2E (failsafe) coverage for the current “low-level” tool-definition APIs, along with a new replay-proxy snapshot and a reusable Copilot skill documenting how to add Java E2E tests backed by handcrafted YAML snapshots.

Changes:

• Added a new Java failsafe integration test that defines custom tools via ToolDefinition.create(...) / createOverride(...) and validates tool execution via a replay snapshot.
• Added a new replay-proxy YAML snapshot for the low-level tool-definition scenario.
• Added a new repository Copilot skill documenting the workflow for adding Java E2E tests + YAML snapshots.
• Extended an existing abort snapshot with an additional conversation entry for a recovery path.

Show a summary per file

File	Description
test/snapshots/tools/low_level_tool_definition.yaml	New replay snapshot for low-level tool definition E2E flow (custom tool calls + results).
test/snapshots/abort/should_abort_during_active_streaming.yaml	Adds an additional conversation entry to cover an abort recovery path.
java/src/test/java/com/github/copilot/LowLevelToolDefinitionIT.java	New Java failsafe IT that configures the proxy snapshot and exercises low-level tool-definition APIs.
.github/skills/new-java-e2e-test-yaml-and-test/SKILL.md	New Copilot skill describing how to add Java E2E tests and craft YAML snapshots.
.github/skills/new-java-e2e-test-yaml-and-test/examples.md	Examples supporting the new skill documentation.

Copilot's findings

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

[github-actions]

Cross-SDK Consistency Review ✅

I reviewed this PR against all six SDK implementations (Node.js, Python, Go, .NET, Rust, Java) for cross-language consistency.

Summary

No significant cross-SDK consistency gaps found. This PR is well-structured as part of an intentional incremental series.

---

Changes analyzed

File	Assessment
java/.../LowLevelToolDefinitionIT.java	New Java E2E test — snapshot shared for PRs #2–#6 ✅
test/snapshots/tools/low_level_tool_definition.yaml	Shared snapshot for all 6 SDKs ✅
test/snapshots/abort/should_abort_during_active_streaming.yaml	Backward-compatible fix for cleared-history recovery path ✅
.github/skills/new-java-e2e-test-yaml-and-test/	Java-specific Copilot skill — no SDK parity needed ✅

---

Feature parity check for APIs exercised in the new Java test

All APIs under test have consistent equivalents across SDKs (accounting for language idioms):

Java API	Node.js	Go	.NET	Python	Rust
ToolDefinition.create(name, desc, schemaMap, handler)	defineTool(name, { parameters: Record<string,unknown>, handler })	Tool{ Parameters: map[string]any, Handler }	AIFunctionDeclaration	Tool(name, desc, parameters: dict, handler)	define_tool(name, desc, handler)
ToolDefinition.createOverride(...)	defineTool("grep", { overridesBuiltInTool: true })	Tool{ OverridesBuiltInTool: true }	CopilotTool.OverridesBuiltInToolKey	overrides_built_in_tool=True	Tool::with_overrides_built_in_tool(true)
new ToolSet().addCustom("*").addBuiltIn("web_fetch")	new ToolSet().addCustom("*").addBuiltIn(...)	[]string{"custom:*", "builtin:web_fetch"} (idiomatic Go)	new ToolSet().AddCustom("*").AddBuiltIn(...)	ToolSet().add_custom("*").add_builtin(...)	raw vec of strings

Abort snapshot fix (lines 31–37 added)

This fix is additive — it adds a second conversation entry to handle the cleared-history recovery code path. All SDKs with abort tests (Go, Node.js, Python, .NET, Rust) share this snapshot. The change is backward-compatible: the first conversation still handles the normal case; the second is a fallback for when session history is cleared after abort. No action needed in other SDKs.

---

The incremental PR structure (6 PRs, one per SDK) is a sound approach: the shared snapshot is already in place so PRs #2–#6 can each add their equivalent test independently.

Generated by SDK Consistency Review Agent for issue #1721 · sonnet46 1.9M · ◷