Package com.github.copilot.sdk

Class CopilotSession

java.lang.Object
com.github.copilot.sdk.CopilotSession
All Implemented Interfaces:
AutoCloseable
public final class CopilotSession extends Object implements AutoCloseable
Represents a single conversation session with the Copilot CLI.

A session maintains conversation state, handles events, and manages tool execution. Sessions are created via CopilotClient.createSession(com.github.copilot.sdk.json.SessionConfig) or resumed via CopilotClient.resumeSession(java.lang.String, com.github.copilot.sdk.json.ResumeSessionConfig).

Example Usage


 // Create a session
 CopilotSession session = client.createSession(new SessionConfig().setModel("gpt-5")).get();

 // Register event handlers
 session.on(evt -> {
 	if (evt instanceof AssistantMessageEvent msg) {
 		System.out.println(msg.getData().getContent());
 	}
 });

 // Send messages
 session.sendAndWait(new MessageOptions().setPrompt("Hello!")).get();

 // Clean up
 session.close();
Since:
1.0.0
See Also:

  • Method Details

    • getSessionId

      public String getSessionId()
      Gets the unique identifier for this session.
      Returns:
      the session ID

    • getWorkspacePath

      public String getWorkspacePath()
      Gets the path to the session workspace directory when infinite sessions are enabled.

      The workspace directory contains checkpoints/, plan.md, and files/ subdirectories.

      Returns:
      the workspace path, or null if infinite sessions are disabled

    • send

      public CompletableFuture<String> send(String prompt)
      Sends a simple text message to the Copilot session.

      This is a convenience method equivalent to send(new MessageOptions().setPrompt(prompt)).

      Parameters:
      prompt - the message text to send
      Returns:
      a future that resolves with the message ID assigned by the server
      See Also:

    • sendAndWait

      public CompletableFuture<AssistantMessageEvent> sendAndWait(String prompt)
      Sends a simple text message and waits until the session becomes idle.

      This is a convenience method equivalent to sendAndWait(new MessageOptions().setPrompt(prompt)).

      Parameters:
      prompt - the message text to send
      Returns:
      a future that resolves with the final assistant message event, or null if no assistant message was received
      See Also:

    • send

      public CompletableFuture<String> send(MessageOptions options)
      Sends a message to the Copilot session.

      This method sends a message asynchronously and returns immediately. Use sendAndWait(MessageOptions) to wait for the response.

      Parameters:
      options - the message options containing the prompt and attachments
      Returns:
      a future that resolves with the message ID assigned by the server
      See Also:

    • sendAndWait

      public CompletableFuture<AssistantMessageEvent> sendAndWait(MessageOptions options, long timeoutMs)
      Sends a message and waits until the session becomes idle.

      This method blocks until the assistant finishes processing the message or until the timeout expires. It's suitable for simple request/response interactions where you don't need to process streaming events.

      Parameters:
      options - the message options containing the prompt and attachments
      timeoutMs - timeout in milliseconds (0 or negative for no timeout)
      Returns:
      a future that resolves with the final assistant message event, or null if no assistant message was received. The future completes exceptionally with a TimeoutException if the timeout expires.
      See Also:

    • sendAndWait

      public CompletableFuture<AssistantMessageEvent> sendAndWait(MessageOptions options)
      Sends a message and waits until the session becomes idle with default 60 second timeout.
      Parameters:
      options - the message options containing the prompt and attachments
      Returns:
      a future that resolves with the final assistant message event, or null if no assistant message was received
      See Also:

    • on

      public Closeable on(Consumer<AbstractSessionEvent> handler)
      Registers a callback for session events.

      The handler will be invoked for all events in this session, including assistant messages, tool calls, and session state changes.

      Example: 

      
 Closeable subscription = session.on(evt -> {
 	if (evt instanceof AssistantMessageEvent msg) {
 		System.out.println(msg.getData().getContent());
 	}
 });

 // Later, to unsubscribe:
 subscription.close();
      Parameters:
      handler - a callback to be invoked when a session event occurs
      Returns:
      a Closeable that, when closed, unsubscribes the handler
      See Also:

    • getMessages

      public CompletableFuture<List<AbstractSessionEvent>> getMessages()
      Gets the complete list of messages and events in the session.

      This retrieves the full conversation history, including all user messages, assistant responses, tool invocations, and other session events.

      Returns:
      a future that resolves with a list of all session events
      See Also:

    • abort

      public CompletableFuture<Void> abort()
      Aborts the currently processing message in this session.

      Use this to cancel a long-running operation or stop the assistant from continuing to generate a response.

      Returns:
      a future that completes when the abort is acknowledged

    • close

      public void close()
      Disposes the session and releases all associated resources.

      This destroys the session on the server, clears all event handlers, and releases tool and permission handlers. After calling this method, the session cannot be used again.

      Specified by:
      close in interface AutoCloseable