Keyed singleton registry with lifecycle management and optional storage-backed hibernation.

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 storage — 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 storage config 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),
    storage: {Jido.Storage.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)
• :storage - nil, storage module, or {StorageModule, opts} (optional)
  • Omitted: derive from Jido instance (:jido, or agent_opts[:jido], or Jido)
  • nil: disable hibernate/thaw for this manager
• :jido - Jido instance atom used for default storage resolution (optional)
• :registry_partitions - Partition count for manager registry (default: schedulers online)
• :agent_opts - Additional options passed to AgentServer

Lifecycle

1. get/3 looks up by key in Registry
2. If not found and storage enabled, tries to thaw from storage
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 storage (if configured) then stop

Persistence keys are manager-scoped ({manager_name, pool_key}), so multiple managers can safely share the same storage backend without checkpoint collisions.

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