ai-core/locks

Implements distributed lock coordination for TanStack AI middleware critical sections.

3.1k|316|Updated Oct 8, 2025
One-click install
npx skills add https://github.com/TanStack/ai --skill ai-core-locks
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: ai-core/locks
Source: https://github.com/TanStack/ai/tree/main/packages/ai/skills/ai-core/locks
Command: npx skills add https://github.com/TanStack/ai --skill ai-core-locks

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @tanstack/ai.

What problem does it solve?

Multi-instance TanStack AI deployments risk race conditions when multiple workers mutate shared chat state concurrently, and persistence stores alone do not provide mutual exclusion for critical sections.

Core Features & Use Cases

  • LockStore contract: Define a withLock(key, fn) interface that serializes owners per key and passes an AbortSignal into critical sections.
  • InMemoryLockStore: Use the built-in per-key promise chain for single-process coordination, or implement a distributed store with defineLock for multi-instance deployments.
  • Middleware integration: Wire withLocks into the ChatMiddleware chain to expose the LocksCapability to downstream middleware such as sandbox.
  • Use Case: A sandbox middleware running across multiple Cloudflare workers acquires a per-thread lease before mutating shared state, aborting work automatically when the lease is lost.

Quick Start

Add withLocks with an InMemoryLockStore to my TanStack AI chat middleware chain so sandbox operations are mutually exclusive per thread.

Frequently Asked Questions about ai-core/locks

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add distributed locks to TanStack AI middleware?

Import withLocks from @tanstack/ai/locks and pass a LockStore implementation to it in your middleware array. Use InMemoryLockStore for single-process apps, or define a custom distributed store with defineLock for multi-instance deployments.

What is the difference between withLocks and withPersistence in TanStack AI?

withPersistence manages durable chat state stores like messages and runs, while withLocks coordinates who may execute a critical section right now. Locks are not part of AIPersistence.stores and ship in @tanstack/ai, not @tanstack/ai-persistence.

Does InMemoryLockStore work across multiple processes?

No, InMemoryLockStore only provides mutual exclusion within a single process using a per-key promise chain. Multi-instance deployments require a distributed implementation, such as the Cloudflare Durable Object recipe in @tanstack/ai-persistence.

Can I add locks to AIPersistence stores or composePersistence?

No, AIPersistence.stores only accepts messages, runs, interrupts, and metadata keys. Passing locks to stores or composePersistence overrides is rejected; use the withLocks middleware instead.

Why does my locked critical section need to handle AbortSignal?

The AbortSignal passed to withLock's callback fires when the lease is lost, signaling that another owner may now hold the lock. Continuing work after abort races other owners, so callbacks must pass the signal to cancellable operations.