As of 2026-07, the Copilot SDK for Java does not embed a Copilot runtime. Rather, it depends on one being available externally. This design decision was made before 2026-02. Now that the Rust Copilot runtime cdylib is nearing the point where it can be consumed as a native shared library, this decision must be revisited.
Work items in this Epic will make it so the Copilot SDK for Java embeds N platform-specific instances of the Rust Copilot runtime native library (runtime.node, a Rust cdylib), dynamically selecting and loading the correct library for the current platform at runtime via JNA.
The relevant platform dimensions are:
- OS: Windows, macOS, GNU/Linux
- CPU architecture: x86_64 (x64), aarch64 (arm64)
- Linux only — C runtime variant: glibc (mainstream distros: Debian 10+, Ubuntu 20.04+, RHEL 8+) vs. musl (Alpine Linux)
This yields 6 binaries for the common case (Windows × 2 + macOS × 2 + GNU/Linux × 2), or 8 binaries if Alpine/musl Linux support is also required. The correct binary is selected 100% deterministically at runtime — no heuristics are needed — using System.getProperty("os.name"), System.getProperty("os.arch"), and (on Linux) inspection of the ELF PT_INTERP segment of /proc/self/exe to distinguish glibc from musl.
The library is loaded in-process via JNA using approximately 12 fixed C ABI entry points (copilot_runtime_server_create, copilot_runtime_connection_open, etc.). All API methods are dispatched as JSON-RPC over this in-process connection; no Node.js process is required by the host. (Note: during the current transitional period while the Rust port is in progress, the runtime library may internally spawn a short-lived Node.js child process to service method bodies not yet ported to Rust. This internal dependency shrinks with each port PR and is expected to disappear entirely once the migration is complete.)
The cli-native.node addon — which provides ICU4X text segmentation, Win32 APIs, and terminal UI helpers — is a CLI-only artifact and is not needed by the Java SDK.
This decision is based on the assumption that embedding N platform-specific native libraries remains acceptably compact. Current measured sizes (release cli-1.0.69-2): each runtime.node binary ranges from 48 to 68 MB uncompressed. The 6-platform set compresses to approximately 132 MB within a JAR (deflate ~40%); the 8-platform set to approximately 180 MB.
Internal tracker: https://devdiv.visualstudio.com/DevDiv/_workitems/edit/3028097
As of 2026-07, the Copilot SDK for Java does not embed a Copilot runtime. Rather, it depends on one being available externally. This design decision was made before 2026-02. Now that the Rust Copilot runtime cdylib is nearing the point where it can be consumed as a native shared library, this decision must be revisited.
Work items in this Epic will make it so the Copilot SDK for Java embeds N platform-specific instances of the Rust Copilot runtime native library (
runtime.node, a Rust cdylib), dynamically selecting and loading the correct library for the current platform at runtime via JNA.The relevant platform dimensions are:
This yields 6 binaries for the common case (Windows × 2 + macOS × 2 + GNU/Linux × 2), or 8 binaries if Alpine/musl Linux support is also required. The correct binary is selected 100% deterministically at runtime — no heuristics are needed — using
System.getProperty("os.name"),System.getProperty("os.arch"), and (on Linux) inspection of the ELF PT_INTERP segment of/proc/self/exeto distinguish glibc from musl.The library is loaded in-process via JNA using approximately 12 fixed C ABI entry points (
copilot_runtime_server_create,copilot_runtime_connection_open, etc.). All API methods are dispatched as JSON-RPC over this in-process connection; no Node.js process is required by the host. (Note: during the current transitional period while the Rust port is in progress, the runtime library may internally spawn a short-lived Node.js child process to service method bodies not yet ported to Rust. This internal dependency shrinks with each port PR and is expected to disappear entirely once the migration is complete.)The
cli-native.nodeaddon — which provides ICU4X text segmentation, Win32 APIs, and terminal UI helpers — is a CLI-only artifact and is not needed by the Java SDK.This decision is based on the assumption that embedding N platform-specific native libraries remains acceptably compact. Current measured sizes (release
cli-1.0.69-2): eachruntime.nodebinary ranges from 48 to 68 MB uncompressed. The 6-platform set compresses to approximately 132 MB within a JAR (deflate ~40%); the 8-platform set to approximately 180 MB.Internal tracker: https://devdiv.visualstudio.com/DevDiv/_workitems/edit/3028097