# `MingaAgent.RemoteAPI`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga_agent/remote_api.ex#L1)

Brokered control boundary for remote agent sessions.

Remote clients may use Erlang distribution as the transport for the MVP, but they should call only this module across the node boundary. The public contract is the verb set here, not arbitrary `:erpc` into `SessionManager`, `Session`, or other internals.

The trust model is deliberately explicit. The Erlang cookie gates trusted node membership and is all-or-nothing: any cookie holder can bypass this broker with raw distribution. The per-session token checked here is defense in depth for Minga's own clients and the seam for a future socket transport; it is not isolation from an untrusted cookie holder.

# `attach_result`

```elixir
@type attach_result() :: MingaAgent.RemoteAPI.AttachResult.t()
```

Attach result returned by the broker.

# `role`

```elixir
@type role() :: :driver | :viewer
```

Remote attachment role.

# `session_info`

```elixir
@type session_info() :: MingaAgent.RemoteAPI.SessionInfo.t()
```

Public session record returned by the broker.

# `add_system_message`

```elixir
@spec add_system_message(String.t(), String.t(), pid(), String.t(), :info | :error) ::
  :ok | {:error, term()}
```

Adds a system message to a session through the broker.

# `approve`

```elixir
@spec approve(String.t(), String.t(), pid(), MingaAgent.Session.approval_decision()) ::
  :ok | {:error, term()}
```

Responds to a tool approval as an attached driver.

# `approve`

```elixir
@spec approve(
  String.t(),
  String.t(),
  pid(),
  String.t() | nil,
  MingaAgent.Session.approval_decision()
) ::
  :ok | {:error, term()}
```

Responds to a stable tool approval id as an attached driver.

# `attach`

```elixir
@spec attach(String.t(), String.t(), pid(), keyword()) ::
  {:ok, attach_result()} | {:error, term()}
```

Attaches a client process to a session as driver or viewer.

# `authorize`

```elixir
@spec authorize(String.t(), String.t()) :: :ok | {:error, :unauthorized | :not_found}
```

Authorizes a broker call with the per-session token.

# `begin_oauth`

```elixir
@spec begin_oauth(String.t(), String.t(), pid()) ::
  {:ok, String.t(), String.t()} | {:error, term()}
```

Begins a server-side manual OAuth flow through the broker.

# `complete_oauth`

```elixir
@spec complete_oauth(String.t(), String.t(), pid(), String.t(), String.t()) ::
  {:ok, :openai} | {:error, term()}
```

Completes a server-side manual OAuth flow through the broker.

# `detach`

```elixir
@spec detach(String.t(), String.t(), pid()) :: :ok | {:error, term()}
```

Detaches a client process from a session without stopping the session.

# `list_sessions`

```elixir
@spec list_sessions() :: [session_info()]
```

Lists live sessions through the broker.

# `send_prompt`

```elixir
@spec send_prompt(
  String.t(),
  String.t(),
  pid(),
  String.t() | [ReqLLM.Message.ContentPart.t()]
) ::
  :ok | {:queued, :steering} | {:error, term()}
```

Sends a prompt as an attached driver.

# `session_data`

```elixir
@spec session_data(String.t()) ::
  {:ok, MingaAgent.SessionStore.session_data()} | {:error, term()}
```

Loads persisted session data through the broker for an ended session.

# `session_data`

```elixir
@spec session_data(String.t(), String.t()) ::
  {:ok, MingaAgent.SessionStore.session_data()} | {:error, term()}
```

Loads persisted session data through the broker for a live token-authorized session.

# `start_or_get_for_workdir`

```elixir
@spec start_or_get_for_workdir(
  String.t(),
  keyword()
) :: {:ok, session_info()} | {:error, term()}
```

Starts or returns the stable session for a server-side working directory.

# `start_session`

```elixir
@spec start_session(keyword()) :: {:ok, session_info()} | {:error, term()}
```

Starts a new session through the broker.

# `stop_session`

```elixir
@spec stop_session(String.t(), String.t()) :: :ok | {:error, term()}
```

Stops a session through the broker.

# `stop_workdir_session`

```elixir
@spec stop_workdir_session(String.t()) :: :ok | {:error, term()}
```

Stops the existing stable session for a workdir through the broker.

---

*Consult [api-reference.md](api-reference.md) for complete listing*