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

Aborts the current operation on a session.

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

Returns a capabilities manifest describing the runtime.

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

Returns structured descriptions of all active sessions.

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

Returns structured descriptions of all registered tools.

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

Executes a tool by name with the given arguments.

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

Looks up the PID for a session ID.

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

Looks up a tool spec by name.

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

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

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

Returns all registered tool specs.

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

Sends a user prompt to a session.

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

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

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

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

Stops a session by its human-readable ID.

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

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