Copilot.Session (Copilot SDK v2.3.0)

Represents a single conversation session with the Copilot CLI.

A session maintains conversation state, handles events, and manages tool execution. Sessions are created via Copilot.Client.create_session/2 or resumed via Copilot.Client.resume_session/3.

Event subscriptions

Use on/2 (all events) or on/3 (typed events) to subscribe. The returned reference can be passed to off/2 to unsubscribe.

Example

{:ok, session} = Copilot.Client.create_session(client)
ref = Copilot.Session.on(session, fn event -> IO.inspect(event) end)
{:ok, response} = Copilot.Session.send_and_wait(session, %MessageOptions{prompt: "Hi"})
Copilot.Session.off(session, ref)
Copilot.Session.destroy(session)

Summary

Functions

abort(session)

Abort the currently processing message.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

destroy(session)

Destroy this session and release all resources.

get_messages(session)

Get all session messages/events from history.

get_metadata(session)

Get metadata for this session.

off(session, ref)

Unsubscribe an event handler by reference.

on(session, handler)

Subscribe to all session events.

on(session, event_type, handler)

Subscribe to a specific event type (e.g. "assistant.message").

register_exit_plan_mode_handler(session, handler)

Register a handler for exit plan mode requests.

send(session, options)

Send a message to the session (fire-and-forget).

send_and_wait(session, options, timeout \\ 60000)

Send a message and wait for the session to become idle.

session_id(session)

Get the session ID.

workspace_path(session)

Get the workspace path (when infinite sessions are enabled).

Functions

abort(session)

@spec abort(GenServer.server()) :: :ok | {:error, any()}

Abort the currently processing message.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

destroy(session)

@spec destroy(GenServer.server()) :: :ok

Destroy this session and release all resources.

get_messages(session)

@spec get_messages(GenServer.server()) :: {:ok, [map()]} | {:error, any()}

Get all session messages/events from history.

get_metadata(session)

@spec get_metadata(GenServer.server()) :: {:ok, map()} | {:error, any()}

Get metadata for this session.

off(session, ref)

@spec off(GenServer.server(), reference()) :: :ok

Unsubscribe an event handler by reference.

on(session, handler)

@spec on(GenServer.server(), (map() -> any())) :: reference()

Subscribe to all session events.

Returns a reference for unsubscribing with off/2.

on(session, event_type, handler)

@spec on(GenServer.server(), String.t(), (map() -> any())) :: reference()

Subscribe to a specific event type (e.g. "assistant.message").

Returns a reference for unsubscribing with off/2.

register_exit_plan_mode_handler(session, handler)

@spec register_exit_plan_mode_handler(GenServer.server(), (... -> any())) :: :ok

Register a handler for exit plan mode requests.

send(session, options)

@spec send(GenServer.server(), Copilot.Types.MessageOptions.t()) ::
  {:ok, String.t()} | {:error, any()}

Send a message to the session (fire-and-forget).

Returns {:ok, message_id} on success.

send_and_wait(session, options, timeout \\ 60000)

@spec send_and_wait(GenServer.server(), Copilot.Types.MessageOptions.t(), timeout()) ::
  {:ok, map() | nil} | {:error, any()}

Send a message and wait for the session to become idle.

Returns {:ok, assistant_message_event | nil} when done, or {:error, reason} on timeout/error.

session_id(session)

@spec session_id(GenServer.server()) :: String.t()

Get the session ID.

workspace_path(session)

@spec workspace_path(GenServer.server()) :: String.t() | nil

Get the workspace path (when infinite sessions are enabled).