Struct Session 

pub struct Session { /* private fields */ }

A Copilot conversation session.

Sessions maintain conversation state, handle events, and manage tool execution.

Example

use copilot_sdk::{Client, SessionConfig, SessionEventData};

#[tokio::main]
async fn main() -> copilot_sdk::Result<()> {
let client = Client::builder().build()?;
client.start().await?;
let session = client.create_session(SessionConfig::default()).await?;

// Subscribe to events
let mut events = session.subscribe();

// Send a message
session.send("Hello!").await?;

// Process events
while let Ok(event) = events.recv().await {
    match &event.data {
        SessionEventData::AssistantMessage(msg) => println!("{}", msg.content),
        SessionEventData::SessionIdle(_) => break,
        _ => {}
    }
}
client.stop().await;

Implementations

impl Session

pub fn new<F>( session_id: String, workspace_path: Option<String>, invoke_fn: F, ) -> Self

where F: Fn(&str, Option<Value>) -> InvokeFuture + Send + Sync + 'static,

Create a new session.

This is typically called by the Client when creating a session.

pub fn session_id(&self) -> &str

Get the session ID.

pub fn workspace_path(&self) -> Option<&str>

Get the workspace path for infinite sessions.

Contains checkpoints/, plan.md, and files/ subdirectories. Returns None if infinite sessions are disabled.

pub fn subscribe(&self) -> EventSubscription

Subscribe to session events.

Returns a receiver that will receive all session events.

pub async fn on<F>(&self, handler: F) -> impl FnOnce()

where F: Fn(&SessionEvent) + Send + Sync + 'static,

Register a callback-based event handler.

Returns an unsubscribe closure. Call it to remove the handler. Alternatively, use [off] with the internal handler ID.

pub async fn off(&self, handler_id: u64)

Unsubscribe a callback-based event handler.

pub async fn dispatch_event(&self, event: SessionEvent)

Dispatch an event to all subscribers.

This is called by the Client when events are received.

pub async fn send(&self, options: impl Into<MessageOptions>) -> Result<String>

Send a message to the session.

Returns the message ID.

pub async fn abort(&self) -> Result<()>

Abort the current message processing.

pub async fn get_messages(&self) -> Result<Vec<SessionEvent>>

Get all messages in the session.

pub async fn register_tool(&self, tool: Tool)

Register a tool with this session.

pub async fn register_tool_with_handler( &self, tool: Tool, handler: Option<ToolHandler>, )

Register a tool with a handler.

pub async fn register_tools(&self, tools: Vec<Tool>)

Register multiple tools.

pub async fn get_tool(&self, name: &str) -> Option<Tool>

Get a registered tool by name.

pub async fn get_tools(&self) -> Vec<Tool>

Get all registered tools.

pub async fn invoke_tool( &self, name: &str, arguments: &Value, ) -> Result<ToolResultObject>

Invoke a tool handler.

pub async fn register_permission_handler<F>(&self, handler: F)

where F: Fn(&PermissionRequest) -> PermissionRequestResult + Send + Sync + 'static,

Register a permission handler.

pub async fn handle_permission_request( &self, request: &PermissionRequest, ) -> PermissionRequestResult

Handle a permission request.

Delegates to the registered permission handler, or denies by default if no handler is set.

pub async fn register_user_input_handler<F>(&self, handler: F)

where F: Fn(&UserInputRequest, &UserInputInvocation) -> UserInputResponse + Send + Sync + 'static,

Register a handler for user input requests from the server.

pub async fn handle_user_input_request( &self, request: &UserInputRequest, ) -> Result<UserInputResponse>

Handle a user input request from the server.

pub async fn has_user_input_handler(&self) -> bool

Check if a user input handler is registered.

pub async fn register_hooks(&self, hooks: SessionHooks)

Register session hooks.

pub async fn has_hooks(&self) -> bool

Check if any hooks are registered.

pub async fn handle_hooks_invoke( &self, hook_type: &str, input: &Value, ) -> Result<Value>

Handle a hooks.invoke callback from the server.

Dispatches to the appropriate hook handler based on hook_type and returns the serialized output JSON.

pub async fn destroy(&self) -> Result<()>

Destroy the session.

impl Session

pub async fn wait_for_idle( &self, timeout: Option<Duration>, ) -> Result<Option<SessionEvent>>

Wait for the session to become idle.

Returns the last assistant message event, or None if no message was received. Uses the specified timeout, or 60 seconds if None.

pub async fn send_and_wait( &self, options: impl Into<MessageOptions>, timeout: Option<Duration>, ) -> Result<Option<SessionEvent>>

Send a message and wait for the complete response.

Returns the last AssistantMessage event, or None if session became idle without producing an assistant message. Uses the specified timeout, or 60 seconds if None.

pub async fn send_and_collect( &self, options: impl Into<MessageOptions>, timeout: Option<Duration>, ) -> Result<String>

Send a message and wait for the response content as a string.

Convenience method that collects all assistant message/delta content. Uses the specified timeout, or 60 seconds if None.