Module locks 

Lock coordinates for the per-agent lockfiles.

Two families, both under the per-state locks root and both held through objectiveai_sdk::lockfile (contents are always empty — these locks carry liveness, not data):

• Per-instance: <state>/locks/agents/instances/<…> — the agent_instance_hierarchy is split on /; every segment but the last becomes a literal subdirectory, the last segment is the lockfile key (the SDK escapes the key; directory segments ride raw). A held instance lock ⇔ a live process owns that agent.
• Per-tag: <state>/locks/agents/tags keyed by the tag name — held while a spawn is materializing an un-upgraded (GROUPED) tag, released once the spawn claims its minted AIH lock.

No create_dir_all here — the SDK’s acquire functions create the directory chain themselves.

In-process gate

objectiveai_sdk::lockfile is a cross-PROCESS mutex that is REENTRANT in-process (its HELD map refcounts per process), so two concurrent in-process tasks acquiring the SAME agent key both succeed reentrantly instead of mutually excluding. AgentLock closes that gap: every agent lock is taken through try_acquire/wait_acquire here, which lock a per-key in-process tokio::sync::Mutex (the AgentLockMap on crate::context::Context) FIRST, then the lockfile — and release the lockfile claim FIRST, then the in-process guard LAST. The in-process lock both precedes and succeeds the cross-process one.

Structs

AcquiredFamily

An acquired lock Family, partitioned for the registry.

AgentLock

A held agent lock: the in-process Mutex guard PLUS the cross-process lockfile LockClaim. Release order is enforced — lockfile claim first, in-process guard last (the guard field is dropped after claim is taken).

Enums

Family

The lock “family” of an agent target — the set of locks a live agent must hold so that NONE of its tags can be relocated (tags apply) or have labs detached (laboratories detach) while it is active.

Functions

agent_instance_lock

(lock_dir, key) for an agent_instance_hierarchy.

agent_tag_lock

(lock_dir, key) for an agent tag.

family_coords

Resolve a Family to its lock coordinates. Group → a tag lock per group member; Hierarchy → the AIH instance lock FIRST, then a tag lock per bound tag.

try_acquire

Acquire an agent lock NON-BLOCKING. Returns None if the key is busy in-process (another task holds the guard) OR held cross-process. On the cross-process miss the in-process guard is dropped before returning, so it never lingers.

try_acquire_all

Acquire EVERY coord NON-BLOCKING, all-or-nothing, concurrently. None if any coord is busy (in-process guard taken OR cross-process held) — the ones that were acquired drop here, releasing them. Deadlock-free: every leg is a non-blocking try, so acquisition order never matters.

try_acquire_family

Resolve + acquire a whole Family NON-BLOCKING, all-or-nothing, and partition it for the registry (AIH lock split out from the tag locks). Ok(None) if any member is busy. Used by spawn / deliver, which resolve the family up front and acquire it in one shot.

wait_acquire

Acquire an agent lock, BLOCKING at both layers: the in-process Mutex first, then the cross-process lockfile.

Type Aliases

AgentLockMap

Per-key in-process gate for agent locks, keyed by the SAME (dir, key) the lockfile uses. Lives on crate::context::Context, shared across clones.