| name | ai-core/locks |
| description | LockStore, InMemoryLockStore, LocksCapability and withLocks for multi-instance coordination in TanStack AI. Ships in @tanstack/ai — NOT in @tanstack/ai-persistence. Separate from AIPersistence state stores — not a stores key, not composable. InMemoryLockStore vs a distributed (e.g. Cloudflare Durable Object) lock, lease recovery, AbortSignal in critical sections. Use when sandbox or other middleware needs cross-worker mutual exclusion — NOT for storing messages/runs (use withPersistence).
|
| type | sub-skill |
| library | tanstack-ai |
| library_version | 0.42.0 |
| sources | ["TanStack/ai:docs/advanced/locks.md","TanStack/ai:packages/ai/src/activities/chat/middleware/locks.ts"] |
Locks (coordination — not persistence)
Dependency note: This skill builds on ai-core and ai-core/middleware.
withLocks is a ChatMiddleware that provides a capability. Locks are not
part of AIPersistence.stores and are not composed with
composePersistence — they ship in @tanstack/ai, independent of
@tanstack/ai-persistence.
Why separate?
State stores answer "what is durable chat data?"
Locks answer "who may run this critical section right now?"
withPersistence does not automatically lock a whole turn. Take a
per-thread (or other) lock yourself when multi-writer races matter.
Wire locks
import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
middleware: [
withLocks(new InMemoryLockStore()),
]
Alongside persistence — optional, locks do not require it:
import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
import { withPersistence } from '@tanstack/ai-persistence'
middleware: [withPersistence(persistence), withLocks(new InMemoryLockStore())]
withLocks provides LocksCapability for downstream middleware (e.g.
sandbox). Order: usually state first, locks alongside or after depending on
who consumes the capability.
The contract
interface LockStore {
withLock<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>
}
InMemoryLockStore ships in @tanstack/ai/locks: a per-key promise chain,
correct within a single process only. Multi-instance deployments need a
distributed implementation — you write it. The Cloudflare Durable Object recipe
is in ai-persistence/build-cloudflare-adapter (@tanstack/ai-persistence).
Type your own store with defineLock (autocomplete, no : LockStore
annotation), then hand it to withLocks. Acquire the key, run fn, release when
fn settles:
import { defineLock, withLocks } from '@tanstack/ai/locks'
import { acquire } from './my-lock-backend'
const locks = defineLock({
async withLock(key, fn) {
const { release, signal } = await acquire(key)
try {
return await fn(signal)
} finally {
release()
}
},
})
middleware: [withLocks(locks)]
Lease semantics
A good LockStore:
- Serializes owners per key,
- Uses leases (or equivalent) so a crashed owner cannot block forever,
- Passes an
AbortSignal into the critical section via withLock; when the
lease is lost, abort so work stops starting external mutations.
Callbacks must honor the signal and pass it to cancellable dependencies.
InMemoryLockStore never aborts its signal — within one process, ownership
cannot be lost.
Capability identity
The 'locks' capability token lives in @tanstack/ai/locks. Capability identity
is by object reference, so one shared token means a withLocks in the chain
reaches withSandbox automatically.
Common mistakes
HIGH: Importing locks from @tanstack/ai-persistence
They are not exported there. Use @tanstack/ai.
HIGH: Putting locks on AIPersistence.stores
Not supported. stores accepts only messages, runs, interrupts,
metadata — never locks. Use withLocks.
HIGH: Passing locks to composePersistence overrides
Same rejection, at the override layer. Locks are not state.
HIGH: Passing 'locks' to the conformance testkit's skip
skip accepts only chat state store keys. The suite does not cover locks
at all — test lease expiry and abort separately.
HIGH: InMemoryLockStore across multiple processes
No mutual exclusion between machines — use a distributed lock store.
MEDIUM: Ignoring lease abort
Continuing work after losing the lease races other owners.
Cross-references
- See also: ai-core/middleware/SKILL.md -- the middleware chain and capability plumbing
- See also:
@tanstack/ai-persistence skills (skills/ai-persistence/SKILL.md in that package) -- ai-persistence/server (state middleware) and ai-persistence/build-cloudflare-adapter (Durable Object lock recipe)
