Agents as content-addressed managed entities: keyed by spec digest, created
once, reused forever, superseded by NEW specs, destroyed only by explicit
prune — the exact lifecycle Provisioner.Environments gives environments.
The provider-side name is <base>_<digest8>, so a name collision can only
mean "this exact agent already exists", and recovery by name is version-correct
even with an empty store.
Summary
Functions
Build-if-absent for an agent. Returns {:ok, %Handle{}}.
Explicit GC: archives <base>_* agent versions beyond the newest keep:
(REQUIRED), never touching tagged digests or already-archived versions.
Resolve "base:tag" to the tagged agent's handle. {:error, :unknown_tag}
when the tag is absent, {:error, {:untracked_digest, d}} when its digest has
no provision entry (re-ensure_agent to heal). Split is on the FIRST colon only.
Point base:tag at an agent digest (or a handle's digest). Movable; tagged digests survive prune.
Functions
@spec ensure_agent(term(), ReqManagedAgents.Agent.Spec.t() | map(), keyword()) :: {:ok, ReqManagedAgents.Agent.Handle.t()} | {:error, term()}
Build-if-absent for an agent. Returns {:ok, %Handle{}}.
Opts: :name (base, default the spec's name), :store ({module, store_opts}),
:create_fun / :list_fun (test seams; default to ReqManagedAgents.Client
calls on the given client).
@spec prune_agents(term(), String.t(), keyword()) :: {:ok, %{archived: [String.t()], kept: [String.t()]}} | {:error, :keep_required | {:partial, [String.t()], {String.t(), term()}}}
Explicit GC: archives <base>_* agent versions beyond the newest keep:
(REQUIRED), never touching tagged digests or already-archived versions.
@spec resolve_agent( String.t(), keyword() ) :: {:ok, ReqManagedAgents.Agent.Handle.t()} | {:error, :unknown_tag} | {:error, {:untracked_digest, String.t()}}
Resolve "base:tag" to the tagged agent's handle. {:error, :unknown_tag}
when the tag is absent, {:error, {:untracked_digest, d}} when its digest has
no provision entry (re-ensure_agent to heal). Split is on the FIRST colon only.
Point base:tag at an agent digest (or a handle's digest). Movable; tagged digests survive prune.