@spec abort(pid()) :: :ok | {:error, term()}

Abort the current active query. Alias for interrupt/1.

@spec account_info(pid()) :: {:ok, map()} | {:error, term()}

Get account information.

@spec active_betas(pid()) :: {:ok, list()} | {:error, term()}

List active beta features from the system init data.

@spec api_key_source(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the API key source from the system init data.

@spec block_to_message(content_block()) :: flat_message()

Convert a single content_block into a flat message.

@spec child_spec(keyword() | map()) :: Supervisor.child_spec()

Supervisor child specification for a copilot_session process.

Accepts keyword list or map. Uses :session_id from opts as child id when available.

Examples

children = [
  {CopilotEx, cli_path: "copilot", work_dir: "/my/project"}
]
Supervisor.start_link(children, strategy: :one_for_one)

@spec cli_version(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the CLI version from the system init data.

@spec command_run(pid(), binary(), map()) ::
  {:error,
   {:port_exit, term()} | {:port_failed, term()} | {:timeout, timeout()}}
  | {:ok, %{exit_code: integer(), output: binary()}}

Run a command via universal command execution.

@spec current_model(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the current model from session info.

Extracts from the session's model field or system init data.

@spec current_permission_mode(pid()) ::
  {:ok, atom() | binary() | nil} | {:error, term()}

Get the current permission mode from session info.

@spec delete_server_session(pid(), binary()) :: {:ok, term()} | {:error, term()}

Delete a native Copilot session by id.

@spec delete_session(binary()) :: :ok

Delete a session and its messages.

@spec extract_todos([message()]) :: [todo_item()]

Extract all TodoWrite items from a list of messages.

@spec filter_todos([todo_item()], BeamAgent.Todo.todo_status()) :: [todo_item()]

Filter todo items by status.

@spec flatten_assistant(map()) :: [map()]

Flatten an assistant message (with content_blocks) into individual messages.

@spec fork_session(pid(), map()) :: {:error, :not_found} | {:ok, session_info()}

Fork a tracked session into a new session ID.

@spec get_auth_status(pid()) :: {:ok, term()} | {:error, term()}

Get native Copilot authentication status.

@spec get_last_session_id(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the last native Copilot session id.

@spec get_server_session(pid(), binary()) :: {:ok, map()} | {:error, term()}

Get native Copilot session metadata by id.

@spec get_session(binary()) :: {:error, :not_found} | {:ok, session_info()}

Get session metadata by ID.

@spec get_session_messages(binary()) :: {:error, :not_found} | {:ok, [message()]}

Get messages for a session.

@spec get_session_messages(binary(), message_filter_opts()) ::
  {:error, :not_found} | {:ok, [message()]}

Get messages with options.

@spec get_status(pid()) :: {:ok, term()} | {:error, term()}

Get native Copilot CLI status information.

@spec health(pid()) :: :connecting | :initializing | :ready | :active_query | :error

Get the current health/state of a session.

Examples

:ready = CopilotEx.health(session)

@spec interrupt(pid()) :: :ok | {:error, term()}

Interrupt/abort the current active query.

Examples

:ok = CopilotEx.interrupt(session)

@spec list_agents(pid()) :: {:ok, list()} | {:error, term()}

List available agents from the system init data.

@spec list_mcp_servers(pid()) :: {:ok, list()} | {:error, term()}

List configured MCP servers from the system init data.

@spec list_plugins(pid()) :: {:ok, list()} | {:error, term()}

List available plugins from the system init data.

@spec list_server_sessions(pid()) :: {:ok, [map()]} | {:error, term()}

List native Copilot sessions.

@spec list_sessions() :: {:ok, [session_info()]}

List all tracked sessions.

@spec list_sessions(session_list_opts()) :: {:ok, [session_info()]}

List sessions with filters.

@spec list_skills(pid()) :: {:ok, list()} | {:error, term()}

List available skills from the system init data.

@spec list_tools(pid()) :: {:ok, list()} | {:error, term()}

List available tools from the system init data.

@spec mcp_server(
  binary(),
  [
    %{
      description: binary(),
      handler: (map() -> {term(), term()}),
      input_schema: map(),
      name: binary()
    }
  ]
) :: mcp_server_def()

Create an in-process MCP server definition.

@spec mcp_server_status(pid()) :: {:ok, %{required(binary()) => map()}}

Get status of all MCP servers.

@spec mcp_tool(binary(), binary(), map(), (map() ->
                                       {:error, binary()} | {:ok, [map()]})) ::
  mcp_tool_def()

Create an in-process MCP tool definition.

@spec message_to_block(map()) :: content_block()

Convert a single flat message into a content_block.

@spec messages_to_blocks([map()]) :: [content_block()]

Convert a list of flat messages into content_block format.

@spec model_list(pid()) :: {:ok, term()} | {:error, term()}

List native Copilot models with metadata.

@spec normalize_messages([map()]) :: [map()]

Normalize a list of messages from any adapter into a uniform flat stream.

Claude produces assistant messages with nested content_blocks. All other adapters (including Copilot) produce individual typed messages. This function flattens both into a uniform stream where each message has a single, specific type — never nested content_blocks.

Examples

CopilotEx.normalize_messages(messages)
|> Enum.filter(& &1.type == :text)
|> Enum.map(& &1.content)
|> Enum.join("")

@spec output_style(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the output style from the system init data.

@spec query(pid(), binary(), query_opts()) :: {:error, term()} | {:ok, [message()]}

Send a query and collect all response messages (blocking).

Returns {:ok, messages} once the query completes (session.idle). Uses deadline-based timeout.

Options

• :timeout - total query timeout in ms (default: 120_000)

Examples

{:ok, messages} = CopilotEx.query(session, "Hello!")
last = List.last(messages)
IO.puts(last.content)

@spec reconnect_mcp_server(pid(), binary()) ::
  {:ok, %{required(<<_::48>>) => <<_::88>>}} | {:error, :not_found}

Reconnect a failed MCP server.

@spec resume_session(binary()) :: {:ok, pid()} | {:error, term()}

Resume a native Copilot session by id.

@spec revert_session(pid(), map()) ::
  {:error, :invalid_selector | :not_found} | {:ok, session_info()}

Revert the visible session history to a prior boundary.

@spec rewind_files(pid(), binary()) ::
  :ok | {:error, :not_found | {:restore_failed, binary(), atom()}}

Revert file changes to a checkpoint via universal checkpointing.

@spec sdk_hook(atom(), (hook_context() -> :ok | {:deny, binary()})) :: %{
  callback: (hook_context() -> :ok | {:deny, binary()}),
  event: atom()
}

Create an SDK lifecycle hook.

Hooks fire at the shared BeamAgent.Hooks lifecycle points, including blocking events like :pre_tool_use, :user_prompt_submit, and :permission_request, plus notification events such as :post_tool_use, :post_tool_use_failure, :session_start, :session_end, :subagent_start, :subagent_stop, :pre_compact, :notification, :config_change, :task_completed, and :teammate_idle.

Examples

hook = CopilotEx.sdk_hook(:pre_tool_use, fn ctx ->
  case ctx.tool_name do
    "Bash" -> {:deny, "No shell access"}
    _ -> :ok
  end
end)
{:ok, session} = CopilotEx.start_session(sdk_hooks: [hook])

@spec sdk_hook(
  atom(),
  (hook_context() -> :ok | {:deny, binary()}),
  %{tool_name: binary()}
) :: %{
  callback: (hook_context() -> :ok | {:deny, binary()}),
  event: atom(),
  matcher: %{tool_name: binary()},
  compiled_re: {:re_pattern, term(), term(), term(), term()}
}

Create an SDK lifecycle hook with a matcher filter.

Examples

hook = CopilotEx.sdk_hook(:pre_tool_use,
  fn _ctx -> {:deny, "blocked"} end,
  %{tool_name: "Bash"})

@spec send_command(pid(), binary(), map()) :: {:ok, term()} | {:error, term()}

Send an arbitrary JSON-RPC command to the Copilot CLI.

Examples

{:ok, result} = CopilotEx.send_command(session, "config.get", %{})

@spec send_control(pid(), binary(), map()) :: {:ok, term()} | {:error, term()}

Send a raw control message. Delegates to native Copilot implementation.

@spec server_health(pid()) ::
  {:ok,
   %{
     adapter: :copilot,
     health: :active_query | :connecting | :error | :initializing | :ready
   }}

Check server health. Maps to session health for Copilot.

@spec session_destroy(pid()) :: {:ok, term()} | {:error, term()}

Destroy the current native Copilot session.

@spec session_get_messages(pid()) :: {:ok, term()} | {:error, term()}

Fetch native Copilot events/messages for the current session.

@spec session_info(pid()) :: {:ok, map()} | {:error, term()}

Query session info (adapter, session_id, model, etc.).

Examples

{:ok, info} = CopilotEx.session_info(session)
info.copilot_session_id

@spec set_max_thinking_tokens(pid(), pos_integer()) ::
  {:ok, %{max_thinking_tokens: pos_integer()}}

Set maximum thinking tokens via universal control.

@spec set_mcp_servers(pid(), [%{name: binary(), tools: [map()], version: binary()}]) ::
  {:error, :not_found} | {:ok, %{required(binary()) => binary()}}

Replace MCP server configurations.

@spec set_model(pid(), binary()) :: {:ok, binary()} | {:error, term()}

Change the model at runtime during a session.

Examples

{:ok, _} = CopilotEx.set_model(session, "gpt-4o")

@spec set_permission_mode(pid(), binary()) :: {:ok, binary()} | {:error, term()}

Change the permission mode at runtime via universal control.

@spec share_session(pid()) :: {:error, :not_found} | {:ok, share_info()}

Create or replace share state for the current session.

@spec start_session(keyword() | map()) :: {:ok, pid()} | {:error, term()}

Start a new Copilot CLI session.

Returns {:ok, pid} on success. The session process speaks full bidirectional JSON-RPC 2.0 over Content-Length framed stdio.

Examples

{:ok, session} = CopilotEx.start_session(cli_path: "copilot")
{:ok, session} = CopilotEx.start_session(
  cli_path: "copilot",
  model: "gpt-4o",
  permission_mode: "acceptEdits"
)

@spec stop(pid()) :: :ok

Gracefully stop a session, closing the CLI subprocess.

@spec stop_task(pid(), binary()) :: :ok | {:error, :not_found}

Stop a running agent task via universal task tracking.

@spec stream(pid(), binary(), map()) :: Enumerable.t()

Returns a Stream that yields {:ok, msg} or {:error, reason} tuples.

Non-raising variant of stream!/3.

@spec stream!(pid(), binary(), map()) :: Enumerable.t()

Returns a Stream that yields messages as they arrive.

Raises on errors. Uses Stream.resource/3 under the hood with demand-driven backpressure — the gen_statem only delivers the next message when the stream consumer requests it.

The query is dispatched to the CLI immediately when stream!/3 is called (not lazily on first consumption). Message consumption is lazy/pull-based.

The stream halts automatically when a :result or terminal :error message is received. Note: Copilot can emit non-terminal :error messages (warnings), so the halt condition checks is_error: true — unlike other adapters where all :error messages are terminal.

Examples

CopilotEx.stream!(session, "Explain GenServer")
|> Stream.filter(& &1.type == :text)
|> Enum.map(& &1.content)
|> Enum.join("")

# With options
CopilotEx.stream!(session, "Hello", %{timeout: 60_000})
|> Enum.to_list()

@spec submit_feedback(pid(), map()) :: :ok

Submit feedback via universal feedback tracking.

@spec summarize_session(pid()) :: {:error, :not_found} | {:ok, summary_info()}

Generate and store a summary for the current session.

@spec supported_agents(pid()) :: {:ok, list()} | {:error, term()}

List available agents.

@spec supported_commands(pid()) :: {:ok, list()} | {:error, term()}

List available slash commands.

@spec supported_models(pid()) :: {:ok, list()} | {:error, term()}

List available models.

@spec thread_archive(pid(), binary()) :: {:error, :not_found} | {:ok, thread_info()}

Archive a thread.

@spec thread_fork(pid(), binary()) :: {:error, :not_found} | {:ok, thread_info()}

Fork an existing thread.

@spec thread_list(pid()) :: {:ok, [thread_info()]}

List all threads for this session.

@spec thread_read(pid(), binary()) ::
  {:error, :not_found} | {:ok, thread_read_result()}

Read thread metadata, optionally including visible messages.

@spec thread_resume(pid(), binary()) :: {:error, :not_found} | {:ok, thread_info()}

Resume an existing thread.

@spec thread_rollback(pid(), binary(), map()) ::
  {:error, :invalid_selector | :not_found} | {:ok, thread_info()}

Rollback the visible thread history.

@spec thread_start(pid(), thread_start_opts()) :: {:ok, thread_start_result()}

Start a new conversation thread.

@spec thread_unarchive(pid(), binary()) :: {:error, :not_found} | {:ok, thread_info()}

Unarchive a thread.

@spec todo_summary([todo_item()]) :: %{
  :total => non_neg_integer(),
  required(atom()) => non_neg_integer()
}

Get a summary of todo counts by status.

@spec toggle_mcp_server(pid(), binary(), boolean()) ::
  {:ok, %{required(<<_::48>>) => <<_::56>>}} | {:error, :not_found}

Enable or disable an MCP server.

@spec turn_respond(pid(), binary(), map()) ::
  :ok | {:error, :not_found | :already_resolved}

Respond to an agent request via universal turn response.

@spec unrevert_session(pid()) :: {:error, :not_found} | {:ok, session_info()}

Clear any stored session revert state.

@spec unshare_session(pid()) :: :ok | {:error, :not_found}

Revoke share state for the current session.

@spec working_directory(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the working directory from the system init data.