@spec adapter_module(pid()) ::
  {:ok,
   :claude_agent_sdk
   | :codex_app_server
   | :copilot_client
   | :gemini_cli_client
   | :opencode_client}
  | {:error,
     :backend_not_present
     | {:invalid_session_info, term()}
     | {:session_backend_lookup_failed, term()}
     | {:unknown_backend, term()}}

Resolve the adapter facade module for a live session pid.

Returns {:ok, module} where module is the backend adapter module (e.g. :claude_agent_session), or {:error, reason}.

@spec backend(pid()) ::
  {:ok, :claude | :codex | :gemini | :opencode | :copilot}
  | {:error,
     :backend_not_present
     | {:invalid_session_info, term()}
     | {:session_backend_lookup_failed, term()}
     | {:unknown_backend, term()}}

Resolve the backend atom for a live session pid.

Returns {:ok, backend} where backend is one of :claude | :codex | :gemini | :opencode | :copilot, or {:error, reason} if the session is not registered.

@spec call(pid(), atom(), [term()]) :: {:ok, term()} | {:error, term()}

Call a backend-native function for a live session, routing by session pid.

The session pid is prepended to args before the call, so the effective call is AdapterModule.function(session, args...). The return value is normalised: bare terms are wrapped in {:ok, term}, existing {:ok, _} and {:error, _} tuples pass through unchanged.

Returns {:error, {:unsupported_native_call, function}} if the backend adapter does not export function/arity.

Example

{:ok, _} = BeamAgent.Raw.call(pid, :thread_realtime_start, [%{mode: "voice"}])

@spec call_backend(atom() | binary(), atom(), [term()]) ::
  {:ok, term()} | {:error, term()}

Call a backend facade function directly, without prepending a session pid.

backend_like may be a backend atom, a binary such as "claude", or any value accepted by :beam_agent_backend.normalize/1. The call is dispatched as AdapterModule.function(args...).

Use this for backend-scoped helpers not bound to an active session (e.g. listing all native Claude sessions). For session-bound calls, prefer call/3.

Example

{:ok, sessions} = BeamAgent.Raw.call_backend(:claude, :list_native_sessions, [])

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

Fetch the raw authentication status from the backend server for a session.

Delegates to the backend adapter's get_auth_status/1. The return value format is adapter-specific.

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

Fetch the last known session ID reported by the backend for a session.

Delegates to the backend adapter's get_last_session_id/1. Useful for correlating a BEAM session pid with the backend's own session identifier without going through BeamAgent.session_info/1.

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

Fetch all messages for a native Claude session by session ID binary.

Returns the raw message list from the Claude SDK session store.

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

Fetch messages for a native Claude session with options.

opts is a map passed directly to the Claude adapter. Use this variant when you need pagination or filtering supported by the underlying Claude adapter.

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

Fetch the raw status map from the backend server for a session.

Delegates to the backend adapter's get_status/1. The return value format is adapter-specific.

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

List all native Claude SDK sessions (no options).

Calls the Claude adapter directly and returns the raw session list from the Claude SDK session store. Not available on other backends.

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

List all native Claude SDK sessions with options.

opts is a map passed directly to the Claude adapter's list_native_sessions/1 function.

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

Probe the transport-level health of the backend server for a session.

Delegates to the backend adapter's server_health/1. The return value format is adapter-specific.

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

Destroy the session associated with a live session pid.

Resolves the session ID from the running session process via BeamAgent.session_info/1 and calls the backend's session_destroy function.

Use session_destroy/2 if the session process is no longer alive.

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

Destroy a session by providing an explicit session ID.

Use this variant when you have a known session_id binary but the session process may or may not still be running. The pid is still required to route to the correct backend adapter.