ai-core/locks

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()), // single process
]

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)]