Keyed singleton registry with lifecycle management and optional persistence.

InstanceManager provides a pattern for managing one agent per logical context (user session, game room, connection, conversation). This is NOT a pool—each key maps to exactly one agent instance. Features:

• Keyed singletons — one agent per key, lookup or start on demand
• Automatic lifecycle — idle timeout with attachment tracking
• Optional persistence — hibernate/thaw with pluggable storage backends
• Multiple registries — different agent types, different configurations

Architecture

Each instance manager consists of:

• A Registry for unique key → pid lookup
• A DynamicSupervisor for agent lifecycle
• Optional Store for hibernate/thaw persistence

Usage

# In your supervision tree
children = [
  Jido.Agent.InstanceManager.child_spec(
    name: :sessions,
    agent: MyApp.SessionAgent,
    idle_timeout: :timer.minutes(15),
    persistence: [
      store: {Jido.Agent.Store.ETS, table: :session_cache}
    ]
  )
]

# At runtime
{:ok, pid} = Jido.Agent.InstanceManager.get(:sessions, "user-123")
:ok = Jido.AgentServer.attach(pid)  # Track this caller as attached

Options

• :name - Instance manager name (required, atom)
• :agent - Agent module (required)
• :idle_timeout - Time in ms before idle agent hibernates/stops (default: :infinity)
• :persistence - Persistence configuration (optional)
  • :store - {StoreModule, opts} tuple
  • :key_fun - Custom key function (agent_module, agent_id) -> key
• :agent_opts - Additional options passed to AgentServer

Lifecycle

1. get/3 looks up by key in Registry
2. If not found and persistence enabled, tries to thaw from store
3. If still not found, starts fresh agent
4. Callers use attach/1 to track interest
5. When all attachments gone, idle timer starts
6. On idle timeout: hibernate to store (if configured) then stop

Phoenix Integration

# LiveView mount
def mount(_params, %{"session_key" => key}, socket) do
  if connected?(socket) do
    {:ok, pid} = Jido.Agent.InstanceManager.get(:sessions, key)
    :ok = Jido.AgentServer.attach(pid)
    {:ok, assign(socket, agent_pid: pid)}
  else
    {:ok, socket}
  end
end