​

TurnLockProtocol

Defined in the protocols module.

AI Agent Contract for serialising a session’s turns — cluster-wide or in-process. The gateway holds this lock for the whole agent turn keyed on the resolved session id, so only one turn ever runs against one session’s transcript at a time. With the default in-process backend (:class:LocalTurnLock) this reproduces today’s asyncio.Lock behaviour exactly and adds no dependency. With a distributed backend (a RedisTurnLock in the wrapper/bot package, reusing the scheduler’s proven owner+TTL lease pattern) the same async with seam serialises turns across every replica. Contract:

• :meth:acquire blocks until the lease for key is held, then returns a :class:TurnLeaseToken. ttl bounds how long the lease survives without renewal so a crashed holder self-heals.
• :meth:release is identity-checked against the token’s owner and idempotent: releasing an already-expired/reclaimed lease is a no-op, never an error and never another owner’s lease.
• :meth:hold is the ergonomic async context manager wrapping acquire/release, used at the async with self._turn_lock.hold(...) call site.

A backend outage must fail open (degrade to a loud warning rather than wedging a healthy session), mirroring the fail-safe defaults elsewhere.

​

Methods

​

Source