Supervises many Omni.Session processes and provides id-based lifecycle management.

The Manager is an app-level Supervisor. Apps define their own module that uses it — following the Ecto.Repo convention — naming the host application via otp_app: and dropping the module into a supervision tree:

defmodule MyApp.Sessions do
  use Omni.Session.Manager, otp_app: :my_app
end

# config/config.exs
config :my_app, MyApp.Sessions,
  store: {Omni.Session.Store.FileSystem, base_path: "priv/sessions", otp_app: :my_app}

# application.ex
children = [MyApp.Sessions]

Supervisor start-opts override app-env values when both are set, for cases where a value must be computed at boot:

children = [
  {MyApp.Sessions, store: dynamic_store()}
]

Call sites go through the use-generated shorthand:

{:ok, pid}             = MyApp.Sessions.create(agent: [model: {:anthropic, "claude-sonnet-4-5"}])
{:ok, pid, :started}   = MyApp.Sessions.open("abc-123")
:ok                    = MyApp.Sessions.close("abc-123")
{:ok, sessions}        = MyApp.Sessions.list(limit: 50)

What the Manager supervises

MyApp.Sessions (Supervisor, :rest_for_one)
├── MyApp.Sessions.Registry (Registry, keys: :unique)
├── MyApp.Sessions.DynamicSupervisor (DynamicSupervisor)
└── MyApp.Sessions.Tracker (GenServer)

Sessions live under the DynamicSupervisor with restart: :temporary — on crash they do not auto-restart. The Registry maps session ids to pids; on close/2 or crash, entries are removed automatically. The Tracker observes every running session and powers list_open/1 plus the Manager-level subscribe/1 feed.

Running sessions outlive the caller that created them. The caller is auto-subscribed as a :controller by default, so idle-shutdown kicks in once the caller drops off (see :idle_shutdown_after).

Cross-session view

list_open/1 returns a snapshot of all running sessions; each entry is %{id, title, status, pid}. subscribe/1 atomically returns the same snapshot and starts streaming live events to the caller:

{:manager, MyApp.Sessions, :opened, %{id, title, status, pid}}
{:manager, MyApp.Sessions, :status, %{id, status}}
{:manager, MyApp.Sessions, :title,  %{id, title}}
{:manager, MyApp.Sessions, :closed, %{id}}

The second element is the Manager module — what the caller already holds — so subscribers watching multiple Managers route events by pattern-matching.

Configuration

Options resolve in this order (highest priority first): supervisor start-opts → Application.get_env(otp_app, ManagerModule, []) → the defaults below.

• :store — required. {module, keyword()} — the store adapter tuple. Used by every session this Manager starts, and by list/2 and delete/2.

• :idle_shutdown_after — nil | non_neg_integer(). Default for sessions this Manager starts; overridden per-call. Defaults to 300_000 (5 minutes) when absent. Pass nil to disable Manager-wide.

• :name — overrides the registered name. Defaults to the use-ing module.

open/3 return shape

open/3 tells you whether the Manager actually started the session or attached to an already-running one:

{:ok, pid, :started}   # Manager started the process; opts applied
{:ok, pid, :existing}  # process was already up; opts silently dropped

On the :existing branch, start-time opts (:agent, :title, :idle_shutdown_after, :subscribers) are dropped because mutating a live session's configuration safely requires knowing its agent status. Callers who genuinely need fresh config use close/2 + open/3.

:subscribe is honored in both branches — it is a subscription, not a state mutation.