MingaAgent.RemoteAPI (Minga v0.1.0)

Copy Markdown View Source

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.

Summary

Types

attach_result()

Attach result returned by the broker.

role()

Remote attachment role.

session_info()

Public session record returned by the broker.

Functions

add_system_message(session_id, token, client_pid, message, level \\ :info)

Adds a system message to a session through the broker.

approve(session_id, token, client_pid, decision)

Responds to a tool approval as an attached driver.

approve(session_id, token, client_pid, approval_id, decision)

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

attach(session_id, token, subscriber_pid, opts \\ [])

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

authorize(session_id, token)

Authorizes a broker call with the per-session token.

begin_oauth(session_id, token, client_pid)

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

complete_oauth(session_id, token, client_pid, ref, pasted)

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

detach(session_id, token, client_pid)

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

list_sessions()

Lists live sessions through the broker.

send_prompt(session_id, token, client_pid, prompt)

Sends a prompt as an attached driver.

session_data(session_id)

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

session_data(session_id, token)

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

start_or_get_for_workdir(workdir, opts \\ [])

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

start_session(opts \\ [])

Starts a new session through the broker.

stop_session(session_id, token)

Stops a session through the broker.

stop_workdir_session(workdir)

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

Types

attach_result()

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

Attach result returned by the broker.

role()

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

Remote attachment role.

session_info()

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

Public session record returned by the broker.

Functions

add_system_message(session_id, token, client_pid, message, level \\ :info)

@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(session_id, token, client_pid, decision)

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

Responds to a tool approval as an attached driver.

approve(session_id, token, client_pid, approval_id, decision)

@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(session_id, token, subscriber_pid, opts \\ [])

@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(session_id, token)

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

Authorizes a broker call with the per-session token.

begin_oauth(session_id, token, client_pid)

@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(session_id, token, client_pid, ref, pasted)

@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(session_id, token, client_pid)

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

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

list_sessions()

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

Lists live sessions through the broker.

send_prompt(session_id, token, client_pid, prompt)

@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(session_id)

@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(session_id, token)

@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(workdir, opts \\ [])

@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(opts \\ [])

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

Starts a new session through the broker.

stop_session(session_id, token)

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

Stops a session through the broker.

stop_workdir_session(workdir)

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

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