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 { chat } from '@tanstack/ai'
import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId: 'thread-1',
  middleware: [
    withLocks(new InMemoryLockStore()), // single process
  ],
})

Alongside persistence — optional, locks do not require it:

import { chat } from '@tanstack/ai'
import { withLocks, InMemoryLockStore } from '@tanstack/ai/locks'
import { openaiText } from '@tanstack/ai-openai'
import { memoryPersistence, withPersistence } from '@tanstack/ai-persistence'

const persistence = memoryPersistence()
const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId: 'thread-1',
  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 { chat } from '@tanstack/ai'
import { defineLock, withLocks } from '@tanstack/ai/locks'
import { openaiText } from '@tanstack/ai-openai'
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()
    }
  },
})

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages,
  threadId: 'thread-1',
  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)