MingaAgent.SessionManager (Minga v0.1.0)

Copy Markdown View Source

Owns agent session lifecycle independently of any UI.

Maps stable session IDs to session PIDs. Local scratch sessions still use human-readable generated IDs (e.g., "session-1"), while remote attach sessions pass a deterministic :session_id derived from their server-side working directory. Sessions are started via MingaAgent.Supervisor (DynamicSupervisor) and monitored here. When a session dies or restarts, the manager broadcasts lifecycle events so the Editor (or any subscriber) can react without monitoring PIDs directly.

Summary

Types

restart_state()

Restart bookkeeping for a managed session that is being recovered.

session_entry()

An entry in the sessions map.

state()

Internal state of the SessionManager.

Functions

abort(session_id)

Aborts the current operation on a session by ID.

abort(manager, session_id)

Aborts the current operation on a session by ID through the given manager.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_session(session_id)

Looks up the PID for a session ID.

get_session(manager, session_id)

Looks up the PID for a session ID through the given manager.

list_background_subagents(parent_session_pid \\ nil)

Lists background sub-agents for a parent session pid, or all background sub-agents when parent is nil.

list_background_subagents(manager, parent_session_pid)

Lists background sub-agents through the given manager.

list_sessions()

Lists all active sessions as {id, pid, metadata} tuples.

list_sessions(manager)

Lists all active sessions through the given manager.

send_prompt(session_id, prompt)

Sends a user prompt to a session by ID.

send_prompt(manager, session_id, prompt)

Sends a user prompt to a session by ID through the given manager.

session_id_for_pid(pid)

Looks up the session ID for a PID.

session_id_for_pid(manager, pid)

Looks up the session ID for a PID through the given manager.

session_token(session_id)

Returns the broker token for a live session. Used by the remote API bootstrap path.

session_token(manager, session_id)

Returns the broker token for a live session through the given manager.

stable_session_id_for_workdir(path)

Builds the deterministic session ID used for a server-side working directory.

start_background_subagent(parent_session_pid, task, opts \\ [])

Starts a background sub-agent, sends it the task asynchronously, and returns a stable handle.

start_background_subagent(manager, parent_session_pid, task, opts)

Starts a background sub-agent through the given manager.

start_link(opts \\ [])

Starts the SessionManager.

start_or_get_session(session_id, opts \\ [])

Starts or returns the stable session with the given ID.

start_or_get_session(manager, session_id, opts)

Starts or returns the stable session with the given ID through the given manager.

start_session(opts \\ [])

Starts a new agent session with a generated human-readable ID.

start_session(manager, opts)

Starts a new agent session through the given manager.

stop_session(session_id)

Stops a session by its human-readable ID.

stop_session(manager, session_id)

Stops a session by its human-readable ID through the given manager.

stop_session_by_pid(pid)

Stops a session by its PID (looks up the ID internally).

stop_session_by_pid(manager, pid)

Stops a session by its PID through the given manager.

Types

restart_state()

@type restart_state() :: %{
  attempts: pos_integer(),
  window_started_at_ms: integer(),
  timer_ref: reference() | nil,
  timer_token: reference() | nil,
  old_pid: pid(),
  reason: term()
}

Restart bookkeeping for a managed session that is being recovered.

session_entry()

@type session_entry() :: %{
  pid: pid(),
  monitor_ref: reference() | nil,
  token: String.t(),
  restart_opts: keyword(),
  restart_state: restart_state() | nil
}

An entry in the sessions map.

state()

@type state() :: %{
  sessions: %{required(String.t()) => session_entry()},
  background_subagents: %{
    required(String.t()) => MingaAgent.Subagent.Handle.t()
  },
  next_id: pos_integer()
}

Internal state of the SessionManager.

Functions

abort(session_id)

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

Aborts the current operation on a session by ID.

abort(manager, session_id)

@spec abort(GenServer.server(), String.t()) :: :ok | {:error, :not_found}

Aborts the current operation on a session by ID through the given manager.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_session(session_id)

@spec get_session(String.t()) :: {:ok, pid()} | {:error, :not_found}

Looks up the PID for a session ID.

get_session(manager, session_id)

@spec get_session(GenServer.server(), String.t()) ::
  {:ok, pid()} | {:error, :not_found}

Looks up the PID for a session ID through the given manager.

list_background_subagents(parent_session_pid \\ nil)

@spec list_background_subagents(pid() | nil) :: [MingaAgent.Subagent.Handle.t()]

Lists background sub-agents for a parent session pid, or all background sub-agents when parent is nil.

list_background_subagents(manager, parent_session_pid)

@spec list_background_subagents(GenServer.server(), pid() | nil) :: [
  MingaAgent.Subagent.Handle.t()
]

Lists background sub-agents through the given manager.

list_sessions()

@spec list_sessions() :: [{String.t(), pid(), MingaAgent.SessionMetadata.t()}]

Lists all active sessions as {id, pid, metadata} tuples.

list_sessions(manager)

@spec list_sessions(GenServer.server()) :: [
  {String.t(), pid(), MingaAgent.SessionMetadata.t()}
]

Lists all active sessions through the given manager.

send_prompt(session_id, prompt)

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

Sends a user prompt to a session by ID.

send_prompt(manager, session_id, prompt)

@spec send_prompt(GenServer.server(), String.t(), String.t()) ::
  :ok | {:error, term()}

Sends a user prompt to a session by ID through the given manager.

session_id_for_pid(pid)

@spec session_id_for_pid(pid()) :: {:ok, String.t()} | {:error, :not_found}

Looks up the session ID for a PID.

session_id_for_pid(manager, pid)

@spec session_id_for_pid(GenServer.server(), pid()) ::
  {:ok, String.t()} | {:error, :not_found}

Looks up the session ID for a PID through the given manager.

session_token(session_id)

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

Returns the broker token for a live session. Used by the remote API bootstrap path.

session_token(manager, session_id)

@spec session_token(GenServer.server(), String.t()) ::
  {:ok, String.t()} | {:error, :not_found}

Returns the broker token for a live session through the given manager.

stable_session_id_for_workdir(path)

@spec stable_session_id_for_workdir(String.t()) :: String.t()

Builds the deterministic session ID used for a server-side working directory.

start_background_subagent(parent_session_pid, task, opts \\ [])

@spec start_background_subagent(pid() | nil, String.t(), keyword()) ::
  {:ok, MingaAgent.Subagent.Handle.t()} | {:error, term()}

Starts a background sub-agent, sends it the task asynchronously, and returns a stable handle.

start_background_subagent(manager, parent_session_pid, task, opts)

@spec start_background_subagent(
  GenServer.server(),
  pid() | nil,
  String.t(),
  keyword()
) ::
  {:ok, MingaAgent.Subagent.Handle.t()} | {:error, term()}

Starts a background sub-agent through the given manager.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the SessionManager.

start_or_get_session(session_id, opts \\ [])

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

Starts or returns the stable session with the given ID.

start_or_get_session(manager, session_id, opts)

@spec start_or_get_session(GenServer.server(), String.t(), keyword()) ::
  {:ok, String.t(), pid()} | {:error, term()}

Starts or returns the stable session with the given ID through the given manager.

start_session(opts \\ [])

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

Starts a new agent session with a generated human-readable ID.

Returns {:ok, session_id, pid} on success.

start_session(manager, opts)

@spec start_session(
  GenServer.server(),
  keyword()
) :: {:ok, String.t(), pid()} | {:error, term()}

Starts a new agent session through the given manager.

stop_session(session_id)

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

Stops a session by its human-readable ID.

stop_session(manager, session_id)

@spec stop_session(GenServer.server(), String.t()) :: :ok | {:error, :not_found}

Stops a session by its human-readable ID through the given manager.

stop_session_by_pid(pid)

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

Stops a session by its PID (looks up the ID internally).

stop_session_by_pid(manager, pid)

@spec stop_session_by_pid(GenServer.server(), pid()) :: :ok | {:error, :not_found}

Stops a session by its PID through the given manager.