Synapse.Orchestrator.Runtime (Synapse v0.1.1)

GenServer responsible for keeping declaratively defined agents running.

The runtime watches a configuration source (file or module), validates each entry into a %Synapse.Orchestrator.AgentConfig{} struct, and reconciles that desired topology against currently running processes. Missing agents are spawned through Synapse.Orchestrator.AgentFactory, stale ones are retired, and crashed processes are respawned on the next reconciliation pass.

Summary

Types

option()

Functions

add_agent(server, config)

Dynamically adds an agent to the runtime.

agent_status(server, agent_id)

Returns the status information for a specific agent.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_agent_config(server, agent_id)

Returns the configuration for a specific agent.

get_skill(server, skill_id)

Gets skill metadata by ID (without loading the body).

health_check(server)

Returns overall health information about the orchestrator.

list_agents(server)

Returns information about currently running agents.

list_skills(server)

Lists all available skills (metadata only).

load_skill_body(server, skill_id)

Loads the full skill body for a given skill ID.

reload(server)

Triggers an immediate reconciliation cycle.

remove_agent(server, agent_id)

Removes an agent from the runtime.

skill_metadata(server)

Returns a metadata summary of discovered skills.

start_link(opts)

Types

option()

@type option() ::
  {:config_source, String.t() | module()}
  | {:router, atom() | nil}
  | {:registry, atom() | nil}
  | {:reconcile_interval, pos_integer()}
  | {:skill_directories, [String.t()]}

Functions

add_agent(server, config)

@spec add_agent(pid(), map() | keyword()) :: {:ok, pid()} | {:error, term()}

Dynamically adds an agent to the runtime.

agent_status(server, agent_id)

@spec agent_status(pid(), atom()) ::
  {:ok,
   %{
     pid: pid(),
     alive?: boolean(),
     config: Synapse.Orchestrator.AgentConfig.t(),
     running_agent: Synapse.Orchestrator.Runtime.RunningAgent.t()
   }}
  | {:error, :not_found}

Returns the status information for a specific agent.

child_spec(init_arg)

@spec child_spec([option()]) :: Supervisor.child_spec()

Returns a specification to start this module under a supervisor.

See Supervisor.

get_agent_config(server, agent_id)

@spec get_agent_config(pid(), atom()) ::
  {:ok, Synapse.Orchestrator.AgentConfig.t()} | {:error, :not_found}

Returns the configuration for a specific agent.

get_skill(server, skill_id)

@spec get_skill(pid(), String.t()) ::
  {:ok, Synapse.Orchestrator.Skill.t()} | {:error, :not_found | :no_registry}

Gets skill metadata by ID (without loading the body).

health_check(server)

@spec health_check(pid()) :: %{
  total: non_neg_integer(),
  running: non_neg_integer(),
  failed: non_neg_integer(),
  reconcile_count: non_neg_integer(),
  last_reconcile: DateTime.t() | nil
}

Returns overall health information about the orchestrator.

list_agents(server)

@spec list_agents(pid()) :: [Synapse.Orchestrator.Runtime.RunningAgent.t()]

Returns information about currently running agents.

list_skills(server)

@spec list_skills(pid()) :: [Synapse.Orchestrator.Skill.t()] | {:error, :no_registry}

Lists all available skills (metadata only).

load_skill_body(server, skill_id)

@spec load_skill_body(pid(), String.t()) ::
  {:ok, Synapse.Orchestrator.Skill.t()} | {:error, term()}

Loads the full skill body for a given skill ID.

reload(server)

@spec reload(pid()) :: :ok

Triggers an immediate reconciliation cycle.

remove_agent(server, agent_id)

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

Removes an agent from the runtime.

skill_metadata(server)

@spec skill_metadata(pid()) :: String.t()

Returns a metadata summary of discovered skills.

start_link(opts)

@spec start_link([option()]) :: GenServer.on_start()