# GitHub Copilot SDK for Java

[![Build](https://github.com/github/copilot-sdk/actions/workflows/sdk.yml/badge.svg)](https://github.com/github/copilot-sdk/actions/workflows/sdk.yml)
[![Java 17+](https://img.shields.io/badge/Java-17%2B-blue?logo=openjdk&logoColor=white)](https://openjdk.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

#### Latest release

[![GitHub Release Date](https://img.shields.io/github/release-date/github/copilot-sdk)](https://github.com/github/copilot-sdk/releases)
[![GitHub Release](https://img.shields.io/github/v/release/github/copilot-sdk)](https://github.com/github/copilot-sdk/releases)
[![Maven Central](https://img.shields.io/maven-central/v/com.github/copilot-sdk-java)](https://central.sonatype.com/artifact/com.github/copilot-sdk-java)
[![Javadoc](https://javadoc.io/badge2/com.github/copilot-sdk-java/javadoc.svg?q=1)](https://javadoc.io/doc/com.github/copilot-sdk-java/latest/index.html)

## Background

Java SDK for programmatic control of GitHub Copilot CLI, enabling you to build AI-powered applications and agentic workflows. The Java SDK tracks the official GitHub Copilot SDK family (TypeScript, Python, Go, .NET, and Rust).

## Prerequisites

To use the SDK, you'll need:

- Java 17 or later. **JDK 25 recommended**. The distributed jar is a multi-release jar (MR-JAR) and is compiled on JDK 25 with `maven.compiler.release` set to 17. This means, when run on JDK 25 and later, the SDK automatically uses virtual threads for its default internal executor.

Managed stdio and TCP connections materialize the platform classifier's
`copilot-runtime[.exe]` and adjacent `runtime.node` by default. An explicit
`cliPath` or `COPILOT_CLI_PATH` environment variable overrides the bundled
runtime.

## Installation

### Maven

```xml
<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.14-preview.1</version>
</dependency>
```

### Gradle

```groovy
implementation 'com.github:copilot-sdk-java:1.0.14-preview.1'
```

### Snapshot builds

Snapshot builds of the next development version are published to Maven Central Snapshots. To use them, add the snapshot repository and depend on the development version:

#### Maven

```xml
<repositories>
    <repository>
        <id>central-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots><enabled>true</enabled></snapshots>
    </repository>
</repositories>

<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>1.0.15-preview.1-SNAPSHOT</version>
</dependency>
```

#### Gradle

```groovy
implementation 'com.github:copilot-sdk-java:1.0.15-preview.1-SNAPSHOT'
```

## In-process mode (experimental)

The SDK supports running the Copilot runtime **in-process** as a native library instead of spawning a separate CLI process. This eliminates process management overhead and simplifies deployment. In-process mode is currently experimental and supported on **linux-x64** (glibc), **linux-arm64** (glibc), **linuxmusl-x64**, **win32-x64**, **win32-arm64**, **darwin-x64**, and **darwin-arm64**.

Because in-process mode is experimental, see the [Using experimental APIs](#using-experimental-apis) section for how to opt in.

### Additional dependency

Add both the SDK and the platform-specific native runtime to your project:

```xml
<dependencies>
    <!-- Pure-Java SDK (~1.5 MB) -->
    <dependency>
        <groupId>com.github</groupId>
        <artifactId>copilot-sdk-java</artifactId>
        <version>${copilot.version}</version>
    </dependency>
    <!-- Add the native runtime for the target platform -->
    <dependency>
        <groupId>com.github</groupId>
        <artifactId>copilot-sdk-java-runtime</artifactId>
        <version>${copilot.version}</version>
        <classifier>linux-x64</classifier>
    </dependency>
    <!-- Use linux-arm64, linuxmusl-x64, win32-x64, win32-arm64, darwin-x64, or darwin-arm64 on those target platforms -->
    <!-- JNA (required for in-process mode) -->
    <dependency>
        <groupId>net.java.dev.jna</groupId>
        <artifactId>jna</artifactId>
        <version>5.19.1</version>
    </dependency>
</dependencies>
```

### Usage

Configure the client to use the in-process connection:

```java
CopilotClientOptions options = new CopilotClientOptions()
    .setConnection(RuntimeConnection.forInProcess());

CopilotClient client = new CopilotClient(options);
client.start().get();
```

## Quick Start

For experimental in-process AHP hosting, select a transport explicitly:
`client.startAhpHost(new AhpHostOptions().setLocalServer(new HostLocalServerOptions(null, null, null, null)))`.
The transport types are in `com.github.copilot.generated.rpc`. For GitHub Mission
Control, use `.setGithubEnvironment(new HostGitHubEnvironmentOptions("My host", "compute-id"))`
instead, or configure both transports. GitHub environment name and compute ID are
required; there is no implicit local listener. The host's `getUrl()`, `getToken()`,
and `getPid()` may return `null`; `getEnvironmentId()` returns the GitHub environment
ID when configured. Environment list/get/delete operations are available only
through the generated RPC API.
See [runtime-supervised AHP hosting](../docs/runtime-supervised-host.md) for creation
and resume callbacks, resident-session publication, ownership, and shared-snapshot E2Es.

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.generated.AssistantMessageEvent;
import com.github.copilot.generated.SessionUsageInfoEvent;
import com.github.copilot.rpc.MessageOptions;
import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.SessionConfig;

public class CopilotSDK {
    public static void main(String[] args) throws Exception {
        var lastMessage = new String[]{null};

        // Create and start client
        try (var client = new CopilotClient()) {
            client.start().get();

            // Create a session
            var session = client.createSession(
                new SessionConfig().setOnPermissionRequest(PermissionHandler.APPROVE_ALL).setModel("claude-sonnet-4.5")).get();


            // Handle assistant message events
            session.on(AssistantMessageEvent.class, msg -> {
                lastMessage[0] = msg.getData().content();
                System.out.println(lastMessage[0]);
            });

            // Handle session usage info events
            session.on(SessionUsageInfoEvent.class, usage -> {
                var data = usage.getData();
                System.out.println("\n--- Usage Metrics ---");
                System.out.println("Current tokens: " + data.currentTokens().intValue());
                System.out.println("Token limit: " + data.tokenLimit().intValue());
                System.out.println("Messages count: " + data.messagesLength().intValue());
            });

            // Send a message
            var completable = session.sendAndWait(new MessageOptions().setPrompt("What is 2+2?"));
            // and wait for completion
            completable.get();
        }

        boolean success = lastMessage[0] != null && lastMessage[0].contains("4");
        System.exit(success ? 0 : -1);
    }
}
```

When targeting MCP tools configured through `setMcpServers(...)`, remember the
runtime tool name is `<server-key>-<tool-name>`. For `setAvailableTools(...)`
and `setExcludedTools(...)`, prefer the source-qualified filter form
`mcp:<server-key>-<tool-name>`. For `CustomAgentConfig.setTools(...)` and
`DefaultAgentConfig.setExcludedTools(...)`, use `<server-key>-<tool-name>`
directly.

`CopilotClientOptions.setCwd(...)` sets the runtime process working directory, which otherwise inherits the current process working directory. `SessionConfig.setWorkingDirectory(...)` sets the session working directory, which otherwise defaults to the runtime process working directory.

`CopilotClientOptions.setExtensionLaunchProvider(...)` configures an experimental
connection-level resolver for extension launch profiles. The client installs the
reverse-RPC handler and registers the provider during startup before sessions can
be created.

### Installation confirmation (experimental)

`CopilotClientOptions.setInstallationConfirmationHandler(...)` configures the
connection-global `installations.confirm` receiver. The handler receives the
generated `InstallationConfirmationRequest` and an
`InstallationConfirmationContext`, then returns only an explicit
generated `InstallationDecision.CONFIRM`, `InstallationDecision.DECLINE` or
`InstallationDecision.CANCEL`. The SDK echoes the original challenge and review
fingerprint; it never infers approval and does not enable installation
capabilities or call a runtime registration RPC.

Match `operationId` and `policySessionId` against the original action on this
exact connection before presenting the complete review. Missing legacy session
metadata does not select a default session. Refuse unknown operations or
incomplete reviews.

Concurrent reviews are independent and do not block other client-global RPCs.
`context.getCancelled()` returns the single cancellation signal for the review.
It completes when the runtime's numeric `$/cancelRequest`, runtime-enforced
expiry, or loss of the original connection retires the review. Separately
spawned UI work should observe this signal and retire itself when it completes.
Dropping an outbound installation or OAuth future does not cancel that
operation.

`SessionConfig.setAskUserVariant(AskUserVariant.ELICITATION)` selects the
structured form-based `ask_user` tool when an elicitation handler is also set.
The default is `AskUserVariant.LEGACY`. Re-supply the option and handler through
`ResumeSessionConfig` on a cold resume.

To continue a pending turn after resuming a session, pass
`new ResumeSessionConfig().setContinuePendingWork(true)` to `resumeSession`.
Set it to `false` to opt out explicitly, or leave it unset to use the runtime
default.

For rotating per-session GitHub credentials, use
`SessionConfig.setGitHubTokenProvider(...)` (or the equivalent
`ResumeSessionConfig` setter) instead of `setGitHubToken(...)`:

```java
var config = new SessionConfig()
    .setGitHubTokenProvider(args ->
        acquireForHost(args.host()).thenApply(token ->
            GitHubTokenProviderResult.token(token, 8 * 60 * 60)))
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL);
```

The remaining lifetime is required and must be positive when the callback
completes; production GitHub tokens typically last eight hours. A static token
and a provider are mutually exclusive.

Initial acquisition runs during session creation or resume. Cancellation,
provider errors, and invalid token responses reject that operation instead of
falling back to ambient authentication. Idle sessions refresh only before their
next credential-consuming operation; there is no background refresh timer.

### Typed MCP installation and removal payloads (breaking change)

Three payloads in the experimental MCP installation and removal workflow are now sealed
interfaces with one record per variant, instead of `Object`, which brings Java into line
with the other SDKs. No other generated type changes.

| Field | Before | After |
| --- | --- | --- |
| `InstallationConfirmationRequest.review()` | `Object` | `InstallationReview` sealed interface (`InstallationReviewMcp` / `InstallationReviewSkill`, by `resource`); the MCP variant carries `McpInstallationReview` (`McpInstallationReviewInstall` / `McpInstallationReviewUninstall`, by `action`) and the Skill variant carries `SkillInstallationReview` |
| `McpInstallPlan.transportChoices()` | `List<Object>` | `List<McpPlanTransportChoice>` (`McpPlanTransportChoicePackage` / `McpPlanTransportChoiceRemote`, by `installMethod`) |
| `McpInstallationManagementResultOutcome.getOutcome()` / `setOutcome(...)` | `Object` | `McpInstallationManagementOutcome`, whose operation variant carries `McpInstallationOperationStatus` (by `phase`) |

## Message source

Use `MessageSource.SYSTEM` for application-generated system context and
`MessageSource.agent(id)` for messages from an identified agent:

```java
import com.github.copilot.rpc.MessageOptions;
import com.github.copilot.rpc.MessageSource;

session.send(new MessageOptions()
    .setPrompt("The background build completed successfully.")
    .setSource(MessageSource.SYSTEM)).get();

session.sendAndWait(new MessageOptions()
    .setPrompt("The review found no blocking issues.")
    .setSource(MessageSource.agent("reviewer"))).get();
```

Leave `source` unset to omit it from the request and retain the runtime's default
user-input behavior, or set `MessageSource.USER` explicitly. Source is independent
of delivery mode (`enqueue` or `immediate`) and does not configure the session's
system prompt.

Agent sources serialize as `agent-<id>`. Pass the agent ID without adding a
prefix. The SDK preserves its case and whitespace and rejects null IDs.
`sendAndWait` accepts the same source values as `send`. Sub-agent events remain
visible to listeners but do not complete the wait or supply its reply.
Synchronous listeners registered before `sendAndWait` finish processing the root
`session.idle` event before its future completes. Event listeners run in
registration order.

## Structured output (experimental)

Annotate a result record or class using the same compile-time schema-generation
approach as `@CopilotTool`. No additional schema dependency is needed:

```java
@CopilotResponse
public record Inventory(int count, String color) {}

Inventory inventory = session.sendAndWait(
    "Call get_inventory, then report the widget count and color.",
    Inventory.class
).get();
```

Enable annotation processing with `CopilotResponseProcessor` (automatically
discoverable alongside the SDK's existing processors), and opt in to experimental
APIs as described below. The processor reuses the custom-tool `SchemaGenerator`,
closing record/class objects for strict output. Its existing type-mapping
limitations apply: custom Jackson naming/converters and recursive types need an explicit schema.
Provider restrictions, including optional-field and dictionary restrictions,
still apply. Jackson deserialization is not full JSON Schema validation.

For an explicit schema, use `new MessageOptions().setPrompt(...).setResponseSchema(schema)`
with `send` or `sendAndWait`; schema-bearing `sendAndWait` returns the ordinary
message event. Typed overloads accept message options and a timeout, clone the
options, and reject explicit schemas and immediate delivery.

Schemas apply to one run, including tools, steering, and stop-hook corrections;
independent sends and subagents do not inherit them. Streaming stays text.
Structured waits return the last correlated root message without tool requests at
non-autopilot idle. Concurrent waits keep their own results; queued work can delay
idle. Aborts, session errors after the run starts, and missing final output fail.
Cancellation and timeout stop waiting without aborting the agent.

## Permission Handling

`PermissionHandler.APPROVE_ALL` approves requests when managed settings are disabled. When `enableManagedSettings` is true, it completes exceptionally. Custom handlers can inspect `request.getManagedApprovalRequired()` for human-facing confirmation logic.

When handling `PermissionRequestedEvent` directly, convert its generated event value with `PermissionRequest.fromJsonValue(event.getData().permissionRequest())` to access the typed metadata.

Custom handlers must check managed approval before applying kind-specific automatic decisions:

```java
import java.util.concurrent.CompletableFuture;

import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.PermissionRequestResult;

PermissionHandler handler = (request, invocation) -> {
    if (Boolean.TRUE.equals(request.getManagedApprovalRequired())) {
        return CompletableFuture.completedFuture(PermissionRequestResult.noResult());
    }

    return CompletableFuture.completedFuture(PermissionRequestResult.approveOnce());
};
```

## Try it with JBang

You can run the SDK without setting up a full Java project, by using [JBang](https://www.jbang.dev/).

See the full source of [`jbang-example.java`](sdk/jbang-example.java) for a complete example with more features like session idle handling and usage info events.

Or run it directly from the repository:

```bash
jbang https://github.com/github/copilot-sdk/blob/main/java/sdk/jbang-example.java
```

## Annotation-based tools and `ToolInvocation` context

When you define tools with `@CopilotTool`, parameters of type `ToolInvocation` are injected as runtime context and are not exposed in the tool schema.
`ToolInvocation` can appear before, between, or after schema-visible parameters.

```java
import com.github.copilot.rpc.ToolInvocation;
import com.github.copilot.tool.CopilotTool;
import com.github.copilot.tool.CopilotToolParam;

class ProgressTools {
    @CopilotTool("Reports the current phase and session")
    public String reportProgress(
            @CopilotToolParam("Current phase") String phase,
            ToolInvocation invocation) {
        return "phase=" + phase + ", sessionId=" + invocation.getSessionId();
    }
}
```

Position examples:

```java
@CopilotTool("Invocation first")
public String report(ToolInvocation invocation, @CopilotToolParam("Phase") String phase) { ... }

@CopilotTool("Invocation only")
public String onlyContext(ToolInvocation invocation) { ... }

@CopilotTool("Invocation middle")
public String report(@CopilotToolParam("Phase") String phase, ToolInvocation invocation, @CopilotToolParam("Limit") int limit) { ... }
```

## Inline lambda tool definitions (experimental)

For inline tool authoring at the session construction site, use `ToolDefinition.from(...)` with explicit parameter metadata:

```java
import com.github.copilot.rpc.ToolDefinition;
import com.github.copilot.rpc.ToolDefer;
import com.github.copilot.tool.Param;

ToolDefinition search = ToolDefinition
    .from(
        "search_items",
        "Searches indexed items by keyword",
        Param.of(String.class, "keyword", "Search keyword"),
        keyword -> "Searching for: " + keyword)
    .skipPermission(true)
    .defer(ToolDefer.AUTO);
```

### Parameter metadata with `Param.of(...)`

`Param.of(type, name, description)` creates a required parameter. For optional parameters with defaults:

```java
Param<Integer> limit = Param.of(Integer.class, "limit", "Max results", false, "10");
```

### Async handlers

Use `fromAsync` for asynchronous tool handlers:

```java
import java.util.concurrent.CompletableFuture;

ToolDefinition fetchData = ToolDefinition.fromAsync(
    "fetch_data",
    "Fetches data from remote source",
    Param.of(String.class, "url", "Data source URL"),
    url -> CompletableFuture.supplyAsync(() -> fetchRemote(url))
);
```

### ToolInvocation context injection

Inline tools can access `ToolInvocation` runtime context using `fromWithToolInvocation`:

```java
ToolDefinition reportPhase = ToolDefinition.fromWithToolInvocation(
    "report_phase",
    "Reports the current phase with invocation context",
    Param.of(String.class, "phase", "The current phase"),
    (phase, invocation) -> "phase=" + phase + ", toolCallId=" + invocation.getToolCallId()
);
```

For async with `ToolInvocation`, use `fromAsyncWithToolInvocation`.

### Fluent option modifiers

Chain fluent modifiers to set tool options:

- `.skipPermission(boolean)` — bypass permission prompts
- `.defer(ToolDefer)` — control deferred execution (`AUTO`, `NEVER`)
- `.overridesBuiltInTool(boolean)` — shadow built-in tools

For design context and decision rationale, see [ADR-006](docs/adr/adr-006-tool-definition-inline.md).

## Auto routing tiers

Use `CapiSessionOptions.setAutoTier(...)` to select `AutoTier.EFFICIENCY`,
`AutoTier.BALANCE`, `AutoTier.INTELLIGENCE`, or `AutoTier.FAST`. This option is
meaningful only with model `auto` (Auto mode V2).
It requires a runtime version that supports `capi.autoTier`.
`AutoTier.FAST` is an integrator-only latency preset, not a first-party GitHub
Copilot product preference — the SDK does not decide Fast eligibility or apply
it implicitly.

```java
import com.github.copilot.rpc.AutoTier;
import com.github.copilot.rpc.CapiSessionOptions;
import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.SessionConfig;

var config = new SessionConfig()
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setModel("auto")
    .setCapi(new CapiSessionOptions().setAutoTier(AutoTier.BALANCE));
```

The same options work with `ResumeSessionConfig.setCapi(...)` and can be combined
with `setEnableWebSocketResponses(false)`. The SDK omits an unset (`null`) tier:
the runtime chooses its default on create and preserves the persisted/current
tier on resume. An explicit tier overrides the persisted tier on cold resume. On
resident resume, a different tier requests a safe switch applied after the
resume succeeds; it cannot change a turn that is already in flight. The SDK does not choose a default or manage tier persistence.
See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence)
for the lifecycle rules.

### Changing the Auto tier during a session

Change the Auto routing preference without changing the selected model. The runtime does not apply the preference immediately: it records the request and commits it only when a later user turn using the `auto` model successfully obtains a usable model from the provider, so a `pending` status confirms acceptance rather than effect. Only the most recent request survives.

Watch for the outcome through the `session.model_change` event on success or the ephemeral `session.auto_tier_switch_failed` event on failure. A failed activation leaves the incumbent effective tier unchanged. Read the authoritative committed, pending, and activating preferences at any time through the session's `model.getCurrent` RPC method.

```java
var result = session.setAutoTier(AutoTier.INTELLIGENCE).get();
if (result.status() == ModelSwitchAutoTierStatus.PENDING) {
    // Accepted, but not yet in effect.
}

// Return to the provider's default Auto routing.
session.setAutoTier(null).get();
```

`setModel(SetModelOptions)` accepts the same preference through `SetModelOptions.setAutoTier(...)`, which stages the tier atomically with selecting `auto`. Call `setResetAutoTier(true)` instead to return to provider-default routing; the two options are mutually exclusive.

## Session Store

`enableSessionStore` on `SessionConfig` enables the cross-session store for search and retrieval across sessions. When unset in the default `CopilotClientMode.COPILOT_CLI` mode, the runtime default applies (enabled). In `CopilotClientMode.EMPTY` mode, defaults to disabled.

## Memory

Sessions can opt into persistent memory, allowing the agent to read and write memory across turns. Memory is configured per session and applies to both `createSession` and `resumeSession`.
For more background, see [About GitHub Copilot Memory](https://docs.github.com/en/copilot/concepts/agents/copilot-memory).

```java
import com.github.copilot.rpc.MemoryConfiguration;
import com.github.copilot.rpc.PermissionHandler;
import com.github.copilot.rpc.ResumeSessionConfig;
import com.github.copilot.rpc.SessionConfig;

// Enable memory for a new session
var session = client.createSession(new SessionConfig()
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setModel("gpt-5")
    .setMemory(new MemoryConfiguration().setEnabled(true))
).get();

// Disable memory for a new session
var sessionNoMemory = client.createSession(new SessionConfig()
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setModel("gpt-5")
    .setMemory(new MemoryConfiguration().setEnabled(false))
).get();

// Configure memory while resuming
var resumed = client.resumeSession(sessionId, new ResumeSessionConfig()
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    .setMemory(new MemoryConfiguration().setEnabled(true))
).get();
```

When `memory` is left unset, no memory configuration is sent and the runtime default applies. In the default `CopilotClientMode.COPILOT_CLI` the SDK leaves `memory` unset so the runtime applies its own default, while `CopilotClientMode.EMPTY` defaults `memory` to disabled unless you set it explicitly.

## JSON-RPC error handling

Server error responses surface as `com.github.copilot.JsonRpcException`, a
`RuntimeException` with `getCode()`, `getMessage()`, and `getData()`. The data is a
Jackson `JsonNode`: objects, arrays, strings, numbers, and booleans retain their
JSON types, including empty values, zero, and false. Numeric fidelity follows
Jackson's existing parser. Omitted data returns Java `null`; explicit JSON `null`
returns a `NullNode` (`data.isNull()` is true).

Future wrapping is unchanged. With `get()`, inspect the cause of
`ExecutionException`:

```java
import com.github.copilot.JsonRpcException;
import java.util.concurrent.ExecutionException;

try {
    client.ping("hello").get();
} catch (ExecutionException ex) {
    if (ex.getCause() instanceof JsonRpcException rpcError) {
        System.err.println("RPC " + rpcError.getCode() + ": " + rpcError.getMessage());
        var data = rpcError.getData();
        if (data != null && !data.isNull()) {
            // Inspect data according to the server's error contract.
        }
    } else {
        throw ex; // Transport and local failures are not JSON-RPC error responses.
    }
}
```

The enclosing method must handle or declare both `InterruptedException` and the
rethrown `ExecutionException`.
With `join()`, the wrapper is `CompletionException` instead:

```java
import java.util.concurrent.CompletionException;

try {
    client.ping("hello").join();
} catch (CompletionException ex) {
    if (ex.getCause() instanceof JsonRpcException rpcError) {
        System.err.println("RPC " + rpcError.getCode() + ": " + rpcError.getMessage());
        var data = rpcError.getData();
        if (data == null) {
            // The data member was omitted.
        } else if (data.isNull()) {
            // The server explicitly supplied JSON null.
        } else {
            // Inspect data according to the server's error contract.
        }
    } else {
        throw ex;
    }
}
```

Error data is not appended to `getMessage()` or `toString()`. Avoid logging it
indiscriminately: server-provided data may contain sensitive information.
`getData()` returns the shared Jackson node, not an immutable snapshot. Use
`deepCopy()` before modifying a container node, particularly when multiple
observers share the failed future.

## Using experimental APIs

Some SDK APIs are marked as experimental with `@CopilotExperimental`. These APIs may change or be removed in future versions without notice.

By default, referencing an experimental API from your code causes a **compile-time error**:

```
error: Use of experimental API 'ExperimentalType' in field type is not allowed.
       Add @AllowCopilotExperimental or compiler option -Acopilot.experimental.allowed=true to opt in.
```

To opt in and use experimental APIs, either:

- annotate the consuming class, method, or constructor with `@AllowCopilotExperimental`, or
- pass the annotation processor option `-Acopilot.experimental.allowed=true` to the Java compiler.

### In code

```java
import com.github.copilot.AllowCopilotExperimental;
import test.ExperimentalType;

@AllowCopilotExperimental
public class Consumer {
    private ExperimentalType field;

    public ExperimentalType getIt() {
        return field;
    }

    @AllowCopilotExperimental
    public ExperimentalType echo(ExperimentalType value) {
        return value;
    }
}
```

### Maven

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-Acopilot.experimental.allowed=true</arg>
        </compilerArgs>
    </configuration>
</plugin>
```

### Gradle

```groovy
tasks.withType(JavaCompile) {
    options.compilerArgs += ['-Acopilot.experimental.allowed=true']
}
```

### What the processor catches

The processor detects usage of experimental types in **declarations**:

| Usage pattern | Caught? |
|---|---|
| Field declared with experimental type | ✅ |
| Method parameter of experimental type | ✅ |
| Method return type is experimental | ✅ |
| `extends` / `implements` experimental type | ✅ |
| `throws` an experimental exception type | ✅ |
| Generic type argument is experimental (e.g., `List<ExperimentalType>`) | ✅ |

### Known limitations

The processor uses standard JSR 269 annotation processing APIs for maximum portability (works with javac, ECJ/Eclipse, and any compliant compiler). This means it inspects **declarations only**, not expressions inside method bodies. The following patterns are **not caught** by the processor:

| Usage pattern | Caught? | Workaround |
|---|---|---|
| `new ExperimentalType()` in a method body (no field/param declaration) | ❌ | Use the compiler flag for a whole-compilation opt-in |
| `ExperimentalType.staticMethod()` inline call | ❌ | Use the compiler flag for a whole-compilation opt-in |
| Method reference `ExperimentalType::method` | ❌ | Use the compiler flag for a whole-compilation opt-in |
| Local variable with experimental type (including `var` inference) | ❌ | Move the usage into a declaration the processor can see, or use the compiler flag |
| Cast to experimental type | ❌ | Use the compiler flag for a whole-compilation opt-in |

In practice, these gaps rarely matter: any meaningful use of an experimental SDK type almost always appears in a field declaration, method signature, or type hierarchy — all of which are caught. A purely inline expression with no declaration footprint (e.g., `session.rpc().experimental.foo().join()`) is the only case that would slip through. See [ADR-004](docs/adr/adr-004-copilotexperimental.md) for the design rationale.

### Example

```java
import com.github.copilot.CopilotExperimental;

// This type is experimental — consumer code that references it
// in declarations will fail to compile unless the opt-in flag is provided.
@CopilotExperimental
public class ExperimentalType {
    public void doSomething() {}
}

// Consumer code — compiles only with -Acopilot.experimental.allowed=true
import test.ExperimentalType;

public class Consumer {
    private ExperimentalType field;                      // ← caught: field type
    public ExperimentalType getIt() { return field; }   // ← caught: return type
    public void setIt(ExperimentalType v) { }           // ← caught: parameter type
}
```

The gate also applies to individual methods annotated with `@CopilotExperimental` on otherwise stable types. When a type-level annotation is present, all member accesses through that type are considered experimental. `@AllowCopilotExperimental` mirrors the same declaration-level boundary: annotating a class opts in that class and its enclosed declarations, while annotating a method or constructor opts in just that executable signature.

## Projects Using This SDK

| Project                                                                       | Description                                |
| ----------------------------------------------------------------------------- | ------------------------------------------ |
| [JMeter Copilot Plugin](https://github.com/brunoborges/jmeter-copilot-plugin) | JMeter plugin for AI-assisted load testing |

> Want to add your project? Open a PR!

### Development Setup

Requires JDK 25 or later and a supported [Node.js version](../nodejs/README.md#prerequisites) for development. The following steps validate the artifact built with JDK 25 runs on both 25 and 17, preserving the MR-JAR behavior.

```bash
# Clone the repository
git clone https://github.com/github/copilot-sdk.git
cd copilot-sdk/java

# Build and test with JDK 25
mvn test-compile jar:jar
mvn verify -Dskip.test.harness=true

# Set your paths for JDK 17
# Run the JDK 25 built jar with JDK 17 JVM for tests. Do not re-compile the jar.
mvn jacoco:prepare-agent@wire-up-coverage-instrumentation antrun:run@print-test-jdk-banner surefire:test failsafe:integration-test failsafe:verify jacoco:report@build-coverage-report-from-tests -Denforcer.skip=true
```

#### Formatting and linting

From the repository root, run `just format-java` to apply formatting and `just lint-java` to check formatting and Javadoc. These recipes are also included in `just format` and `just lint`.

Without `just`, run the equivalent Maven commands from `java/`:

```bash
# Apply formatting
mvn -pl sdk spotless:apply

# Check formatting and Javadoc
mvn -pl sdk spotless:check checkstyle:check
```

CI enforces both checks. Spotless runs explicitly in CI; `mvn verify` alone does not check formatting.

#### Development Setup for native embedding

Run native-runtime Maven commands from the `java` directory. Native packaging requires Node.js in addition to JDK 25 and Maven. In a standalone SDK checkout, `copilot-native/scripts/fetch-native.mjs` retrieves the pinned runtime package from the corresponding GitHub release. When the SDK is nested in `copilot-agent-runtime`, it instead stages the same-checkout artifacts from `dist-cli`; run `pnpm run build:cli` from the runtime repository first.

On a native Linux glibc host, Maven activates `native-linux-x64` or `native-linux-arm64` for the matching architecture when `copilot.native.libc=glibc` is set. On a Linux musl x64 host, Maven activates `native-linuxmusl-x64` when `copilot.native.libc=musl` is set. On Windows x64, Windows ARM64, Intel macOS, and Apple Silicon macOS, Maven activates `native-win32-x64`, `native-win32-arm64`, `native-darwin-x64`, or `native-darwin-arm64` automatically. The matching profile validates the host, runs the native script tests, stages the platform package during `generate-resources`, packages the classifier JAR during `package`, and verifies its native contents.

Before opting in, validate that Node.js reports glibc for the build host:

```bash
node copilot-native/scripts/validate-native-host.mjs linux-x64
mvn -pl copilot-native clean verify -Dcopilot.native.libc=glibc
```

The `inprocess` test profile performs the same validation and native packaging automatically, so the full in-process test command remains:

```bash
mvn -Pinprocess clean verify
```

On Windows x64 or ARM64 PowerShell, initialize Java and run the same profile:

```powershell
mvn -Pinprocess clean verify
```

The same command validates in-process mode on macOS; use the classifier for the host architecture:

```bash
node copilot-native/scripts/validate-native-host.mjs darwin-x64 # Use darwin-arm64 on Apple Silicon
mvn -Pinprocess clean verify
```

The same command validates in-process mode on Linux ARM64:

```bash
node copilot-native/scripts/validate-native-host.mjs linux-arm64
mvn -Pinprocess clean verify -Dcopilot.native.libc=glibc
```

The same command validates in-process mode on Linux musl x64:

```bash
node copilot-native/scripts/validate-native-host.mjs linuxmusl-x64
mvn -Pinprocess clean verify -Dcopilot.native.libc=musl
```

On Linux musl ARM64 and other unsupported hosts, do not set `copilot.native.libc`. A normal build produces only the OS-neutral primary, sources, and Javadoc JARs; it does not run native script tests, download or stage native files, or produce a platform classifier JAR.

To build only the OS-neutral artifacts on any host, or override the glibc opt-in, disable native download and packaging:

```bash
mvn -pl copilot-native clean package -DskipTests -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=true
```

The verified Linux x64 checks are:

```bash
node --test copilot-native/scripts/fetch-native.test.mjs copilot-native/scripts/validate-native-host.test.mjs
mvn -pl copilot-native help:active-profiles -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=false
mvn -pl copilot-native test -Dcopilot.native.libc=glibc
mvn clean verify -Dcopilot.native.libc=glibc
mvn clean package -pl copilot-native -DskipTests -Dcopilot.native.libc=glibc -Dcopilot.native.skip.download=true
```

Each classifier JAR includes `runtime.node`, `platform.properties`, and `copilot-runtime` (or `copilot-runtime.exe`) under its `native/<classifier>` directory. It does not contain the legacy `copilot` SEA. The placeholder JAR remains OS-neutral and contains no native binaries. Unsupported hosts retain the placeholder-only behavior.

### Versioning and releases

The Java SDK uses [Maven CI-friendly versions](https://maven.apache.org/maven-ci-friendly.html). Every module declares `<version>${revision}</version>`, and the single source of truth is the `<revision>` property in `java/pom.xml`. The committed value stays a `-SNAPSHOT` (for example `1.0.14-SNAPSHOT`) and is only used for local development and the daily snapshot publish.

Releasing is intentionally a **read-only** operation that never mutates the repository:

- The release version is computed by the shared release pipeline (`.github/workflows/publish.yml`) — the same version used by every other language SDK — and injected at build time with `-Drevision=X.Y.Z`. The POM is **not** edited or committed.
- `.github/workflows/java-publish-maven.yml` builds every native classifier and the primary artifact from a single immutable source commit and publishes to Maven Central. It creates no commits, no branch-protection bypass, and requires no elevated repository token.
- The `java/vX.Y.Z` traceability tag and the cross-language `vX.Y.Z` GitHub Release are created by `publish.yml` **after** publication succeeds, pointing at the original release commit.

For an independent Java publication retry, dispatch `java-publish-maven.yml` from `main` with the original `releaseVersion` and full `sourceSha`. The source must be a commit already in `main`'s history. Unmerged commits, branch names, and tag names are rejected before builds run.

Because there is no `maven-release-plugin` and no `release:prepare` ceremony, the POM deliberately does not track the "next" release version. To validate a build with an explicit version locally, without publishing:

```bash
# Build and verify with an explicit version, without touching the POM
mvn clean verify -Drevision=1.2.3

# Inspect the generated flattened POMs for the literal version (no ${revision})
cat sdk/.flattened-pom.xml copilot-native/.flattened-pom.xml
```

These commands do not upload artifacts. Do not use `deploy` for local validation: the Central publishing plugin is configured with `autoPublish=true`.

`flatten-maven-plugin` (ossrh mode) resolves `${revision}` into the installed and published POMs, so downstream consumers never see the unresolved property. Documentation version references are updated through a normal reviewed pull request (see `scripts/update-documentation-versions.sh`), not as a side effect of publishing.

## License

MIT — see [LICENSE](../LICENSE) for details.