toolHandlers = new ConcurrentHashMap<>();
@@ -94,8 +95,26 @@ public final class CopilotSession implements AutoCloseable {
* the JSON-RPC client for communication
*/
CopilotSession(String sessionId, JsonRpcClient rpc) {
+ this(sessionId, rpc, null);
+ }
+
+ /**
+ * Creates a new session with the given ID, RPC client, and workspace path.
+ *
+ * This constructor is package-private. Sessions should be created via
+ * {@link CopilotClient#createSession} or {@link CopilotClient#resumeSession}.
+ *
+ * @param sessionId
+ * the unique session identifier
+ * @param rpc
+ * the JSON-RPC client for communication
+ * @param workspacePath
+ * the workspace path if infinite sessions are enabled
+ */
+ CopilotSession(String sessionId, JsonRpcClient rpc, String workspacePath) {
this.sessionId = sessionId;
this.rpc = rpc;
+ this.workspacePath = workspacePath;
}
/**
@@ -107,6 +126,19 @@ public String getSessionId() {
return sessionId;
}
+ /**
+ * Gets the path to the session workspace directory when infinite sessions are
+ * enabled.
+ *
+ * The workspace directory contains checkpoints/, plan.md, and files/
+ * subdirectories.
+ *
+ * @return the workspace path, or {@code null} if infinite sessions are disabled
+ */
+ public String getWorkspacePath() {
+ return workspacePath;
+ }
+
/**
* Sends a simple text message to the Copilot session.
*
diff --git a/src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java b/src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java
index c725a2348..32ab67f6b 100644
--- a/src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java
+++ b/src/main/java/com/github/copilot/sdk/json/CreateSessionRequest.java
@@ -56,6 +56,9 @@ public final class CreateSessionRequest {
@JsonProperty("customAgents")
private List customAgents;
+ @JsonProperty("infiniteSessions")
+ private InfiniteSessionConfig infiniteSessions;
+
/** Gets the model name. @return the model */
public String getModel() {
return model;
@@ -165,4 +168,14 @@ public List getCustomAgents() {
public void setCustomAgents(List customAgents) {
this.customAgents = customAgents;
}
+
+ /** Gets infinite sessions config. @return the config */
+ public InfiniteSessionConfig getInfiniteSessions() {
+ return infiniteSessions;
+ }
+
+ /** Sets infinite sessions config. @param infiniteSessions the config */
+ public void setInfiniteSessions(InfiniteSessionConfig infiniteSessions) {
+ this.infiniteSessions = infiniteSessions;
+ }
}
diff --git a/src/main/java/com/github/copilot/sdk/json/CreateSessionResponse.java b/src/main/java/com/github/copilot/sdk/json/CreateSessionResponse.java
index 930417872..644114d8a 100644
--- a/src/main/java/com/github/copilot/sdk/json/CreateSessionResponse.java
+++ b/src/main/java/com/github/copilot/sdk/json/CreateSessionResponse.java
@@ -8,10 +8,25 @@ public final class CreateSessionResponse {
@JsonProperty("sessionId")
private String sessionId;
+ @JsonProperty("workspacePath")
+ private String workspacePath;
+
public String getSessionId() {
return sessionId;
}
public void setSessionId(String sessionId) {
this.sessionId = sessionId;
}
+
+ /**
+ * Gets the workspace path when infinite sessions are enabled.
+ *
+ * @return the workspace path, or {@code null} if infinite sessions are disabled
+ */
+ public String getWorkspacePath() {
+ return workspacePath;
+ }
+ public void setWorkspacePath(String workspacePath) {
+ this.workspacePath = workspacePath;
+ }
}
diff --git a/src/main/java/com/github/copilot/sdk/json/InfiniteSessionConfig.java b/src/main/java/com/github/copilot/sdk/json/InfiniteSessionConfig.java
new file mode 100644
index 000000000..f0b2ca8f7
--- /dev/null
+++ b/src/main/java/com/github/copilot/sdk/json/InfiniteSessionConfig.java
@@ -0,0 +1,113 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.sdk.json;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Configuration for infinite sessions with automatic context compaction and
+ * workspace persistence.
+ *
+ * When enabled, sessions automatically manage context window limits through
+ * background compaction and persist state to a workspace directory.
+ *
+ *
Example Usage
+ *
+ * {@code
+ * var infiniteConfig = new InfiniteSessionConfig().setEnabled(true).setBackgroundCompactionThreshold(0.80)
+ * .setBufferExhaustionThreshold(0.95);
+ *
+ * var config = new SessionConfig().setInfiniteSessions(infiniteConfig);
+ *
+ * var session = client.createSession(config).get();
+ * }
+ *
+ * @see SessionConfig#setInfiniteSessions(InfiniteSessionConfig)
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class InfiniteSessionConfig {
+
+ @JsonProperty("enabled")
+ private Boolean enabled;
+
+ @JsonProperty("backgroundCompactionThreshold")
+ private Double backgroundCompactionThreshold;
+
+ @JsonProperty("bufferExhaustionThreshold")
+ private Double bufferExhaustionThreshold;
+
+ /**
+ * Gets whether infinite sessions are enabled.
+ *
+ * @return {@code true} if enabled, {@code null} to use default (true)
+ */
+ public Boolean getEnabled() {
+ return enabled;
+ }
+
+ /**
+ * Sets whether infinite sessions are enabled.
+ *
+ * Default: true
+ *
+ * @param enabled
+ * {@code true} to enable infinite sessions
+ * @return this config instance for method chaining
+ */
+ public InfiniteSessionConfig setEnabled(Boolean enabled) {
+ this.enabled = enabled;
+ return this;
+ }
+
+ /**
+ * Gets the background compaction threshold.
+ *
+ * @return the threshold (0.0-1.0), or {@code null} to use default
+ */
+ public Double getBackgroundCompactionThreshold() {
+ return backgroundCompactionThreshold;
+ }
+
+ /**
+ * Sets the context utilization threshold at which background compaction starts.
+ *
+ * Compaction runs asynchronously, allowing the session to continue processing.
+ * Default: 0.80
+ *
+ * @param backgroundCompactionThreshold
+ * the threshold (0.0-1.0)
+ * @return this config instance for method chaining
+ */
+ public InfiniteSessionConfig setBackgroundCompactionThreshold(Double backgroundCompactionThreshold) {
+ this.backgroundCompactionThreshold = backgroundCompactionThreshold;
+ return this;
+ }
+
+ /**
+ * Gets the buffer exhaustion threshold.
+ *
+ * @return the threshold (0.0-1.0), or {@code null} to use default
+ */
+ public Double getBufferExhaustionThreshold() {
+ return bufferExhaustionThreshold;
+ }
+
+ /**
+ * Sets the context utilization threshold at which the session blocks until
+ * compaction completes.
+ *
+ * This prevents context overflow when compaction hasn't finished in time.
+ * Default: 0.95
+ *
+ * @param bufferExhaustionThreshold
+ * the threshold (0.0-1.0)
+ * @return this config instance for method chaining
+ */
+ public InfiniteSessionConfig setBufferExhaustionThreshold(Double bufferExhaustionThreshold) {
+ this.bufferExhaustionThreshold = bufferExhaustionThreshold;
+ return this;
+ }
+}
diff --git a/src/main/java/com/github/copilot/sdk/json/ResumeSessionResponse.java b/src/main/java/com/github/copilot/sdk/json/ResumeSessionResponse.java
index 615bf462c..dd9e8b050 100644
--- a/src/main/java/com/github/copilot/sdk/json/ResumeSessionResponse.java
+++ b/src/main/java/com/github/copilot/sdk/json/ResumeSessionResponse.java
@@ -8,10 +8,25 @@ public final class ResumeSessionResponse {
@JsonProperty("sessionId")
private String sessionId;
+ @JsonProperty("workspacePath")
+ private String workspacePath;
+
public String getSessionId() {
return sessionId;
}
public void setSessionId(String sessionId) {
this.sessionId = sessionId;
}
+
+ /**
+ * Gets the workspace path when infinite sessions are enabled.
+ *
+ * @return the workspace path, or {@code null} if infinite sessions are disabled
+ */
+ public String getWorkspacePath() {
+ return workspacePath;
+ }
+ public void setWorkspacePath(String workspacePath) {
+ this.workspacePath = workspacePath;
+ }
}
diff --git a/src/main/java/com/github/copilot/sdk/json/SessionConfig.java b/src/main/java/com/github/copilot/sdk/json/SessionConfig.java
index b1ea7df75..341ddb2f7 100644
--- a/src/main/java/com/github/copilot/sdk/json/SessionConfig.java
+++ b/src/main/java/com/github/copilot/sdk/json/SessionConfig.java
@@ -41,6 +41,7 @@ public class SessionConfig {
private boolean streaming;
private Map mcpServers;
private List customAgents;
+ private InfiniteSessionConfig infiniteSessions;
/**
* Gets the custom session ID.
@@ -309,4 +310,31 @@ public SessionConfig setCustomAgents(List customAgents) {
this.customAgents = customAgents;
return this;
}
+
+ /**
+ * Gets the infinite sessions configuration.
+ *
+ * @return the infinite sessions config
+ */
+ public InfiniteSessionConfig getInfiniteSessions() {
+ return infiniteSessions;
+ }
+
+ /**
+ * Sets the infinite session configuration for persistent workspaces and
+ * automatic compaction.
+ *
+ * When enabled (default), sessions automatically manage context limits and
+ * persist state to a workspace directory. The workspace contains checkpoints/,
+ * plan.md, and files/ subdirectories.
+ *
+ * @param infiniteSessions
+ * the infinite sessions configuration
+ * @return this config instance for method chaining
+ * @see InfiniteSessionConfig
+ */
+ public SessionConfig setInfiniteSessions(InfiniteSessionConfig infiniteSessions) {
+ this.infiniteSessions = infiniteSessions;
+ return this;
+ }
}
diff --git a/src/site/markdown/.gitignore b/src/site/markdown/.gitignore
new file mode 100644
index 000000000..0982931ec
--- /dev/null
+++ b/src/site/markdown/.gitignore
@@ -0,0 +1,2 @@
+# Copied from root during pre-site phase - do not edit here
+index.md
diff --git a/DOCS.md b/src/site/markdown/documentation.md
similarity index 62%
rename from DOCS.md
rename to src/site/markdown/documentation.md
index c8673a10a..9c8cb119d 100644
--- a/DOCS.md
+++ b/src/site/markdown/documentation.md
@@ -4,20 +4,22 @@ This document provides detailed API reference and usage examples for the Copilot
## Table of Contents
-- [API Reference](#api-reference)
- - [CopilotClient](#copilotclient)
- - [CopilotSession](#copilotsession)
-- [Event Types](#event-types)
-- [Streaming](#streaming)
-- [Advanced Usage](#advanced-usage)
- - [Manual Server Control](#manual-server-control)
- - [Tools](#tools)
- - [System Message Customization](#system-message-customization)
- - [Multiple Sessions](#multiple-sessions)
- - [File Attachments](#file-attachments)
- - [Bring Your Own Key (BYOK)](#bring-your-own-key-byok)
- - [Permission Handling](#permission-handling)
-- [Error Handling](#error-handling)
+- [API Reference](#API_Reference)
+ - [CopilotClient](#CopilotClient)
+ - [CopilotSession](#CopilotSession)
+- [Event Types](#Event_Types)
+- [Streaming](#Streaming)
+- [Listing Models](#Listing_Models)
+- [Advanced Usage](#Advanced_Usage)
+ - [Manual Server Control](#Manual_Server_Control)
+ - [Tools](#Tools)
+ - [System Message Customization](#System_Message_Customization)
+ - [Multiple Sessions](#Multiple_Sessions)
+ - [File Attachments](#File_Attachments)
+ - [Bring Your Own Key (BYOK)](#Bring_Your_Own_Key_.28BYOK.29)
+ - [Permission Handling](#Permission_Handling)
+ - [Infinite Sessions](#Infinite_Sessions)
+- [Error Handling](#Error_Handling)
## API Reference
@@ -83,6 +85,18 @@ Resume an existing session.
Ping the server to check connectivity.
+##### `getStatus(): CompletableFuture`
+
+Get CLI status including version and protocol information.
+
+##### `getAuthStatus(): CompletableFuture`
+
+Get current authentication status.
+
+##### `listModels(): CompletableFuture>`
+
+List available models with their metadata (id, name, capabilities, billing info).
+
##### `getState(): ConnectionState`
Get current connection state. Returns one of: `DISCONNECTED`, `CONNECTING`, `CONNECTED`, `ERROR`.
@@ -111,6 +125,10 @@ Represents a single conversation session.
#### Methods
+##### `send(String prompt): CompletableFuture`
+
+Convenience method to send a simple text message. Equivalent to `send(new MessageOptions().setPrompt(prompt))`.
+
##### `send(MessageOptions options): CompletableFuture`
Send a message to the session.
@@ -123,10 +141,18 @@ Send a message to the session.
Returns the message ID.
-##### `sendAndWait(MessageOptions options, long timeoutMs): CompletableFuture`
+##### `sendAndWait(String prompt): CompletableFuture`
+
+Convenience method to send a simple text message and wait for the session to become idle. Equivalent to `sendAndWait(new MessageOptions().setPrompt(prompt))`.
+
+##### `sendAndWait(MessageOptions options): CompletableFuture`
Send a message and wait for the session to become idle. Default timeout is 60 seconds.
+##### `sendAndWait(MessageOptions options, long timeoutMs): CompletableFuture`
+
+Send a message and wait for the session to become idle with custom timeout.
+
##### `on(Consumer handler): Closeable`
Subscribe to session events. Returns a `Closeable` to unsubscribe.
@@ -211,6 +237,45 @@ session.send(new MessageOptions().setPrompt("Tell me a short story")).get();
done.get();
```
+## Listing Models
+
+Query available models and their capabilities before creating a session:
+
+```java
+try (var client = new CopilotClient()) {
+ client.start().get();
+
+ // List all available models
+ List models = client.listModels().get();
+
+ for (ModelInfo model : models) {
+ System.out.println("Model: " + model.getId());
+ System.out.println(" Name: " + model.getName());
+
+ if (model.getCapabilities() != null) {
+ System.out.println(" Max Output Tokens: " + model.getCapabilities().getMaxOutputTokens());
+ }
+
+ if (model.getPolicy() != null) {
+ System.out.println(" State: " + model.getPolicy().getState());
+ }
+ }
+
+ // Use a specific model from the list
+ var session = client.createSession(
+ new SessionConfig().setModel(models.get(0).getId())
+ ).get();
+}
+```
+
+Each `ModelInfo` contains:
+
+- `id` - Model identifier (e.g., "claude-sonnet-4.5", "gpt-4o")
+- `name` - Human-readable display name
+- `capabilities` - Model limits including max output tokens
+- `policy` - Policy state information
+- `billing` - Billing/usage information
+
## Advanced Usage
### Manual Server Control
@@ -349,6 +414,78 @@ var session = client.createSession(
).get();
```
+### Infinite Sessions
+
+Infinite sessions enable automatic context management for long-running conversations. When enabled (default), the session automatically manages context window limits through background compaction and persists state to a workspace directory.
+
+#### How It Works
+
+As conversations grow, they eventually approach the model's context window limit. Infinite sessions solve this by:
+
+1. **Background Compaction**: When context utilization reaches the background threshold (default 80%), the session starts compacting older messages asynchronously while continuing to process new messages.
+
+2. **Buffer Exhaustion Protection**: If context reaches the exhaustion threshold (default 95%) before compaction completes, the session blocks until compaction finishes to prevent overflow.
+
+3. **Workspace Persistence**: Session state is persisted to a workspace directory containing:
+ - `checkpoints/` - Session checkpoints for resumption
+ - `plan.md` - Current conversation plan
+ - `files/` - Associated files
+
+#### Configuration
+
+```java
+var infiniteConfig = new InfiniteSessionConfig()
+ .setEnabled(true)
+ .setBackgroundCompactionThreshold(0.80) // Start compacting at 80% utilization
+ .setBufferExhaustionThreshold(0.95); // Block at 95% until compaction completes
+
+var session = client.createSession(
+ new SessionConfig()
+ .setModel("gpt-5")
+ .setInfiniteSessions(infiniteConfig)
+).get();
+```
+
+#### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Whether infinite sessions are enabled |
+| `backgroundCompactionThreshold` | `0.80` | Context utilization (0.0-1.0) at which background compaction starts |
+| `bufferExhaustionThreshold` | `0.95` | Context utilization (0.0-1.0) at which the session blocks until compaction completes |
+
+#### Accessing the Workspace
+
+When infinite sessions are enabled, you can access the workspace path:
+
+```java
+var session = client.createSession(
+ new SessionConfig()
+ .setModel("gpt-5")
+ .setInfiniteSessions(new InfiniteSessionConfig().setEnabled(true))
+).get();
+
+String workspacePath = session.getWorkspacePath();
+if (workspacePath != null) {
+ System.out.println("Session workspace: " + workspacePath);
+ // Access checkpoints/, plan.md, files/ subdirectories
+}
+```
+
+#### Disabling Infinite Sessions
+
+For short conversations where context management isn't needed:
+
+```java
+var session = client.createSession(
+ new SessionConfig()
+ .setModel("gpt-5")
+ .setInfiniteSessions(new InfiniteSessionConfig().setEnabled(false))
+).get();
+
+// session.getWorkspacePath() will return null
+```
+
## Error Handling
```java
diff --git a/src/site/resources/.gitignore b/src/site/resources/.gitignore
new file mode 100644
index 000000000..4ccc5817f
--- /dev/null
+++ b/src/site/resources/.gitignore
@@ -0,0 +1,2 @@
+# Copied from root during pre-site phase - do not edit here
+image.png
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 000000000..3fcc921fd
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,62 @@
+
+
+
+
+
+ org.apache.maven.skins
+ maven-fluido-skin
+ 2.0.0-M11
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+
+
+
+
+