docs(adapters): add Cloudflare Agents as vendor-official state adapter (#669)

Adds Cloudflare Agents as a vendor-official **state** adapter —
`agents/chat-sdk`'s `createChatSdkState()`, a Chat SDK `StateAdapter`
that stores subscriptions, locks, queues, dedupe keys, thread/channel
state, transcripts, and history in Durable Object SQLite via
`ChatSdkStateAgent` sub-agents.

- `vendor-official/cloudflare-agents.mdx` state-adapter page (Agent
setup, wrangler DO migration, sharding, config, storage/cleanup)
- catalog entry in `packages/chat/src/adapters/index.ts` (`group:
vendor-official`, `type: state`)
- registry entry in `adapters.json` + `cloudflare-agents` in
vendor-official `meta.json`
- integration-test doc lists + changeset

Repo: https://github.com/cloudflare/agents · package `agents`
(`agents/chat-sdk`) ·
[docs](https://developers.cloudflare.com/agents/runtime/communication/chat-sdk/)

### Not wired into the create-chat-sdk CLI
This adapter runs inside a Cloudflare Worker with Durable Objects, not
the generated Next.js runtime, so it is intentionally kept out of the
scaffold:
- added to `CLI_INCOMPATIBLE_ADAPTERS` (rejected via `--adapter`, hidden
from the platform picker and e2e run, like `lark`/`matrix`)
- new `listCliStateAdapters()` filters the interactive **state** picker
and the `--help` adapter list (the state picker previously used raw
`listStateAdapters()` and would have offered it, then thrown on
selection)

### Tests
- `catalog/display.test.ts` — `listCliStateAdapters`: returns only state
adapters, includes `memory`/`redis`, and excludes `cloudflare-agents`
while asserting it *is* in the raw catalog
- `catalog/selection.test.ts` —
`resolveAdapterValue("cloudflare-agents")` throws "not supported"
- `cli/program.test.ts` — `buildAdapterList()` help text omits
`cloudflare-agents`
- existing `CLI_SCAFFOLD_SPEC covers every catalog adapter` +
docs-adapters/docs-content suites cover the catalog entry, registry
parity, and MDX imports

### Validation
- create-chat-sdk: **178 passed**, typecheck clean
- integration docs suites pass; Biome + knip clean

---------

Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>

Author: bensabic

.changeset/cloudflare-agents-vendor-adapter.md

@@ -0,0 +1,6 @@
+---
+"chat": patch
+"create-chat-sdk": patch
+---
+
+docs(adapters): add Cloudflare Agents as a vendor-official state adapter (`agents/chat-sdk`) to the catalog and docs listing. It is hidden from the create-chat-sdk CLI (Worker/Durable Objects runtime), and the interactive state picker now filters out CLI-incompatible state adapters.

apps/docs/adapters.json

@@ -159,6 +159,17 @@
     "author": "dcartertwo",
     "readme": "https://github.com/dcartertwo/chat-state-cloudflare-do/tree/13ebf545b302b7c8fdabf7de9c5de678e047ce5e"
   },
+  {
+    "name": "Cloudflare Agents",
+    "slug": "cloudflare-agents",
+    "type": "state",
+    "community": true,
+    "description": "Cloudflare Agents state adapter for Chat SDK. Stores subscriptions, locks, queues, and history in Durable Object SQLite via ChatSdkStateAgent sub-agents.",
+    "packageName": "agents",
+    "author": "Cloudflare",
+    "readme": "https://github.com/cloudflare/agents",
+    "vendorOfficial": true
+  },
   {
     "name": "MySQL",
     "slug": "mysql",

apps/docs/content/adapters/vendor-official/cloudflare-agents.mdx

@@ -0,0 +1,206 @@
+---
+title: Cloudflare Agents
+description: Vendor-official state adapter for Chat SDK backed by Cloudflare Agents. Stores subscriptions, locks, queues, dedupe keys, thread and channel state, transcripts, and message history in Durable Object SQLite via ChatSdkStateAgent sub-agents.
+packageName: agents
+slug: cloudflare-agents
+type: state
+tagline: State adapter for Chat SDK that persists subscriptions, locks, queues, and history in Durable Object SQLite — sharded across Cloudflare Agents sub-agents, with no Redis or external database.
+community: true
+vendorOfficial: true
+author: Cloudflare
+mdxBody: true
+features:
+  persistence: yes
+  multiInstance: yes
+  subscriptions: yes
+  distributedLocking: yes
+  keyValueCache: yes
+  lists: yes
+  queues: yes
+  automaticReconnect: yes
+  cluster:
+    status: partial
+    label: Sharding
+  sentinel: no
+  keyPrefix:
+    status: yes
+    label: shardKey
+---
+
+Use `agents/chat-sdk` when you run [Chat SDK](https://chat-sdk.dev) inside a [Cloudflare Agent](https://developers.cloudflare.com/agents/). It provides a Chat SDK `StateAdapter` that stores subscriptions, locks, queues, dedupe keys, thread and channel state, callback metadata, transcripts, and thread history in Durable Object SQLite. Each state shard is a `ChatSdkStateAgent` sub-agent under your ingress Agent.
+
+Use it with any Chat SDK adapter — Telegram, Slack, Discord, Teams, or Google Chat.
+
+## Install
+
+<PackageInstall package="agents chat" />
+
+## Quick start
+
+Create a parent Agent that owns your Chat SDK runtime and pass `createChatSdkState()` as the `state` option. Export `ChatSdkStateAgent` from your Worker entry point so sub-agent routing can resolve it.
+
+```typescript title="src/index.ts" lineNumbers
+import { Agent } from "agents";
+import { createChatSdkState } from "agents/chat-sdk";
+import { Chat } from "chat";
+import { createTelegramAdapter } from "@chat-adapter/telegram";
+
+export { ChatSdkStateAgent } from "agents/chat-sdk";
+
+export class MessengerAgent extends Agent<Env> {
+  private chat!: Chat;
+
+  onStart() {
+    const telegram = createTelegramAdapter({
+      botToken: this.env.TELEGRAM_BOT_TOKEN,
+      mode: "webhook",
+      userName: "my_bot",
+    });
+
+    this.chat = new Chat({
+      adapters: { telegram },
+      userName: "my_bot",
+      state: createChatSdkState(),
+      concurrency: { strategy: "burst", debounceMs: 600 },
+    });
+  }
+}
+```
+
+When `createChatSdkState()` runs inside an Agent lifecycle method or request handler, it uses the current Agent as the parent (via `getCurrentAgent()`) and creates state shards with `this.subAgent()`.
+
+## Wrangler configuration
+
+Add the parent Agent to your Durable Object migration and enable `nodejs_compat`:
+
+```jsonc title="wrangler.jsonc"
+{
+  "compatibility_date": "2026-07-02",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [{ "class_name": "MessengerAgent", "name": "MessengerAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MessengerAgent"] }]
+}
+```
+
+```toml title="wrangler.toml"
+compatibility_date = "2026-07-02"
+compatibility_flags = ["nodejs_compat"]
+
+[[durable_objects.bindings]]
+class_name = "MessengerAgent"
+name = "MessengerAgent"
+
+[[migrations]]
+new_sqlite_classes = ["MessengerAgent"]
+tag = "v1"
+```
+
+## State sharding
+
+By default, state is sharded by the first two colon-separated segments of a thread-like key. For example, `telegram:-100123:456` and `telegram:-100123:789` share the shard `telegram:-100123`.
+
+The default key sharder recognizes these Chat SDK key prefixes:
+
+- `thread-state:`
+- `channel-state:`
+- `msg-history:`
+- `transcripts:user:`
+
+Unknown keys use the adapter's default shard name, `default`.
+
+### Custom sharding
+
+Use `shardKey` to control how thread IDs map to state sub-agent names, and `keyShard` for non-thread-shaped keys that should still route to a provider-specific shard:
+
+```typescript
+const state = createChatSdkState({
+  shardKey(threadId) {
+    return threadId.split(":").slice(0, 2).join(":");
+  },
+  keyShard(key) {
+    if (!key.startsWith("dedupe:telegram:")) {
+      return undefined;
+    }
+
+    const chatId = key.slice("dedupe:telegram:".length).split(":")[0];
+    return chatId ? `telegram:${chatId}` : undefined;
+  },
+});
+```
+
+Returning `undefined` from `keyShard` falls back to the built-in key sharder and then to the default shard.
+
+## Configuration
+
+<TypeTable
+  type={{
+    parent: {
+      type: "Agent",
+      description:
+        "Parent Agent that calls `subAgent()` to create state shards. Defaults to the current Agent from `getCurrentAgent()`.",
+    },
+    agent: {
+      type: "typeof ChatSdkStateAgent",
+      description:
+        "Custom subclass of `ChatSdkStateAgent`. Defaults to `ChatSdkStateAgent`.",
+    },
+    name: {
+      type: "string",
+      default: '"default"',
+      description: "Default shard name for keys that cannot be mapped.",
+    },
+    shardKey: {
+      type: "(threadId: string) => string",
+      description: "Maps Chat SDK thread IDs and lock keys to a shard name.",
+    },
+    keyShard: {
+      type: "(key: string) => string | undefined",
+      description:
+        "Maps generic Chat SDK cache or list keys to a shard name. Return `undefined` to fall back to the built-in sharder.",
+    },
+  }}
+/>
+
+## What is stored
+
+The adapter implements the full Chat SDK `StateAdapter` interface:
+
+- Subscriptions for `thread.subscribe()` and `thread.unsubscribe()`.
+- Locks for per-thread or per-channel concurrency.
+- Pending message queues for `queue`, `debounce`, and `burst` concurrency strategies.
+- Generic key-value cache entries with optional TTL.
+- Append-only lists with max-length trimming and list-level TTL refresh.
+
+Chat SDK features built on these primitives include message deduplication, thread and channel state, persistent thread history (for adapters that opt in to `persistThreadHistory`), callback URL token storage, modal context storage, and cross-platform transcripts.
+
+## Cleanup behavior
+
+TTL reads are strict: expired locks, cache values, queue entries, and list entries are ignored or deleted before they are returned.
+
+Physical cleanup is lazy. `ChatSdkStateAgent` schedules one cleanup callback for the earliest known expiry and reschedules after cleanup runs. This keeps idle shards quiet while preventing expired rows from accumulating indefinitely.
+
+## API
+
+### `createChatSdkState(options)`
+
+Creates a Chat SDK `StateAdapter` backed by a `ChatSdkStateAgent` sub-agent. Options are optional — the defaults resolve the parent from `getCurrentAgent()` and shard by thread-like key prefixes.
+
+### `ChatSdkStateAgent`
+
+The sub-agent class that stores state in SQLite. Export it from your Worker entry point so the runtime can create it:
+
+```typescript
+export { ChatSdkStateAgent } from "agents/chat-sdk";
+```
+
+## Example
+
+- [GitHub](https://github.com/cloudflare/agents)
+- [Chat SDK messenger example](https://github.com/cloudflare/agents/tree/main/examples/chat-sdk-messenger) — a Telegram messenger bot with Chat SDK state in sub-agents, burst/debounce concurrency, and AI replies running in managed fibers.
+- [Cloudflare Agents docs](https://developers.cloudflare.com/agents/runtime/communication/chat-sdk/)
+
+## Feature support
+
+<FeatureSupport />

apps/docs/content/adapters/vendor-official/meta.json

@@ -12,6 +12,7 @@
     "velt",
     "kapso",
     "linq",
-    "photon"
+    "photon",
+    "cloudflare-agents"
   ]
 }

packages/chat/src/adapters/index.ts

@@ -198,6 +198,22 @@ export const ADAPTERS = {
     slug: "agentphone",
     type: "platform",
   },
+  "cloudflare-agents": {
+    description:
+      "Cloudflare Agents state adapter for Chat SDK. Stores subscriptions, locks, queues, and history in Durable Object SQLite via ChatSdkStateAgent sub-agents.",
+    env: {
+      config: ["parent", "agent", "name", "shardKey", "keyShard"],
+      notes:
+        "No environment variables are required. State is stored in Durable Object SQLite via ChatSdkStateAgent sub-agents; add the parent Agent to your Durable Object migration and re-export ChatSdkStateAgent from the Worker entry point.",
+    },
+    factoryExport: "createChatSdkState",
+    group: "vendor-official",
+    name: "Cloudflare Agents",
+    packageName: "agents",
+    peerDeps: [],
+    slug: "cloudflare-agents",
+    type: "state",
+  },
   discord: {
     description:
       "Create Discord bots with slash commands, threads, and rich embeds.",

packages/create-chat-sdk/src/catalog/compatibility.ts

@@ -10,6 +10,8 @@ import type { AdapterSlug } from "chat/adapters";
  * are hidden from the CLI prompts and rejected when passed via `--adapter`.
  */
 const CLI_INCOMPATIBLE_ADAPTERS = {
+  "cloudflare-agents":
+    "it runs inside a Cloudflare Worker with Durable Objects, not the generated Next.js runtime",
   lark: "it requires a long-running WebSocket connection",
   matrix: "it requires a long-running sync process",
 } as const satisfies Partial<Record<AdapterSlug, string>>;

packages/create-chat-sdk/src/catalog/display.test.ts

@@ -1,6 +1,6 @@
-import { listPlatformAdapters } from "chat/adapters";
+import { listPlatformAdapters, listStateAdapters } from "chat/adapters";
 import { describe, expect, it } from "vitest";
-import { listCliPlatformAdapters } from "./display.js";
+import { listCliPlatformAdapters, listCliStateAdapters } from "./display.js";
 
 describe("listCliPlatformAdapters", () => {
   it("keeps official adapters in catalog order", () => {
@@ -27,3 +27,26 @@ describe("listCliPlatformAdapters", () => {
     expect(slugs).not.toContain("lark");
   });
 });
+
+describe("listCliStateAdapters", () => {
+  it("returns only state adapters", () => {
+    expect(
+      listCliStateAdapters().every((adapter) => adapter.type === "state")
+    ).toBe(true);
+  });
+
+  it("includes state adapters the scaffold can host", () => {
+    const slugs = listCliStateAdapters().map((adapter) => adapter.slug);
+    expect(slugs).toContain("memory");
+    expect(slugs).toContain("redis");
+  });
+
+  it("omits state adapters the webhook-only scaffold cannot host", () => {
+    const catalogSlugs = listStateAdapters().map((adapter) => adapter.slug);
+    const cliSlugs = listCliStateAdapters().map((adapter) => adapter.slug);
+    // Cloudflare Agents ships in the catalog but runs inside a Worker, so it is
+    // hidden from the CLI even though it is a catalog state adapter.
+    expect(catalogSlugs).toContain("cloudflare-agents");
+    expect(cliSlugs).not.toContain("cloudflare-agents");
+  });
+});

packages/create-chat-sdk/src/catalog/display.ts

@@ -1,5 +1,5 @@
 import type { CatalogAdapter } from "chat/adapters";
-import { listPlatformAdapters } from "chat/adapters";
+import { listPlatformAdapters, listStateAdapters } from "chat/adapters";
 import { isCliCompatibleAdapter } from "./compatibility.js";
 
 type PlatformAdapterGroup = CatalogAdapter["group"];
@@ -31,3 +31,18 @@ export function listCliPlatformAdapters(
 
   return adapters;
 }
+
+/**
+ * List state adapters the CLI can scaffold.
+ *
+ * Filters out catalog state adapters the generated Next.js runtime cannot host
+ * (for example, Cloudflare Agents, which runs inside a Worker with Durable
+ * Objects) so they never appear in the interactive state picker.
+ *
+ * @returns Scaffoldable state adapters in catalog order.
+ */
+export function listCliStateAdapters(): CatalogAdapter[] {
+  return listStateAdapters().filter((adapter) =>
+    isCliCompatibleAdapter(adapter.slug)
+  );
+}

packages/create-chat-sdk/src/catalog/index.ts

@@ -1,4 +1,4 @@
-export { listCliPlatformAdapters } from "./display.js";
+export { listCliPlatformAdapters, listCliStateAdapters } from "./display.js";
 export {
   type AdapterConnectSpec,
   CONNECT_CHAT_IMPORT,

packages/create-chat-sdk/src/catalog/scaffold-spec.ts

@@ -130,6 +130,11 @@ export const CLI_SCAFFOLD_SPEC = {
   agentphone: {
     invocation: { kind: "empty-object" },
   },
+  // Catalog-only: hidden from the CLI via CLI_INCOMPATIBLE_ADAPTERS. Runs inside
+  // a Cloudflare Worker, so it is never scaffolded by create-chat-sdk.
+  "cloudflare-agents": {
+    invocation: { kind: "zero-arg" },
+  },
   discord: {
     invocation: { kind: "zero-arg" },
     serverExternalPackages: [