Owns provider identity, configuration, process attachment, and retry state for one agent session.
Transitions are pure. MingaAgent.Session remains responsible for provider calls, process monitoring, timers, and code lease effects.
Summary
Types
External effect for the Session process to execute after a transition.
Ordered external effects returned by a pure lifecycle transition.
Current provider lifecycle phase with phase-specific state.
Provider restart backoff policy.
Provider retry history retained across process replacements.
Retry timer identity installed by the Session process.
Provider lifecycle state owned by a session.
Functions
Attaches a started provider process.
Records provider failure and detaches the failed process and lease.
Returns the most recent provider failure reason.
Installs a source-code lease acquired while provider startup is in progress.
Installs the timer identity created by the Session process for a scheduled retry.
Returns true in guards when no provider process is attached.
Returns the active provider code lease, or nil when no provider is attached.
Builds the initial lifecycle value from resolved provider configuration.
Returns the current lifecycle phase name.
Returns the active provider process, or nil when no provider is attached.
Replaces the model configuration while preserving process and retry identity.
Clears retry history for an explicit provider restart.
Calculates the next retry or records terminal retry exhaustion.
Returns the number of retries attempted in the current backoff window.
Consumes a matching retry timer token and rejects stale timer messages.
Returns the installed retry timer identity, if a retry is scheduled.
Returns the start of the current retry window.
Begins provider startup unless a provider is already attached.
Stops the lifecycle and clears attached process, lease, retry, and failure state.
Returns true when automatic retries are exhausted.
Types
@type effect() :: {:cancel_timer, reference()} | {:release_lease, Minga.Extension.CodeLease.t()} | {:stop_provider, pid()}
External effect for the Session process to execute after a transition.
@type effects() :: [effect()]
Ordered external effects returned by a pure lifecycle transition.
@type phase() :: {:stopped, Minga.Extension.CodeLease.t() | nil, retry_state()} | {:starting, Minga.Extension.CodeLease.t() | nil, retry_state()} | {:running, pid(), Minga.Extension.CodeLease.t() | nil, retry_state()} | {:retrying, retry_state(), retry_timer() | nil} | {:terminal_failure, retry_state()}
Current provider lifecycle phase with phase-specific state.
@type restart_policy() :: %{ base_delay_ms: pos_integer(), max_attempts: pos_integer(), max_delay_ms: pos_integer(), window_ms: non_neg_integer() }
Provider restart backoff policy.
@type retry_state() :: %{ attempts: non_neg_integer(), window_started_at_ms: integer() | nil, failure_reason: term() }
Provider retry history retained across process replacements.
Retry timer identity installed by the Session process.
@type t() :: %MingaAgent.Session.ProviderLifecycle{ id: String.t(), model_name: String.t(), module: module(), opts: keyword(), phase: phase(), provider_name: String.t(), restart_policy: restart_policy(), source: Minga.Extension.ContributionCleanup.contribution_source() }
Provider lifecycle state owned by a session.
Functions
Attaches a started provider process.
Records provider failure and detaches the failed process and lease.
Returns the most recent provider failure reason.
@spec install_lease(t(), Minga.Extension.CodeLease.t()) :: {:ok, t()} | {:invalid_phase, t()}
Installs a source-code lease acquired while provider startup is in progress.
Installs the timer identity created by the Session process for a scheduled retry.
Returns true in guards when no provider process is attached.
@spec lease(t()) :: Minga.Extension.CodeLease.t() | nil
Returns the active provider code lease, or nil when no provider is attached.
Builds the initial lifecycle value from resolved provider configuration.
@spec phase(t()) :: :stopped | :starting | :running | :retrying | :terminal_failure
Returns the current lifecycle phase name.
Returns the active provider process, or nil when no provider is attached.
Replaces the model configuration while preserving process and retry identity.
Clears retry history for an explicit provider restart.
@spec retry(t(), term(), integer()) :: {:retry, t(), pos_integer(), effects()} | {:terminal_failure, t(), effects()}
Calculates the next retry or records terminal retry exhaustion.
@spec retry_attempts(t()) :: non_neg_integer()
Returns the number of retries attempted in the current backoff window.
Consumes a matching retry timer token and rejects stale timer messages.
@spec retry_timer(t()) :: retry_timer() | nil
Returns the installed retry timer identity, if a retry is scheduled.
Returns the start of the current retry window.
Begins provider startup unless a provider is already attached.
Stops the lifecycle and clears attached process, lease, retry, and failure state.
Returns true when automatic retries are exhausted.