lukasa1993/tanstack-skills-extracted/tanstack-ai-persistence-build-cloudflare-adapter

Cloudflare Chat Persistence

The deliverable is one file in the Worker — src/lib/chat-persistence.ts — exporting a factory that builds a ChatPersistence from the request's D1 binding, plus (when the app needs coordination) a Durable Object lock store. Tables go into the app's existing migrations/ directory and are applied with wrangler d1 migrations apply.

Do not create a package or a migration runner. Wrangler already tracks applied migrations; a second bookkeeping table only creates drift.

Read the Store Reference (docs/persistence/store-reference.md) for the store contracts, and ai-persistence/stores for the shape rules. This skill covers only the Cloudflare-specific parts.

1. Read the app before writing anything

2. Two independent pieces

D1 database      -> messages, runs, interrupts, metadata   (AIPersistence.stores)
Durable Object   -> LockStore                              (withLocks — NOT a store)

These do not compose into one object. AIPersistence.stores accepts exactly four keys. Putting locks in the map throws Unknown AIPersistence store key: locks; putting it in a composePersistence override throws Unknown AIPersistence override key: locks. Both also fail to type-check. Return the state persistence from one factory and the lock store from another, then wire them as two middlewares.

Most apps need only the first piece. Add the Durable Object when other middleware genuinely needs mutual exclusion across isolates — InMemoryLockStore gives none, because a Worker runs on many isolates at once.

3. Bindings are per-request

This is the one rule that separates Cloudflare from every other backend. A D1 binding does not exist at module scope, so chat-persistence.ts must export a factory, not a const:

import { defineAIPersistence } from '@tanstack/ai-persistence'
import type { ChatPersistence } from '@tanstack/ai-persistence'
 
/** Call inside a request handler — `env` is not available at module scope. */
export function chatPersistence(d1: D1Database): ChatPersistence {
  return defineAIPersistence({
    stores: {
      messages: createMessageStore(d1),
      runs: createRunStore(d1),
      interrupts: createInterruptStore(d1),
      metadata: createMetadataStore(d1),
    },
  })
}

Annotate ChatPersistence — bare AIPersistence is the all-optional bag and withPersistence rejects it. Building it per request is cheap: the stores hold no state beyond the binding.

4. The stores

Two routes, same invariants:

• Drizzle over D1 — if the app already runs Drizzle, wrap the binding with

drizzle(env.DB, { schema }) and follow ai-persistence/build-drizzle-adapter verbatim (its "if db is per-request" section is exactly this case). Stop reading here.

• Raw D1 — implement the four stores against d1.prepare(sql).bind(...):

.first() for get, .all() for list*, .run() for writes. D1 speaks SQLite, so this mirrors the node:sqlite walkthrough in the guide one-for-one; everything is already async, so no Promise.resolve wrapping.

The invariants are the whole game, whichever route you take:

On runs, findActiveRun is required. listByThread, listByParentRun, and listReclaimable are optional, so implement those only if the app needs them. withPersistence calls createOrResume, update, and get. reconstruct.ts calls findActiveRun for rejoin-by-thread and listByParentRun to put subagent cards back. @tanstack/ai-sandbox's reapDetachedRuns calls listReclaimable. reconstruct.ts also calls listByThread to find the parent runs of children that a tool call started. Consumers of the optional methods feature-detect with store.method?.(...) and degrade when one is absent. The conformance testkit does not: each optional method you leave out must be listed in skipMethods or the suite fails. listByParentRun is the exception. When it is absent, the subagent checks skip on their own.

createOrResume copies parentRunId, subagentRunId, and name on the first insert. A later call for the same runId leaves them unchanged. If the caller omits a field, omit it on the mapped record.

RunRecord.error is a structured RunError ({ message: string, code?: string }), so the table gets two columns rather than one JSON blob: error for the provider's prose and error_code for the stable classification an operator filters and groups by. Write both together in update, so a later code-less failure can never leave a stale error_code from an earlier one behind, and omit code from the mapped record when the column is null: ...(row.error != null ? { error: { message: row.error, ...(row.error_code != null ? { code: row.error_code } : {}) } } : {}). Other row mappers omit absent optionals the same way (...(row.sandbox_key != null ? { sandboxKey: row.sandbox_key } : {})) so records compare cleanly against the reference in-memory backend. JSON columns are text: JSON.parse on read, JSON.stringify on write. Timestamps are integer epoch ms.

sandbox_key, detached_since, cancel_requested, and driver_epoch are the durable-agent-runs columns. In update, check 'field' in patch for all four — never patch.field !== undefined — because a reattach clears detachedSince by passing it explicitly as undefined, which must bind NULL into the SET clause rather than being filtered out of it (a filtered clear leaves the stale value and the run looks permanently detached to the reaper). The same applies to cancelRequested: false written explicitly is a real, meaningful value distinct from "never set", not something to coerce away. See examples/ts-react-chat/src/lib/sqlite-persistence.ts (D1 speaks the same SQLite dialect) for the worked update body.

5. The migration

Write the tables into the app's migrations/ directory as a new numbered file:

CREATE TABLE IF NOT EXISTS chat_threads (
  thread_id text PRIMARY KEY NOT NULL,
  messages_json text NOT NULL,
  updated_at integer NOT NULL
);
CREATE TABLE IF NOT EXISTS chat_runs (
  run_id text PRIMARY KEY NOT NULL,
  thread_id text NOT NULL,
  status text NOT NULL,
  started_at integer NOT NULL,
  finished_at integer,
  error text,
  error_code text,
  usage_json text,
  sandbox_key text,
  detached_since integer,
  cancel_requested integer,
  driver_epoch integer,
  parent_run_id text,
  subagent_run_id text,
  name text
);
CREATE INDEX IF NOT EXISTS chat_runs_thread_status ON chat_runs (thread_id, status);
CREATE INDEX IF NOT EXISTS chat_runs_thread_started ON chat_runs (thread_id, started_at);
CREATE INDEX IF NOT EXISTS chat_runs_parent_started ON chat_runs (parent_run_id, started_at);
-- Powers listReclaimable: status = 'running' AND detached_since <= cutoff.
CREATE INDEX IF NOT EXISTS chat_runs_status_detached ON chat_runs (status, detached_since);
CREATE TABLE IF NOT EXISTS chat_interrupts (
  interrupt_id text PRIMARY KEY NOT NULL,
  run_id text NOT NULL,
  thread_id text NOT NULL,
  status text NOT NULL,
  requested_at integer NOT NULL,
  resolved_at integer,
  payload_json text NOT NULL,
  response_json text
);
CREATE INDEX IF NOT EXISTS chat_interrupts_thread ON chat_interrupts (thread_id, requested_at);
CREATE TABLE IF NOT EXISTS chat_metadata (
  namespace text NOT NULL,
  key text NOT NULL,
  value_json text NOT NULL,
  PRIMARY KEY (namespace, key)
);

Apply with wrangler d1 migrations apply <database-name> (--local first, then --remote). If the app also uses Drizzle, generate this file with drizzle-kit generate instead of hand-writing it — the SQL and the Drizzle table definitions must agree, so let one of them own the other.

An existing chat_runs table does not get the three subagent columns from CREATE TABLE IF NOT EXISTS, and the chat_runs_parent_started index then fails. To add subagent support to an existing database, apply a separate migration first: