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

Public API for the Minga agent runtime.

Unifies session management, tool execution, and introspection into
a single entry point. External clients (API gateway, CLI tools, IDE
extensions) should call this module rather than reaching into
SessionManager, Tool.Registry, or Tool.Executor directly.

All functions here are Layer 1 (MingaAgent.*). They work in both
headless mode (`Minga.Runtime.start/1`) and full editor mode.

# `abort`

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

Aborts the current operation on a session.

# `capabilities`

```elixir
@spec capabilities() :: MingaAgent.Introspection.capabilities_manifest()
```

Returns a capabilities manifest describing the runtime.

# `describe_sessions`

```elixir
@spec describe_sessions() :: [MingaAgent.Introspection.session_description()]
```

Returns structured descriptions of all active sessions.

# `describe_tools`

```elixir
@spec describe_tools() :: [MingaAgent.Introspection.tool_description()]
```

Returns structured descriptions of all registered tools.

# `execute_tool`

```elixir
@spec execute_tool(String.t(), map()) :: MingaAgent.Tool.Executor.result()
```

Executes a tool by name with the given arguments.

# `get_session`

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

Looks up the PID for a session ID.

# `get_tool`

```elixir
@spec get_tool(String.t()) :: {:ok, MingaAgent.Tool.Spec.t()} | :error
```

Looks up a tool spec by name.

# `list_sessions`

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

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

# `list_tools`

```elixir
@spec list_tools() :: [MingaAgent.Tool.Spec.t()]
```

Returns all registered tool specs.

# `send_prompt`

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

Sends a user prompt to a session.

# `start_gateway`

```elixir
@spec start_gateway(keyword()) :: {:ok, pid()} | {:error, term()}
```

Starts the API gateway (WebSocket + JSON-RPC).

Does not start by default. Call explicitly from headless mode or when
external clients need to connect. The Editor boot path never calls this.

Options:
  * `:port` - TCP port to listen on (default: 4820)

# `start_session`

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

Starts a new agent session. Returns `{:ok, session_id, pid}`.

# `stop_session`

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

Stops a session by its human-readable ID.

# `tool_registered?`

```elixir
@spec tool_registered?(String.t()) :: boolean()
```

Returns true if a tool with the given name is registered.

---

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