Bring Java SDK cookbook to .NET parity

[brunoborges]

Pull Request Checklist

• I have read and followed the CONTRIBUTING.md guidelines.
• I have read and followed the Guidance for submissions involving paid services.
• My contribution adds a new instruction, prompt, agent, skill, workflow, or canvas extension file in the correct directory.
• The file follows the required naming convention.
• The content is clearly structured and follows the example format.
• I have tested my instructions, prompt, agent, skill, workflow, or canvas extension with GitHub Copilot.
• I have run npm start and verified that README.md is up to date.
• I am targeting the main branch for this pull request.

---

Description

The Java cookbook still referenced the archived standalone SDK and lacked recent .NET cookbook coverage. This brings Java to all eight .NET recipe topics while linking SDK documentation and source examples to the official github/copilot-sdk monorepo.

• Migrate Java recipes and snippets to released SDK 1.0.21 package names and typed MCP configuration.
• Add an experimental in-process runtime recipe, including a model-free --ping check, platform classifiers, JNA setup, and lifecycle limitations.
• Add message-provenance guidance and per-session tool search, enabling tool deferral in the runnable PR visualization example.
• Add Java-specific setup and safe testing instructions without replacing the existing recipe workflows.

---

Type of Contribution

• New instruction file.
• New prompt file.
• New agent file.
• New plugin.
• New skill file.
• New agentic workflow.
• New canvas extension.
• Update to existing instruction, prompt, agent, plugin, skill, workflow, or canvas extension.
• Other (please specify): Java SDK cookbook documentation and runnable JBang examples.

---

Additional Notes

The resource-addition and resource-testing checklist items are N/A: this changes cookbook examples, not instructions, prompts, agents, skills, workflows, or extensions.

Validation:

• npm start: passed; generated documentation and marketplace output remained unchanged.
• for file in cookbook/copilot-sdk/java/recipe/*.java; do jbang build --quiet "$file" || exit; done: passed for all eight recipes.
• jbang --deps com.github:copilot-sdk-java-runtime:1.0.21:darwin-arm64 cookbook/copilot-sdk/java/recipe/InProcessRuntime.java --ping: passed native startup, ping, and shutdown on Apple Silicon.
• python3 "$COPILOT_SESSION_ARTIFACTS/validate-cookbook.py": passed using a session-local validation harness (not committed). Compiled 16 standalone documentation classes, 20 contextual snippets, and eight recipes with javac --release 17; verified eight-topic parity, 133 local links, 13 official SDK links, the experimental-API anchor, and all eight published native classifiers.
• Additional session-local checks passed for message-source/tool-search/MCP serialization, rejected in-process options, and both environment-selected stdio and in-process startup/ping/shutdown.
• bash eng/fix-line-endings.sh: passed with a macOS-compatible sed shim.
• git --no-pager diff --check: passed.

Java requires an explicit platform runtime artifact and JNA for native transport, plus Java's experimental annotation opt-in instead of .NET's diagnostic suppression. Native execution was tested only on macOS arm64; other platforms and model-backed/MCP/browser end-to-end runs were not executed.

---

By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.

[github-actions]

🚦 Submission status: 👀 Ready for review

Risk tier: merge-risk:medium — New or substantially changed resource without privileged execution
Required to merge: passing submission-gate checks plus 1 approval from reviewers with write access.

Why this tier

• Adds 2 file(s), e.g. cookbook/copilot-sdk/java/in-process-runtime.md
• Changes 850 lines (low-risk limit is 40)

Automated checks

Check	Status	Details
Line endings	✅ Passed	Passed · logs
Spelling	✅ Passed	Passed · logs
Contributor reputation	✅ Passed	Passed · logs
Duplicate resource scan	✅ Passed	Passed · logs
PR quality signal	✅ Passed	Passed · logs

Review

• Approvals: 0/1
• Assigned reviewer: edburns, jdubois
• Review target date: not set
• Still needed: 1 more approval(s)
• No staffed reviewer pool owns these files yet; any reviewer with write access counts as the domain reviewer.

Commands

Command	Who	What it does
/rerun-checks	PR author, maintainers	Re-runs failed or incomplete checks and re-evaluates this gate
/request-review	PR author, maintainers	Asks the review rotation to assign a reviewer (adds needs-reviewer)

_{Updated for f026c24 · gate run · This comment is maintained automatically — see submission gate docs.}

[github-actions]

🟡 Contributor Reputation Check: MEDIUM risk

Check	Risk
Profile	MEDIUM
Credential audit	NONE

Maintainers: please review this contributor before merging.
See the workflow run for full details.
Automated check powered by AGT.

[Copilot]

🟢 Approval recommended

The examples align with the released SDK APIs, include appropriate safety guidance, and have credible validation evidence.

0 open findings

What changed in this PR

Updates the Java SDK cookbook to match current .NET coverage and the official SDK monorepo.

Changes:

• Migrates Java examples to SDK 1.0.21 APIs.
• Adds in-process runtime documentation and example.
• Adds tool search, message provenance, prerequisites, and safety guidance.

File	Description
cookbook/​copilot-sdk/​README.md	Updates links, Java setup, and recipe counts.
cookbook/​copilot-sdk/​java/​README.md	Documents SDK migration and new recipe.
cookbook/​copilot-sdk/​java/​accessibility-report.md	Uses typed MCP configuration.
cookbook/​copilot-sdk/​java/​error-handling.md	Adds provenance and shutdown guidance.
cookbook/​copilot-sdk/​java/​in-process-runtime.md	Documents native in-process transport.
cookbook/​copilot-sdk/​java/​managing-local-files.md	Migrates example imports.
cookbook/​copilot-sdk/​java/​multiple-sessions.md	Migrates example imports.
cookbook/​copilot-sdk/​java/​persisting-sessions.md	Migrates persistence examples.
cookbook/​copilot-sdk/​java/​pr-visualization.md	Adds per-session tool search.
cookbook/​copilot-sdk/​java/​ralph-loop.md	Migrates loop examples.
cookbook/​copilot-sdk/​java/​recipe/​README.md	Adds prerequisites and safety instructions.
cookbook/​copilot-sdk/​java/​recipe/​AccessibilityReport.java	Uses SDK 1.0.21 typed MCP APIs.
cookbook/​copilot-sdk/​java/​recipe/​ErrorHandling.java	Migrates SDK packages.
cookbook/​copilot-sdk/​java/​recipe/​InProcessRuntime.java	Adds runnable native-runtime example.
cookbook/​copilot-sdk/​java/​recipe/​ManagingLocalFiles.java	Migrates SDK packages.
cookbook/​copilot-sdk/​java/​recipe/​MultipleSessions.java	Migrates SDK packages.
cookbook/​copilot-sdk/​java/​recipe/​PRVisualization.java	Enables tool-search deferral.
cookbook/​copilot-sdk/​java/​recipe/​PersistingSessions.java	Migrates SDK packages.
cookbook/​copilot-sdk/​java/​recipe/​RalphLoop.java	Migrates SDK packages.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The APIs, released version, platform classifiers, documentation links, and runnable-example guidance are consistent and adequately validated.

0 open findings

🧠 Review effort: Balanced

[edburns]

WIP reviewing:

1. In-process transport claims

1.1 Default and in-process transport behavior

PR claim

By default, CopilotClient manages a child process and communicates over
stdio or TCP. Hosts that need to avoid a separate process for the SDK
transport can load the native Copilot runtime directly into the JVM instead.

The runtime's tools can still launch subprocesses; in-process transport is
not a sandbox.

Proposed usage

var options = new CopilotClientOptions()
    .setConnection(RuntimeConnection.forInProcess());

try (var client = new CopilotClient(options)) {
    client.start().get(30, TimeUnit.SECONDS);
    // Create and use sessions normally.
}

SME review

• Is “manages a child process” an accurate description of every default
  Java client configuration?

edburns> Yes. And I suggest "spawns a child process" is more accurate.

• Are stdio and TCP the complete set of relevant subprocess transport
  forms?

edburns> Yes.

• Does RuntimeConnection.forInProcess() avoid only the SDK transport
  process, while runtime tools remain able to start arbitrary subprocesses?

edburns> Change the wording to

In-process hosting only removes the separate Copilot runtime process. Enabled built-in tools such as shell execution, configured local MCP servers, and application-defined tool handlers may still start child processes according to their implementation, configuration, permissions, and sandbox policy.

• Should the text distinguish loading the runtime “inside the JVM” from
  loading a native library into the JVM process?

edburns> Say this instead:

Hosts that need to avoid a separate runtime process can load the native Copilot runtime library into the JVM process.

1.2 Native runtime dependencies and classifiers

PR claim

Java needs JNA and a platform-specific native runtime artifact of the same
SDK version.

The proposed dependencies are:

<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.21</version>
</dependency>
<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java-runtime</artifactId>
    <version>1.0.21</version>
    <classifier>linux-x64</classifier>
</dependency>
<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna</artifactId>
    <version>5.19.1</version>
</dependency>

PR claim: published classifier mapping

Platform	Claimed classifiers
Linux with glibc	linux-x64, linux-arm64
Linux with musl	linuxmusl-x64, linuxmusl-arm64
Windows	win32-x64, win32-arm64
macOS	darwin-x64, darwin-arm64

SME review

• Are all eight classifier names exact?

edburns> Yes. Manually checked.

• Are all eight artifacts published for SDK version 1.0.21?

edburns> Yes. Manually checked.

• Must copilot-sdk-java and copilot-sdk-java-runtime always have
  identical versions?

edburns> Yes.

• Is JNA 5.19.1 required, recommended, or merely the version currently
  used by the SDK?

edburns> It is more accurate to say the system is tested with JNA 5.19.1.

• Does the runtime artifact transitively supply JNA, or must applications
  declare it explicitly?

edburns> Applications must declare it explicitly.

• Are there additional OS, libc, or architecture restrictions that should
  be stated?

edburns> Yes, there are. I suggest this statement:

The glibc Linux classifiers require glibc 2.28 or newer. The musl classifiers dynamically link musl and are intended for compatible musl-based distributions such as Alpine Linux. Only x64 and ARM64 are supported.

• Is JDK 25 “recommended” by the SDK, or is Java 17 the only SDK-level
  requirement?

edburns> JDK 25 is required for the native classifier in process work.

[edburns]

See my comments.

#5085 (comment)
#5085 (comment)
#5085 (comment)

[jdubois]

Have a look at first at Ed's comments, I'll do a second review after that

[Copilot]

🟡 Changes recommended

The Windows CLI setup can select a PowerShell shim that prevents the recipes from starting.

1 open finding

• Windows CLI startup fails when resolveCliCommand selects copilot.ps1 · New

🧠 Review effort: Balanced

[brunoborges]

@edburns @jdubois, the requested corrections and recommended clarifications are now pushed. This includes message-source semantics, demo-only permission warnings throughout the Java cookbook, tool-search behavior and version-qualified defaults, and native transport/JDK/dependency/lifecycle guidance. The Windows CLI setup finding is also fixed, and the inline review thread is resolved.

Could you please take another look? All eight runnable recipes and documentation snippets compile, and the native ping path was exercised on Java 17 and 25 on macOS arm64. Model-backed/MCP/browser end-to-end runs and Windows execution remain untested; the documentation now states those boundaries and does not claim to prove native teardown success.

[Copilot]

🟢 Approval recommended

No unresolved defects were identified; version-pinned references and reported validation support the examples, with native testing limitations clearly documented.

0 open findings

1 resolved since last review

• Windows CLI startup fails when resolveCliCommand selects copilot.ps1

🧠 Review effort: Balanced

[Copilot]

🟢 Approval recommended

No blocking issues remain; pinned SDK references support the migration, and experimental runtime validation limits are clearly documented.

0 open findings

🧠 Review effort: Balanced