diff --git a/.changeset/middleware-capabilities.md b/.changeset/middleware-capabilities.md
new file mode 100644
index 000000000..987db886e
--- /dev/null
+++ b/.changeset/middleware-capabilities.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai': minor
+---
+
+Add a type-safe capability system to chat middleware. `createCapability<T>()('name')` returns a `[get, provide]` accessor tuple that is also its own identity for `requires`/`provides` declarations — no separate token import. The middleware context also exposes `ctx.get(capability)` / `ctx.getOptional(capability)` / `ctx.provide(capability, value)`, typed by the handle you pass. Middleware gain a `setup` provisioning hook (runs first, before `onConfig`) plus `requires`/`provides`/`optionalRequires`. `chat()` validates that every required capability is provided, at compile time (an array coverage check and the new order-aware `createChatMiddleware()` builder) and at runtime (clear errors before the adapter runs). Adapters can now declare `requires`. This is the primitive layer for upcoming persistence and sandbox middleware; no concrete capabilities ship yet.
diff --git a/docs/advanced/middleware.md b/docs/advanced/middleware.md
index 6dc399d0f..fab12f6e6 100644
--- a/docs/advanced/middleware.md
+++ b/docs/advanced/middleware.md
@@ -43,7 +43,7 @@ const logger: ChatMiddleware = {
 };
 
 const stream = chat({
-  adapter: openaiText("gpt-4o"),
+  adapter: openaiText("gpt-5.5"),
   messages: [{ role: "user", content: "Hello" }],
   middleware: [logger],
 });
@@ -548,7 +548,7 @@ Middleware execute in array order. The ordering matters for hooks that pipe or s
 
 ```typescript
 const stream = chat({
-  adapter: openaiText("gpt-4o"),
+  adapter: openaiText("gpt-5.5"),
   messages,
   middleware: [authMiddleware, loggingMiddleware, cachingMiddleware],
 });
@@ -567,6 +567,132 @@ const stream = chat({
 | `onUsage` | Sequential | All run in order |
 | `onFinish/onAbort/onError` | Sequential | All run in order |
 
+## Capabilities
+
+Middleware often need to **share state**. A provider middleware sets something up (a database handle, a per-request counter, a sandbox), and a consumer middleware reads it back later in the same run. Capabilities make that hand-off **type-safe and order-checked**: the consumer declares what it needs, the provider declares what it offers, and `chat()` refuses to run (at compile time _and_ at runtime) if a required capability was never provided.
+
+### Creating a capability
+
+A capability is created with `createCapability<TValue>()('name')` — a **curried** call:
+
+```typescript
+import { createCapability } from "@tanstack/ai";
+
+const counterCapability = createCapability<{ value: number }>()("counter");
+const [getCounter, provideCounter] = counterCapability;
+```
+
+The currying is deliberate: you supply the **value type** explicitly (`<{ value: number }>`) while the **name literal** is inferred from the argument (`"counter"`). A single `createCapability<T>('name')` call can't do both — supplying `T` explicitly stops TypeScript inferring the name, collapsing it to `string` and defeating the compile-time coverage check that keys on the literal name.
+
+The returned `counterCapability` is a hybrid value:
+
+- It **destructures to `[get, provide]`** — the two accessors you use inside hooks.
+- It **is itself the identity** you list in `requires` / `provides`. There is no separate token to import.
+
+The accessors:
+
+| Accessor | Behavior |
+|----------|----------|
+| `getCounter(ctx)` | Returns the value. **Throws** if the capability was never provided. |
+| `getCounter(ctx, { optional: true })` | Returns `TValue \| undefined` — no throw when absent. |
+| `provideCounter(ctx, value)` | Sets the value for this run. Call it from `setup`. |
+
+Equivalently, the context exposes `ctx.get(capability)`, `ctx.getOptional(capability)`, and `ctx.provide(capability, value)` — pass the capability handle directly. These are typed by the handle you pass (`ctx.get(counterCapability)` returns the value type), so `getCounter(ctx)` and `ctx.get(counterCapability)` are interchangeable — use whichever reads better in your hook.
+
+> **Capability names must be unique across your app.** The compile-time coverage check keys on the name literal (runtime keys on the handle reference), so two capabilities sharing a name will conflate in the type-level check.
+
+### The `setup` hook
+
+Provisioning happens in a dedicated `setup(ctx)` hook. It **runs first** — before any `onConfig` (init), across all middleware in array order — so that by the time the rest of the lifecycle begins, every capability is in place. `setup` receives the stable `ChatMiddlewareContext` (not the mutable config), and may be async.
+
+### `requires` / `provides` / `optionalRequires`
+
+Three array fields on a middleware declare its capability contract. Each is a `ReadonlyArray<CapabilityHandle>` — you list the capability handles themselves:
+
+| Field | Meaning |
+|-------|---------|
+| `provides` | Capabilities this middleware sets up. Each one **must** be `provide`d inside `setup`, or `chat()` throws after the setup phase. |
+| `requires` | Capabilities this middleware reads. `chat()` validates (compile time + runtime) that some earlier middleware provides each one. |
+| `optionalRequires` | Capabilities used **if present** but not required. Non-gating — never causes a validation error. Read with `getX(ctx, { optional: true })`. |
+
+### Array example
+
+Author middleware with `defineChatMiddleware` — it sharpens the `requires` / `provides` tuple types so the coverage check and builder can read them precisely. Here a **provider** sets up a counter in `setup`, and a **consumer** reads it in a hook:
+
+```typescript
+import {
+  chat,
+  createCapability,
+  defineChatMiddleware,
+} from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const counterCapability = createCapability<{ value: number }>()("counter");
+const [getCounter, provideCounter] = counterCapability;
+
+// Provider: declares `provides` and provisions the value in `setup`.
+const withCounter = defineChatMiddleware({
+  name: "with-counter",
+  provides: [counterCapability],
+  setup(ctx) {
+    provideCounter(ctx, { value: 0 });
+  },
+});
+
+// Consumer: declares `requires` and reads the value via `get` in a hook.
+const countsChunks = defineChatMiddleware({
+  name: "counts-chunks",
+  requires: [counterCapability],
+  onChunk(ctx) {
+    getCounter(ctx).value++;
+  },
+  onFinish(ctx) {
+    console.log(`Saw ${getCounter(ctx).value} chunks`);
+  },
+});
+
+const stream = chat({
+  adapter: openaiText("gpt-5.5"),
+  messages: [{ role: "user", content: "Hello" }],
+  // Provider must come before the consumer.
+  middleware: [withCounter, countsChunks],
+});
+```
+
+If you drop `withCounter` from the array, `chat()` reports a compile-time error at the `middleware` option naming the missing `"counter"` capability — and throws at runtime before the adapter is ever called.
+
+### Builder example
+
+`createChatMiddleware()` builds the array through chained `.use()` calls and enforces **provider-before-consumer ordering at compile time**: each `.use()` requires that the middleware's `requires` are already covered by capabilities provided by earlier `.use()` calls.
+
+```typescript
+import { chat, createChatMiddleware } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
+
+const middleware = createChatMiddleware()
+  .use(withCounter) // provides "counter"
+  .use(countsChunks) // requires "counter" — OK, already provided above
+  .build();
+
+const stream = chat({
+  adapter: openaiText("gpt-5.5"),
+  messages: [{ role: "user", content: "Hello" }],
+  middleware,
+});
+```
+
+Swap the two `.use()` calls (`.use(countsChunks).use(withCounter)`) and the builder rejects it at the `.use(countsChunks)` line — the consumer is ordered before its provider, so `"counter"` isn't in the provided set yet.
+
+### Validation guarantees
+
+The capability system fails loudly and early:
+
+- **Compile-time coverage.** A required capability that nothing provides surfaces as a type error at the `middleware` option. This is enforced two ways: an **array coverage check** on `middleware: [...]`, and the order-aware **`createChatMiddleware()` builder** (which additionally enforces ordering).
+- **Runtime coverage.** Even if types are bypassed, `chat()` validates coverage and **throws before the adapter runs** if a required capability is missing.
+- **Post-`setup` assertion.** If a middleware declares a capability in `provides` but never calls its `provide` accessor during `setup`, `chat()` throws after the setup phase — you can't silently forget to provision.
+- **Duplicate provide → last-wins + warning.** If two middleware provide the same capability, the last write wins and a development warning is emitted.
+- **Unique names.** Capability `name`s must be unique across your app; the compile-time coverage check keys on the name literal (runtime keys on the handle reference).
+
 ## Built-in Middleware
 
 TanStack AI ships ready-made middleware for common cases — caching tool results, redacting streamed text, and OpenTelemetry tracing:
diff --git a/docs/config.json b/docs/config.json
index e3fc3b712..8bffca9c5 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -270,7 +270,8 @@
         {
           "label": "Middleware",
           "to": "advanced/middleware",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-06-15"
         },
         {
           "label": "Built-in Middleware",
diff --git a/examples/ts-react-chat/src/components/Header.tsx b/examples/ts-react-chat/src/components/Header.tsx
index 0e581b321..0a0424ec8 100644
--- a/examples/ts-react-chat/src/components/Header.tsx
+++ b/examples/ts-react-chat/src/components/Header.tsx
@@ -16,6 +16,7 @@ import {
   Music,
   Plug,
   Server,
+  Sparkles,
   Video,
   X,
 } from 'lucide-react'
@@ -280,6 +281,19 @@ export default function Header() {
             <Plug size={20} />
             <span className="font-medium">MCP Servers</span>
           </Link>
+
+          <Link
+            to="/capability-demo"
+            onClick={() => setIsOpen(false)}
+            className="flex items-center gap-3 p-3 rounded-lg hover:bg-gray-800 transition-colors mb-2"
+            activeProps={{
+              className:
+                'flex items-center gap-3 p-3 rounded-lg bg-cyan-600 hover:bg-cyan-700 transition-colors mb-2',
+            }}
+          >
+            <Sparkles size={20} />
+            <span className="font-medium">Capability Middleware</span>
+          </Link>
         </nav>
       </aside>
     </>
diff --git a/examples/ts-react-chat/src/routeTree.gen.ts b/examples/ts-react-chat/src/routeTree.gen.ts
index 83da3a117..d51c54cf6 100644
--- a/examples/ts-react-chat/src/routeTree.gen.ts
+++ b/examples/ts-react-chat/src/routeTree.gen.ts
@@ -17,6 +17,7 @@ import { Route as Issue176ToolResultRouteImport } from './routes/issue-176-tool-
 import { Route as ImageToolReproRouteImport } from './routes/image-tool-repro'
 import { Route as ImageGenRouteImport } from './routes/image-gen'
 import { Route as GenerationHooksRouteImport } from './routes/generation-hooks'
+import { Route as CapabilityDemoRouteImport } from './routes/capability-demo'
 import { Route as IndexRouteImport } from './routes/index'
 import { Route as GenerationsVideoRouteImport } from './routes/generations.video'
 import { Route as GenerationsTranscriptionRouteImport } from './routes/generations.transcription'
@@ -38,6 +39,7 @@ import { Route as ApiMcpManualRouteImport } from './routes/api.mcp-manual'
 import { Route as ApiMcpChatRouteImport } from './routes/api.mcp-chat'
 import { Route as ApiImageToolReproRouteImport } from './routes/api.image-tool-repro'
 import { Route as ApiImageGenRouteImport } from './routes/api.image-gen'
+import { Route as ApiCapabilityDemoRouteImport } from './routes/api.capability-demo'
 import { Route as ExampleGuitarsIndexRouteImport } from './routes/example.guitars/index'
 import { Route as ExampleGuitarsGuitarIdRouteImport } from './routes/example.guitars/$guitarId'
 import { Route as ApiGenerateVideoRouteImport } from './routes/api.generate.video'
@@ -85,6 +87,11 @@ const GenerationHooksRoute = GenerationHooksRouteImport.update({
   path: '/generation-hooks',
   getParentRoute: () => rootRouteImport,
 } as any)
+const CapabilityDemoRoute = CapabilityDemoRouteImport.update({
+  id: '/capability-demo',
+  path: '/capability-demo',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const IndexRoute = IndexRouteImport.update({
   id: '/',
   path: '/',
@@ -193,6 +200,11 @@ const ApiImageGenRoute = ApiImageGenRouteImport.update({
   path: '/api/image-gen',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiCapabilityDemoRoute = ApiCapabilityDemoRouteImport.update({
+  id: '/api/capability-demo',
+  path: '/api/capability-demo',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ExampleGuitarsIndexRoute = ExampleGuitarsIndexRouteImport.update({
   id: '/example/guitars/',
   path: '/example/guitars/',
@@ -226,6 +238,7 @@ const ApiGenerateAudioRoute = ApiGenerateAudioRouteImport.update({
 
 export interface FileRoutesByFullPath {
   '/': typeof IndexRoute
+  '/capability-demo': typeof CapabilityDemoRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
@@ -234,6 +247,7 @@ export interface FileRoutesByFullPath {
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
+  '/api/capability-demo': typeof ApiCapabilityDemoRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
   '/api/mcp-chat': typeof ApiMcpChatRoute
@@ -263,6 +277,7 @@ export interface FileRoutesByFullPath {
 }
 export interface FileRoutesByTo {
   '/': typeof IndexRoute
+  '/capability-demo': typeof CapabilityDemoRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
@@ -271,6 +286,7 @@ export interface FileRoutesByTo {
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
+  '/api/capability-demo': typeof ApiCapabilityDemoRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
   '/api/mcp-chat': typeof ApiMcpChatRoute
@@ -301,6 +317,7 @@ export interface FileRoutesByTo {
 export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/': typeof IndexRoute
+  '/capability-demo': typeof CapabilityDemoRoute
   '/generation-hooks': typeof GenerationHooksRoute
   '/image-gen': typeof ImageGenRoute
   '/image-tool-repro': typeof ImageToolReproRoute
@@ -309,6 +326,7 @@ export interface FileRoutesById {
   '/realtime': typeof RealtimeRoute
   '/server-fn-chat': typeof ServerFnChatRoute
   '/threads': typeof ThreadsRoute
+  '/api/capability-demo': typeof ApiCapabilityDemoRoute
   '/api/image-gen': typeof ApiImageGenRoute
   '/api/image-tool-repro': typeof ApiImageToolReproRoute
   '/api/mcp-chat': typeof ApiMcpChatRoute
@@ -340,6 +358,7 @@ export interface FileRouteTypes {
   fileRoutesByFullPath: FileRoutesByFullPath
   fullPaths:
     | '/'
+    | '/capability-demo'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
@@ -348,6 +367,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
+    | '/api/capability-demo'
     | '/api/image-gen'
     | '/api/image-tool-repro'
     | '/api/mcp-chat'
@@ -377,6 +397,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/'
+    | '/capability-demo'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
@@ -385,6 +406,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
+    | '/api/capability-demo'
     | '/api/image-gen'
     | '/api/image-tool-repro'
     | '/api/mcp-chat'
@@ -414,6 +436,7 @@ export interface FileRouteTypes {
   id:
     | '__root__'
     | '/'
+    | '/capability-demo'
     | '/generation-hooks'
     | '/image-gen'
     | '/image-tool-repro'
@@ -422,6 +445,7 @@ export interface FileRouteTypes {
     | '/realtime'
     | '/server-fn-chat'
     | '/threads'
+    | '/api/capability-demo'
     | '/api/image-gen'
     | '/api/image-tool-repro'
     | '/api/mcp-chat'
@@ -452,6 +476,7 @@ export interface FileRouteTypes {
 }
 export interface RootRouteChildren {
   IndexRoute: typeof IndexRoute
+  CapabilityDemoRoute: typeof CapabilityDemoRoute
   GenerationHooksRoute: typeof GenerationHooksRoute
   ImageGenRoute: typeof ImageGenRoute
   ImageToolReproRoute: typeof ImageToolReproRoute
@@ -460,6 +485,7 @@ export interface RootRouteChildren {
   RealtimeRoute: typeof RealtimeRoute
   ServerFnChatRoute: typeof ServerFnChatRoute
   ThreadsRoute: typeof ThreadsRoute
+  ApiCapabilityDemoRoute: typeof ApiCapabilityDemoRoute
   ApiImageGenRoute: typeof ApiImageGenRoute
   ApiImageToolReproRoute: typeof ApiImageToolReproRoute
   ApiMcpChatRoute: typeof ApiMcpChatRoute
@@ -546,6 +572,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof GenerationHooksRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/capability-demo': {
+      id: '/capability-demo'
+      path: '/capability-demo'
+      fullPath: '/capability-demo'
+      preLoaderRoute: typeof CapabilityDemoRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/': {
       id: '/'
       path: '/'
@@ -693,6 +726,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiImageGenRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/capability-demo': {
+      id: '/api/capability-demo'
+      path: '/api/capability-demo'
+      fullPath: '/api/capability-demo'
+      preLoaderRoute: typeof ApiCapabilityDemoRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/example/guitars/': {
       id: '/example/guitars/'
       path: '/example/guitars'
@@ -740,6 +780,7 @@ declare module '@tanstack/react-router' {
 
 const rootRouteChildren: RootRouteChildren = {
   IndexRoute: IndexRoute,
+  CapabilityDemoRoute: CapabilityDemoRoute,
   GenerationHooksRoute: GenerationHooksRoute,
   ImageGenRoute: ImageGenRoute,
   ImageToolReproRoute: ImageToolReproRoute,
@@ -748,6 +789,7 @@ const rootRouteChildren: RootRouteChildren = {
   RealtimeRoute: RealtimeRoute,
   ServerFnChatRoute: ServerFnChatRoute,
   ThreadsRoute: ThreadsRoute,
+  ApiCapabilityDemoRoute: ApiCapabilityDemoRoute,
   ApiImageGenRoute: ApiImageGenRoute,
   ApiImageToolReproRoute: ApiImageToolReproRoute,
   ApiMcpChatRoute: ApiMcpChatRoute,
diff --git a/examples/ts-react-chat/src/routes/api.capability-demo.ts b/examples/ts-react-chat/src/routes/api.capability-demo.ts
new file mode 100644
index 000000000..ad7e0646c
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/api.capability-demo.ts
@@ -0,0 +1,151 @@
+import { createFileRoute } from '@tanstack/react-router'
+import {
+  EventType,
+  chat,
+  chatParamsFromRequestBody,
+  createCapability,
+  createChatMiddleware,
+  createChatOptions,
+  defineChatMiddleware,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import type { ChatMiddleware, StreamChunk } from '@tanstack/ai'
+
+/**
+ * Capability middleware demo.
+ *
+ * Shows the new capability primitives end-to-end:
+ *  - `createCapability<T>()('name')` returns a `[get, provide]` tuple that is
+ *    also its own identity for `requires`/`provides`.
+ *  - a PROVIDER middleware supplies the value in `setup` (runs first),
+ *  - a CONSUMER middleware reads it in `onConfig` and injects a system prompt,
+ *  - `chat()` validates coverage. With the provider present we wire the
+ *    middleware through the type-safe `createChatMiddleware().use().build()`
+ *    builder (compile-time order check). With it absent we pass a plain
+ *    middleware array, so `chat()` throws the runtime validation error.
+ */
+
+// The capability: a "persona" string the assistant should adopt. The value
+// type is explicit; the name literal is inferred from the argument.
+const personaCapability = createCapability<string>()('demo-persona')
+const [getPersona, providePersona] = personaCapability
+
+function readForwardedString(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.trim() ? value : fallback
+}
+
+export const Route = createFileRoute('/api/capability-demo')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const abortController = new AbortController()
+
+        let params
+        try {
+          params = await chatParamsFromRequestBody(await request.json())
+        } catch (error) {
+          return new Response(
+            error instanceof Error ? error.message : 'Bad request',
+            { status: 400 },
+          )
+        }
+
+        const persona = readForwardedString(
+          params.forwardedProps.capabilityValue,
+          'a cheerful pirate captain',
+        )
+        // When false, the provider middleware is omitted so the consumer's
+        // `requires: [personaCapability]` is unmet — demonstrating the runtime
+        // validation error.
+        const provideCapability =
+          params.forwardedProps.provideCapability !== false
+
+        // PROVIDER — supplies the persona capability in `setup` (runs first,
+        // before `onConfig`, so later middleware can consume it).
+        const personaProvider = defineChatMiddleware({
+          name: 'persona-provider',
+          provides: [personaCapability],
+          setup(ctx) {
+            providePersona(ctx, persona)
+          },
+        })
+
+        // CONSUMER — reads the persona in `onConfig` and injects a system
+        // prompt. `getPersona(ctx)` is typed `string` (throws if unprovided).
+        const personaConsumer = defineChatMiddleware({
+          name: 'persona-consumer',
+          requires: [personaCapability],
+          onConfig(ctx, config) {
+            const activePersona = getPersona(ctx)
+            return {
+              systemPrompts: [
+                ...config.systemPrompts,
+                `You are ${activePersona}. Stay fully in character for the entire reply, and open by introducing yourself in that persona.`,
+              ],
+            }
+          },
+        })
+
+        try {
+          const options = createChatOptions({
+            adapter: openaiText('gpt-5.5'),
+          })
+
+          if (provideCapability) {
+            // Happy path: the order-aware builder enforces provider-before-
+            // consumer at COMPILE time and accumulates the provided set.
+            const stream = chat({
+              ...options,
+              middleware: createChatMiddleware()
+                .use(personaProvider)
+                .use(personaConsumer)
+                .use({
+                  name: 'logging-middleware',
+                  onConfig(_ctx, config) {
+                    console.log('onConfig', { config })
+                    return config
+                  },
+                })
+                .build(),
+              messages: params.messages,
+              threadId: params.threadId,
+              runId: params.runId,
+              abortController,
+            })
+            return toServerSentEventsResponse(stream, { abortController })
+          }
+
+          // Omit path: a plain `ChatMiddleware[]` (widened, so the compile-time
+          // coverage check can't prove the gap) — the unmet `requires` is caught
+          // by `chat()`'s RUNTIME validation, which throws and is surfaced below.
+          const middleware: Array<ChatMiddleware> = [personaConsumer]
+          const stream = chat({
+            ...options,
+            middleware,
+            messages: params.messages,
+            threadId: params.threadId,
+            runId: params.runId,
+            abortController,
+          })
+          return toServerSentEventsResponse(stream, { abortController })
+        } catch (error) {
+          // Surface the message (capability validation error when the provider
+          // is omitted, or a missing-API-key error) as an SSE RUN_ERROR so the
+          // client shows the real text instead of a generic "HTTP 500".
+          const message =
+            error instanceof Error ? error.message : 'An error occurred'
+          const errorStream = (async function* (): AsyncGenerator<StreamChunk> {
+            yield {
+              type: EventType.RUN_ERROR,
+              message,
+              timestamp: Date.now(),
+              error: { message },
+            }
+          })()
+          return toServerSentEventsResponse(errorStream, { abortController })
+        }
+      },
+    },
+  },
+})
diff --git a/examples/ts-react-chat/src/routes/capability-demo.tsx b/examples/ts-react-chat/src/routes/capability-demo.tsx
new file mode 100644
index 000000000..7625084e6
--- /dev/null
+++ b/examples/ts-react-chat/src/routes/capability-demo.tsx
@@ -0,0 +1,228 @@
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { Send, Sparkles, Square } from 'lucide-react'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+import type { UIMessage } from '@tanstack/ai-react'
+
+interface SessionConfig {
+  persona: string
+  provideCapability: boolean
+  /** Bumped on every Apply so the chat surface remounts with a fresh session. */
+  seq: number
+}
+
+function Messages({ messages }: { messages: Array<UIMessage> }) {
+  const visible = messages.filter((m) =>
+    m.parts.some((p) => p.type === 'text' && p.content.trim()),
+  )
+
+  if (!visible.length) {
+    return (
+      <div className="flex-1 overflow-y-auto px-4 py-8">
+        <p className="text-center text-sm text-gray-400">
+          Send a message — the assistant should answer in the persona supplied
+          by the capability.
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex-1 overflow-y-auto px-4 py-4">
+      {visible.map((message) => (
+        <div
+          key={message.id}
+          className={`mb-2 rounded-lg p-4 ${
+            message.role === 'assistant'
+              ? 'bg-linear-to-r from-cyan-500/5 to-blue-600/5'
+              : 'bg-transparent'
+          }`}
+        >
+          <div className="flex items-start gap-4">
+            <div
+              className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-lg text-sm font-medium text-white ${
+                message.role === 'assistant'
+                  ? 'bg-linear-to-r from-cyan-500 to-blue-600'
+                  : 'bg-gray-700'
+              }`}
+            >
+              {message.role === 'assistant' ? 'AI' : 'U'}
+            </div>
+            <div className="min-w-0 flex-1">
+              {message.parts.map((part, index) =>
+                part.type === 'text' && part.content ? (
+                  <p
+                    key={`text-${index}`}
+                    className="whitespace-pre-wrap text-white"
+                  >
+                    {part.content}
+                  </p>
+                ) : null,
+              )}
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+function ChatSurface({ config }: { config: SessionConfig }) {
+  const { messages, sendMessage, isLoading, error, stop } = useChat({
+    threadId: `capability-demo-${config.seq}`,
+    connection: fetchServerSentEvents('/api/capability-demo'),
+    // Forwarded to the route as `forwardedProps`: the provider middleware
+    // provides `capabilityValue`; `provideCapability=false` omits the provider
+    // so chat() throws the capability validation error.
+    body: {
+      capabilityValue: config.persona,
+      provideCapability: config.provideCapability,
+    },
+  })
+
+  const [input, setInput] = useState('')
+
+  const handleSend = () => {
+    if (!input.trim()) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <Messages messages={messages} />
+
+      {error && (
+        <div className="mx-4 mt-2 rounded-lg border border-red-500/30 bg-red-500/10 p-3 text-sm text-red-400">
+          <span className="font-semibold">chat() error:</span> {error.message}
+        </div>
+      )}
+
+      <div className="border-t border-cyan-500/10 bg-gray-900/80 backdrop-blur-sm">
+        <div className="w-full space-y-2 px-4 py-3">
+          {isLoading && (
+            <div className="flex items-center justify-center">
+              <button
+                onClick={stop}
+                className="flex items-center gap-2 rounded-lg bg-red-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-red-700"
+              >
+                <Square className="h-4 w-4 fill-current" />
+                Stop
+              </button>
+            </div>
+          )}
+          <div className="relative flex items-end gap-2">
+            <textarea
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              placeholder="Say hello..."
+              className="w-full resize-none overflow-hidden rounded-lg border border-cyan-500/20 bg-gray-800/50 py-3 pl-4 pr-12 text-sm text-white placeholder-gray-400 shadow-lg focus:border-transparent focus:outline-none focus:ring-2 focus:ring-cyan-500/50"
+              rows={1}
+              style={{ minHeight: '44px', maxHeight: '200px' }}
+              disabled={isLoading}
+              onKeyDown={(e) => {
+                if (e.key === 'Enter' && !e.shiftKey && input.trim()) {
+                  e.preventDefault()
+                  handleSend()
+                }
+              }}
+            />
+            <button
+              onClick={handleSend}
+              disabled={!input.trim() || isLoading}
+              className="absolute right-2 top-1/2 -translate-y-1/2 p-2 text-cyan-500 transition-colors hover:text-cyan-400 disabled:text-gray-500 focus:outline-none"
+            >
+              <Send className="h-4 w-4" />
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function CapabilityDemoPage() {
+  const [draftPersona, setDraftPersona] = useState('a cheerful pirate captain')
+  const [draftProvide, setDraftProvide] = useState(true)
+  const [config, setConfig] = useState<SessionConfig>({
+    persona: 'a cheerful pirate captain',
+    provideCapability: true,
+    seq: 0,
+  })
+
+  const apply = () => {
+    setConfig((prev) => ({
+      persona: draftPersona,
+      provideCapability: draftProvide,
+      seq: prev.seq + 1,
+    }))
+  }
+
+  const dirty =
+    draftPersona !== config.persona || draftProvide !== config.provideCapability
+
+  return (
+    <div className="flex h-[calc(100vh-72px)] flex-col bg-gray-900">
+      <div className="shrink-0 border-b border-cyan-500/20 bg-gray-800 px-4 py-3">
+        <div className="mb-2 flex items-center gap-2">
+          <Sparkles className="h-4 w-4 text-cyan-400" />
+          <h2 className="text-sm font-semibold text-white">
+            Middleware Capabilities
+          </h2>
+        </div>
+        <p className="mb-3 text-xs text-gray-400">
+          A <span className="text-cyan-300">provider</span> middleware supplies
+          a persona capability in <code className="text-gray-300">setup()</code>
+          ; a <span className="text-cyan-300">consumer</span> middleware reads
+          it in <code className="text-gray-300">onConfig()</code> and injects a
+          system prompt. With the capability provided, the middleware is wired
+          through the type-safe{' '}
+          <code className="text-gray-300">
+            createChatMiddleware().use().build()
+          </code>{' '}
+          builder. Uncheck “Provide capability” to omit the provider and watch{' '}
+          <code className="text-gray-300">chat()</code> throw the runtime
+          validation error. Requires{' '}
+          <code className="text-gray-300">OPENAI_API_KEY</code>.
+        </p>
+
+        <div className="flex flex-wrap items-end gap-3">
+          <label className="flex flex-col gap-1">
+            <span className="text-xs uppercase tracking-wide text-gray-500">
+              Persona (capability value)
+            </span>
+            <input
+              type="text"
+              value={draftPersona}
+              onChange={(e) => setDraftPersona(e.target.value)}
+              className="w-72 rounded-lg border border-gray-600 bg-gray-700/50 px-3 py-2 text-sm text-white focus:border-cyan-500/50 focus:outline-none"
+            />
+          </label>
+
+          <label className="flex cursor-pointer items-center gap-2 rounded-lg border border-gray-600 bg-gray-700/50 px-3 py-2 text-sm text-gray-200">
+            <input
+              type="checkbox"
+              checked={draftProvide}
+              onChange={(e) => setDraftProvide(e.target.checked)}
+            />
+            <span>Provide capability</span>
+          </label>
+
+          <button
+            onClick={apply}
+            disabled={!dirty}
+            className="rounded-lg bg-cyan-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-cyan-700 disabled:bg-gray-600 disabled:text-gray-400"
+          >
+            {config.seq === 0 ? 'Start session' : 'Apply (new session)'}
+          </button>
+        </div>
+      </div>
+
+      <ChatSurface key={config.seq} config={config} />
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/capability-demo')({
+  component: CapabilityDemoPage,
+})
diff --git a/packages/ai/src/activities/chat/adapter.ts b/packages/ai/src/activities/chat/adapter.ts
index ee6010721..cb3bcae6d 100644
--- a/packages/ai/src/activities/chat/adapter.ts
+++ b/packages/ai/src/activities/chat/adapter.ts
@@ -6,6 +6,7 @@ import type {
   TextOptions,
   TokenUsage,
 } from '../../types'
+import type { CapabilityHandle } from './middleware/capabilities'
 
 /**
  * Configuration for adapter instances
@@ -79,6 +80,15 @@ export interface TextAdapter<
   /** The model this adapter is configured for */
   readonly model: TModel
 
+  /**
+   * Capabilities this adapter requires at runtime. `chat()` validates that the
+   * configured middleware provides each one. Model adapters omit this; harness
+   * adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.
+   * Runtime access to capabilities from inside the adapter is not yet wired —
+   * this is the declaration/validation surface only.
+   */
+  readonly requires?: ReadonlyArray<CapabilityHandle>
+
   /**
    * @internal Type-only properties for inference. Not assigned at runtime.
    */
@@ -183,6 +193,7 @@ export abstract class BaseTextAdapter<
   readonly kind = 'text' as const
   abstract readonly name: string
   readonly model: TModel
+  readonly requires?: ReadonlyArray<CapabilityHandle> = undefined
 
   // Type-only property - never assigned at runtime
   declare '~types': {
diff --git a/packages/ai/src/activities/chat/index.ts b/packages/ai/src/activities/chat/index.ts
index 71dfac206..9a71cb9cc 100644
--- a/packages/ai/src/activities/chat/index.ts
+++ b/packages/ai/src/activities/chat/index.ts
@@ -25,6 +25,8 @@ import {
 import { maxIterations as maxIterationsStrategy } from './agent-loop-strategies'
 import { convertMessagesToModelMessages, generateMessageId } from './messages'
 import { MiddlewareRunner } from './middleware/compose'
+import { CapabilityRegistry } from './middleware/capabilities'
+import { validateCapabilities } from './middleware/validate'
 import { MCPManager } from './mcp/manager'
 import type {
   ApprovalRequest,
@@ -54,11 +56,13 @@ import type {
   UIMessage,
 } from '../../types'
 import type {
+  AnyChatMiddleware,
   ChatMiddleware,
   ChatMiddlewareConfig,
   ChatMiddlewareContext,
   StructuredOutputMiddlewareConfig,
 } from './middleware/types'
+import type { CheckCoverage } from './middleware/builder'
 import type { SystemPrompt } from '../../system-prompts'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
@@ -141,7 +145,8 @@ type TextActivityOptionsWithContext<
   'tools' | 'middleware' | 'context'
 > & {
   tools?: TTools
-  middleware?: TMiddleware
+  middleware?: TMiddleware &
+    CheckCoverage<Extract<TMiddleware, ReadonlyArray<AnyChatMiddleware>>>
 } & RequiredContextFromInputs<TTools, TMiddleware>
 
 // ===========================
@@ -659,6 +664,15 @@ class TextEngine<
       // References
       messages: this.messages,
       createId: (prefix: string) => this.createId(prefix),
+      // Capability bookkeeping for this request (populated by middleware setup)
+      capabilities: new CapabilityRegistry(),
+      // Convenience accessors that delegate to a capability handle's own
+      // tuple getter/provider, keyed by this context. `getX(ctx)` and
+      // `ctx.get(X)` are interchangeable.
+      get: (capability) => capability[0](this.middlewareCtx),
+      getOptional: (capability) =>
+        capability[0](this.middlewareCtx, { optional: true }),
+      provide: (capability, value) => capability[1](this.middlewareCtx, value),
     }
   }
 
@@ -706,6 +720,9 @@ class TextEngine<
     })
 
     try {
+      // Provision capabilities before any consumer (onConfig onward) can read them
+      await this.middlewareRunner.runSetup(this.middlewareCtx)
+
       // Run initial onConfig (phase = init)
       this.middlewareCtx.phase = 'init'
       const initialConfig = this.buildMiddlewareConfig()
@@ -2564,6 +2581,8 @@ export function chat<
     TMiddleware
   >,
 ): TextActivityResult<TSchema, TStream> {
+  validateCapabilities(options.middleware ?? [], options.adapter)
+
   const { outputSchema, stream } = options
 
   // outputSchema + stream:true is the only branch that streams structured
diff --git a/packages/ai/src/activities/chat/middleware/builder.ts b/packages/ai/src/activities/chat/middleware/builder.ts
new file mode 100644
index 000000000..cced4bceb
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/builder.ts
@@ -0,0 +1,109 @@
+import type { CapabilityHandle } from './capabilities'
+import type { AnyChatMiddleware, ChatMiddleware } from './types'
+import type { DefinedChatMiddleware } from './define'
+
+/** Union of capability NAME literals from a tuple of handles. */
+export type NamesOf<T extends ReadonlyArray<CapabilityHandle>> =
+  T[number]['capabilityName']
+
+/** Names provided across a middleware array (imprecise middleware → `string`). */
+export type ProvidedNames<TList extends ReadonlyArray<AnyChatMiddleware>> =
+  NonNullable<TList[number]['provides']> extends infer P
+    ? P extends ReadonlyArray<CapabilityHandle>
+      ? NamesOf<P>
+      : never
+    : never
+
+/** Names required across a middleware array. */
+export type RequiredNames<TList extends ReadonlyArray<AnyChatMiddleware>> =
+  NonNullable<TList[number]['requires']> extends infer P
+    ? P extends ReadonlyArray<CapabilityHandle>
+      ? NamesOf<P>
+      : never
+    : never
+
+/**
+ * Branded marker surfaced when required capability names are missing from the
+ * provided set, so the compiler error names the gap instead of emitting an
+ * opaque "not assignable".
+ */
+export type MissingCapabilities<TMissing extends string> = {
+  // The human-readable message lives in the property KEY, so TypeScript's
+  // "Property '<key>' is missing in type ... but required in type ..." error
+  // prints the explanation instead of an opaque `__missingCapabilities`. The
+  // key distributes over a union of missing names (one required key each).
+  [K in `✖ Missing capability "${TMissing}": no configured middleware provides it. Add a middleware whose \`provides\` includes it (and, with createChatMiddleware().use(), order the provider before this consumer).`]: never
+}
+
+/**
+ * Missing capability names. When required names are imprecise (`string`, i.e.
+ * plain `ChatMiddleware` not authored via `defineChatMiddleware`), we cannot
+ * prove a gap, so we allow it (→ `never`). Otherwise the precise literals not
+ * present in the provided set.
+ */
+type MissingNames<TList extends ReadonlyArray<AnyChatMiddleware>> =
+  string extends RequiredNames<TList>
+    ? never
+    : Exclude<RequiredNames<TList>, ProvidedNames<TList>>
+
+/**
+ * Resolves to `TList` when coverage holds, otherwise to a `MissingCapabilities`
+ * marker (not assignable to a middleware array) — producing a compile error at
+ * the `middleware` option that names the missing capability.
+ */
+export type CheckCoverage<TList extends ReadonlyArray<AnyChatMiddleware>> = [
+  MissingNames<TList>,
+] extends [never]
+  ? TList
+  : MissingCapabilities<MissingNames<TList>>
+
+/**
+ * Order-aware middleware builder. Each `.use()` requires that the middleware's
+ * required capability names are already in the accumulated provided set, then
+ * adds its provided names. `.build()` returns the ordered array.
+ *
+ * `TProvided` is the running union of provided capability name literals.
+ */
+export interface ChatMiddlewareBuilder<
+  TList extends ReadonlyArray<AnyChatMiddleware>,
+  TProvided extends string,
+> {
+  use: <
+    TRequires extends ReadonlyArray<CapabilityHandle>,
+    TProvides extends ReadonlyArray<CapabilityHandle>,
+    TContext = unknown,
+  >(
+    middleware: [NamesOf<TRequires>] extends [TProvided]
+      ? DefinedChatMiddleware<TContext, TRequires, TProvides>
+      : DefinedChatMiddleware<TContext, TRequires, TProvides> &
+          MissingCapabilities<Exclude<NamesOf<TRequires>, TProvided>>,
+  ) => ChatMiddlewareBuilder<
+    readonly [...TList, DefinedChatMiddleware<TContext, TRequires, TProvides>],
+    TProvided | NamesOf<TProvides>
+  >
+
+  build: () => [...TList]
+}
+
+/** Create an order-aware middleware builder. */
+export function createChatMiddleware(): ChatMiddlewareBuilder<
+  readonly [],
+  never
+> {
+  const list: Array<ChatMiddleware<unknown>> = []
+  const builder = {
+    use(middleware: ChatMiddleware<unknown>) {
+      list.push(middleware)
+      return builder
+    },
+    build() {
+      return list
+    },
+  }
+  // The only sanctioned assertion in this PR: the runtime `builder` is a single
+  // object reused across `.use()` calls, but the type accumulates `TProvided`
+  // and `TList` per call — TypeScript cannot derive that from runtime values, so
+  // a structural `as` is impossible and the double assertion is irreducible.
+  // eslint-disable-next-line no-restricted-syntax -- irreducible: type-level accumulation cannot be expressed from a single runtime object
+  return builder as unknown as ChatMiddlewareBuilder<readonly [], never>
+}
diff --git a/packages/ai/src/activities/chat/middleware/capabilities.ts b/packages/ai/src/activities/chat/middleware/capabilities.ts
new file mode 100644
index 000000000..1d076be8d
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/capabilities.ts
@@ -0,0 +1,162 @@
+/** Options accepted by a capability getter. */
+export interface CapabilityGetOptions {
+  /** When true, return undefined instead of throwing if the capability is absent. */
+  optional?: boolean
+}
+
+/**
+ * The minimal context shape a capability accessor needs. The full
+ * `ChatMiddlewareContext` satisfies this (it has `capabilities`), so accessors
+ * accept any middleware context without referencing `any`.
+ */
+export interface CapabilityContext {
+  capabilities: CapabilityRegistry
+}
+
+/** Reads a capability value off a context. Overloaded so the flag narrows the return. */
+export interface CapabilityGetter<TValue> {
+  (ctx: CapabilityContext): TValue
+  (ctx: CapabilityContext, opts: { optional: true }): TValue | undefined
+}
+
+/** Writes a capability value onto a context. */
+export type CapabilityProvider<TValue> = (
+  ctx: CapabilityContext,
+  value: TValue,
+) => void
+
+/**
+ * A capability handle. It is BOTH a `[get, provide]` tuple (array-destructurable)
+ * AND the identity used in middleware `requires`/`provides` declarations.
+ *
+ * Runtime identity is this object's reference. The `capabilityName` literal is
+ * used for diagnostics and COMPILE-TIME tracking only — capability names MUST be
+ * unique across an app or the type-level coverage check conflates them.
+ */
+export type Capability<
+  TValue = unknown,
+  TName extends string = string,
+> = readonly [
+  get: CapabilityGetter<TValue>,
+  provide: CapabilityProvider<TValue>,
+] & {
+  readonly capabilityName: TName
+  /** @internal Presence check for the post-setup assertion. */
+  has: (ctx: CapabilityContext) => boolean
+}
+
+/**
+ * A capability handle with permissive value/name — for use as a constraint in
+ * `requires`/`provides` arrays. Concentrates `any` in one named alias (same
+ * convention as `AnyTextAdapter`/`AnyTool`); needed so `Capability<SpecificT>`
+ * is assignable to the handle-array element type.
+ */
+export type CapabilityHandle = Capability<any, string>
+
+/**
+ * Per-request bookkeeping: which capabilities were provided, plus the
+ * duplicate-provide notification. Capability VALUES live in per-capability
+ * WeakMaps (see `createCapability`), not here — this only tracks presence.
+ */
+export class CapabilityRegistry {
+  private readonly provided = new Set<CapabilityHandle>()
+  private onDuplicate?: (name: string) => void
+
+  /** Register a callback fired when a handle is provided more than once. */
+  setOnDuplicate(cb: (name: string) => void): void {
+    this.onDuplicate = cb
+  }
+
+  /** Record that `handle` was provided; fire the duplicate callback on repeats. */
+  markProvided(handle: CapabilityHandle): void {
+    if (this.provided.has(handle)) this.onDuplicate?.(handle.capabilityName)
+    this.provided.add(handle)
+  }
+
+  has(handle: CapabilityHandle): boolean {
+    return this.provided.has(handle)
+  }
+}
+
+/**
+ * Create a capability. Returns a hybrid handle that destructures to
+ * `[get, provide]` and is itself the identity for `requires`/`provides`.
+ *
+ * Curried so the value type is supplied explicitly while the name literal is
+ * INFERRED from the argument: `createCapability<T>()('name')`. (A single call
+ * `createCapability<T>('name')` cannot work — supplying `T` explicitly stops
+ * TypeScript inferring the name, collapsing it to `string` and defeating the
+ * compile-time coverage check that keys on the literal name.)
+ *
+ * @example Provider + consumer middleware
+ * ```ts
+ * const counterCapability = createCapability<{ value: number }>()('counter')
+ * const [getCounter, provideCounter] = counterCapability
+ *
+ * const withCounter = defineChatMiddleware({
+ *   name: 'counter',
+ *   provides: [counterCapability],
+ *   setup(ctx) { provideCounter(ctx, { value: 0 }) },
+ * })
+ *
+ * const readsCounter = defineChatMiddleware({
+ *   name: 'reads-counter',
+ *   requires: [counterCapability],
+ *   onChunk(ctx) { getCounter(ctx).value++ },
+ * })
+ *
+ * chat({ adapter, messages, middleware: [withCounter, readsCounter] })
+ * ```
+ *
+ * @remarks Capability `name`s must be unique across your app: compile-time
+ * coverage tracking keys on the name literal (runtime keys on reference).
+ */
+export function createCapability<TValue = unknown>(): <
+  const TName extends string,
+>(
+  name: TName,
+) => Capability<TValue, TName> {
+  return <const TName extends string>(
+    name: TName,
+  ): Capability<TValue, TName> => {
+    // Each capability owns a typed WeakMap keyed by the context object. Because
+    // the value type is TValue, reads are typed with no assertion.
+    const values = new WeakMap<CapabilityContext, TValue>()
+
+    function get(ctx: CapabilityContext): TValue
+    function get(
+      ctx: CapabilityContext,
+      opts: { optional: true },
+    ): TValue | undefined
+    function get(
+      ctx: CapabilityContext,
+      opts?: CapabilityGetOptions,
+    ): TValue | undefined {
+      if (!values.has(ctx)) {
+        if (opts?.optional) return undefined
+        throw new Error(
+          `Capability "${name}" was requested but never provided. Ensure a ` +
+            `middleware provides it in setup(), ordered before this consumer.`,
+        )
+      }
+      return values.get(ctx)
+    }
+
+    const provide: CapabilityProvider<TValue> = (ctx, value) => {
+      values.set(ctx, value)
+      ctx.capabilities.markProvided(handle)
+    }
+
+    const pair: readonly [
+      CapabilityGetter<TValue>,
+      CapabilityProvider<TValue>,
+    ] = [get, provide]
+    // Object.assign's return type is the intersection of the tuple and the
+    // props, which IS Capability<TValue, TName> — no cast needed.
+    const handle = Object.assign(pair, {
+      capabilityName: name,
+      has: (ctx: CapabilityContext) => values.has(ctx),
+    })
+    return handle
+  }
+}
diff --git a/packages/ai/src/activities/chat/middleware/compose.ts b/packages/ai/src/activities/chat/middleware/compose.ts
index 638323fec..bab6a9a03 100644
--- a/packages/ai/src/activities/chat/middleware/compose.ts
+++ b/packages/ai/src/activities/chat/middleware/compose.ts
@@ -163,6 +163,57 @@ export class MiddlewareRunner<TContext = unknown> {
     return current
   }
 
+  /**
+   * Run all `setup` hooks in array order, then assert every declared `provides`
+   * capability was actually provided. Wires the last-wins duplicate-provide
+   * warning into the registry. Runs before init `onConfig`.
+   *
+   * Takes the full `ChatMiddlewareContext` — the same stable context the engine
+   * threads through every other hook — because it both forwards `ctx` to each
+   * `setup` hook and emits instrumentation events from it.
+   */
+  async runSetup(ctx: ChatMiddlewareContext<TContext>): Promise<void> {
+    ctx.capabilities.setOnDuplicate((name) => {
+      this.logger.warn(
+        `capability "${name}" was provided more than once; last provider wins`,
+        { capability: name },
+      )
+    })
+
+    for (const mw of this.middlewares) {
+      if (mw.setup) {
+        const skip = shouldSkipInstrumentation(mw)
+        const start = Date.now()
+        await mw.setup(ctx)
+        if (!skip) {
+          this.logger.middleware(
+            `hook=setup middleware=${mw.name ?? 'unnamed'}`,
+            { middleware: mw.name ?? 'unnamed', hook: 'setup' },
+          )
+          aiEventClient.emit('middleware:hook:executed', {
+            ...instrumentCtx(ctx),
+            middlewareName: mw.name || 'unnamed',
+            hookName: 'setup',
+            iteration: ctx.iteration,
+            duration: Date.now() - start,
+            hasTransform: false,
+          })
+        }
+      }
+    }
+
+    for (const mw of this.middlewares) {
+      for (const handle of mw.provides ?? []) {
+        if (!ctx.capabilities.has(handle)) {
+          throw new Error(
+            `Middleware "${mw.name ?? 'unnamed'}" declares it provides ` +
+              `"${handle.capabilityName}" but never called provide() in setup().`,
+          )
+        }
+      }
+    }
+  }
+
   /**
    * Call onStart on all middleware in order.
    */
diff --git a/packages/ai/src/activities/chat/middleware/define.ts b/packages/ai/src/activities/chat/middleware/define.ts
new file mode 100644
index 000000000..92234f1a2
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/define.ts
@@ -0,0 +1,34 @@
+import type { CapabilityHandle } from './capabilities'
+import type { ChatMiddleware } from './types'
+
+/**
+ * A middleware whose `requires`/`provides` tuple types are captured precisely
+ * (via `const` inference) for the array coverage check and the builder.
+ */
+export interface DefinedChatMiddleware<
+  TContext,
+  TRequires extends ReadonlyArray<CapabilityHandle>,
+  TProvides extends ReadonlyArray<CapabilityHandle>,
+> extends ChatMiddleware<TContext> {
+  requires?: TRequires
+  provides?: TProvides
+}
+
+/**
+ * Identity helper for authoring middleware with precise capability inference.
+ * Returns the middleware unchanged at runtime; only sharpens its type so the
+ * `chat()` array coverage check and `createChatMiddleware` builder can read the
+ * exact `requires`/`provides`.
+ */
+export function defineChatMiddleware<
+  TContext = unknown,
+  const TRequires extends ReadonlyArray<CapabilityHandle> = readonly [],
+  const TProvides extends ReadonlyArray<CapabilityHandle> = readonly [],
+>(
+  middleware: ChatMiddleware<TContext> & {
+    requires?: TRequires
+    provides?: TProvides
+  },
+): DefinedChatMiddleware<TContext, TRequires, TProvides> {
+  return middleware
+}
diff --git a/packages/ai/src/activities/chat/middleware/index.ts b/packages/ai/src/activities/chat/middleware/index.ts
index 1bbbd8c5f..98e2f02f9 100644
--- a/packages/ai/src/activities/chat/middleware/index.ts
+++ b/packages/ai/src/activities/chat/middleware/index.ts
@@ -16,3 +16,23 @@ export type {
 } from './types'
 
 export { MiddlewareRunner } from './compose'
+
+export { createCapability, CapabilityRegistry } from './capabilities'
+export type {
+  Capability,
+  CapabilityHandle,
+  CapabilityContext,
+  CapabilityGetter,
+  CapabilityProvider,
+  CapabilityGetOptions,
+} from './capabilities'
+export { defineChatMiddleware } from './define'
+export type { DefinedChatMiddleware } from './define'
+export { createChatMiddleware } from './builder'
+export type {
+  ChatMiddlewareBuilder,
+  MissingCapabilities,
+  NamesOf,
+} from './builder'
+export { validateCapabilities } from './validate'
+export type { AnyChatMiddleware } from './types'
diff --git a/packages/ai/src/activities/chat/middleware/types.ts b/packages/ai/src/activities/chat/middleware/types.ts
index a7143716f..f3b7d3ff8 100644
--- a/packages/ai/src/activities/chat/middleware/types.ts
+++ b/packages/ai/src/activities/chat/middleware/types.ts
@@ -7,6 +7,11 @@ import type {
   ToolCall,
 } from '../../../types'
 import type { SystemPrompt } from '../../../system-prompts'
+import type {
+  Capability,
+  CapabilityHandle,
+  CapabilityRegistry,
+} from './capabilities'
 
 // ===========================
 // Middleware Context
@@ -115,6 +120,28 @@ export interface ChatMiddlewareContext<TContext = unknown> {
   messages: ReadonlyArray<ModelMessage>
   /** Generate a unique ID with the given prefix */
   createId: (prefix: string) => string
+  /**
+   * Capability bookkeeping for this request. Populated by middleware `setup`
+   * hooks (via `provide` accessors) and read by later middleware (via `get`
+   * accessors). Prefer the accessors returned by `createCapability` over using
+   * this directly. Orthogonal to `context` (the user runtime context).
+   */
+  capabilities: CapabilityRegistry
+  /**
+   * Read a provided capability by its handle. Equivalent to the handle's own
+   * `get` accessor (`getX(ctx)`); throws if the capability was never provided.
+   */
+  get: <TValue>(capability: Capability<TValue>) => TValue
+  /**
+   * Read a capability by its handle, returning `undefined` if it was never
+   * provided (never throws).
+   */
+  getOptional: <TValue>(capability: Capability<TValue>) => TValue | undefined
+  /**
+   * Provide a capability value. Equivalent to the handle's own `provide`
+   * accessor (`provideX(ctx, value)`). Typically called from `setup`.
+   */
+  provide: <TValue>(capability: Capability<TValue>, value: TValue) => void
 }
 
 // ===========================
@@ -344,6 +371,36 @@ export interface ChatMiddleware<TContext = unknown> {
   /** Optional name for debugging and identification */
   name?: string
 
+  /**
+   * Capabilities this middleware requires. `chat()` validates that some
+   * middleware (or the adapter) provides each one; unsatisfied requirements are
+   * a compile-time error (array coverage / builder) and a runtime error before
+   * the adapter runs.
+   */
+  requires?: ReadonlyArray<CapabilityHandle>
+
+  /**
+   * Capabilities this middleware provides. Each declared capability MUST be
+   * provided (via its `provide` accessor) inside `setup`, or `chat()` throws
+   * after the setup phase.
+   */
+  provides?: ReadonlyArray<CapabilityHandle>
+
+  /**
+   * Capabilities this middleware uses if present but does not require.
+   * Non-gating: never causes a validation error. Read with
+   * `getX(ctx, { optional: true })`.
+   */
+  optionalRequires?: ReadonlyArray<CapabilityHandle>
+
+  /**
+   * Provisioning hook. Runs FIRST — before `onConfig` (init) — across all
+   * middleware in array order. Use it to call `provide` accessors so later
+   * middleware (`onConfig` onward) can consume the capabilities. Receives the
+   * stable context; does NOT receive the mutable config.
+   */
+  setup?: (ctx: ChatMiddlewareContext<TContext>) => void | Promise<void>
+
   /**
    * Called to observe or transform the chat configuration.
    * Called at init and at the beginning of each agent iteration.
@@ -476,3 +533,6 @@ export interface ChatMiddleware<TContext = unknown> {
     info: ErrorInfo,
   ) => void | Promise<void>
 }
+
+/** A `ChatMiddleware` with a permissive context — for use as a constraint. */
+export type AnyChatMiddleware = ChatMiddleware<any>
diff --git a/packages/ai/src/activities/chat/middleware/validate.ts b/packages/ai/src/activities/chat/middleware/validate.ts
new file mode 100644
index 000000000..a6c66e7be
--- /dev/null
+++ b/packages/ai/src/activities/chat/middleware/validate.ts
@@ -0,0 +1,55 @@
+import type { CapabilityHandle } from './capabilities'
+import type { AnyChatMiddleware } from './types'
+
+/** Minimal adapter shape needed for capability validation. */
+interface CapabilityRequiringAdapter {
+  name: string
+  requires?: ReadonlyArray<CapabilityHandle>
+}
+
+/**
+ * Runtime validation: every required capability (from middleware `requires` and
+ * the adapter's `requires`) must be provided by some middleware's `provides`.
+ * `optionalRequires` is never gating. Throws a clear error otherwise.
+ *
+ * Presence only — ORDER is not validated here (a provider may appear after its
+ * consumer in the array and still pass). Use the `createChatMiddleware()`
+ * builder for compile-time order enforcement; at runtime, a consumer that reads
+ * a not-yet-provided capability during `setup` fails loud via its getter.
+ */
+export function validateCapabilities(
+  middlewares: ReadonlyArray<AnyChatMiddleware>,
+  adapter: CapabilityRequiringAdapter,
+): void {
+  const provided = new Set<CapabilityHandle>()
+  for (const mw of middlewares) {
+    for (const handle of mw.provides ?? []) provided.add(handle)
+  }
+
+  const providedNames = (): string => {
+    const names = [...provided].map((h) => h.capabilityName)
+    return names.length ? names.join(', ') : 'none'
+  }
+
+  for (const handle of adapter.requires ?? []) {
+    if (!provided.has(handle)) {
+      throw new Error(
+        `Adapter "${adapter.name}" requires capability "${handle.capabilityName}". ` +
+          `Provided capabilities: ${providedNames()}. ` +
+          `Add a middleware that provides "${handle.capabilityName}".`,
+      )
+    }
+  }
+
+  for (const mw of middlewares) {
+    for (const handle of mw.requires ?? []) {
+      if (!provided.has(handle)) {
+        throw new Error(
+          `Middleware "${mw.name ?? 'unnamed'}" requires capability ` +
+            `"${handle.capabilityName}". Provided capabilities: ${providedNames()}. ` +
+            `Add a middleware that provides "${handle.capabilityName}".`,
+        )
+      }
+    }
+  }
+}
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index dbb38722b..f44d44b43 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -118,6 +118,20 @@ export type {
   ErrorInfo,
 } from './activities/chat/middleware/index'
 
+// Capability primitives + middleware builder
+export {
+  createCapability,
+  defineChatMiddleware,
+  createChatMiddleware,
+} from './activities/chat/middleware/index'
+export type {
+  Capability,
+  CapabilityHandle,
+  CapabilityContext,
+  CapabilityGetter,
+  CapabilityProvider,
+} from './activities/chat/middleware/index'
+
 // All types
 export * from './types'
 
diff --git a/packages/ai/tests/middleware-capabilities.test-d.ts b/packages/ai/tests/middleware-capabilities.test-d.ts
new file mode 100644
index 000000000..31760a366
--- /dev/null
+++ b/packages/ai/tests/middleware-capabilities.test-d.ts
@@ -0,0 +1,103 @@
+import { expectTypeOf } from 'vitest'
+import { chat } from '../src'
+import { createCapability } from '../src/activities/chat/middleware/capabilities'
+import { defineChatMiddleware } from '../src/activities/chat/middleware/define'
+import { createChatMiddleware } from '../src/activities/chat/middleware/builder'
+import type { AnyTextAdapter } from '../src/activities/chat/adapter'
+import type { ChatMiddlewareContext } from '../src/activities/chat/middleware/types'
+
+const aCap = createCapability<{ a: number }>()('a')
+const bCap = createCapability<{ b: string }>()('b')
+
+const mw = defineChatMiddleware({
+  name: 'demo',
+  provides: [aCap],
+  requires: [bCap],
+  setup(ctx) {
+    const [, provideA] = aCap
+    provideA(ctx, { a: 1 })
+  },
+})
+
+// `provides`/`requires` are optional members, so value access widens with
+// `| undefined`. The assertion still verifies the tuple is captured precisely
+// (not widened to `CapabilityHandle[]`).
+expectTypeOf(mw.provides).toEqualTypeOf<readonly [typeof aCap] | undefined>()
+expectTypeOf(mw.requires).toEqualTypeOf<readonly [typeof bCap] | undefined>()
+
+// ===========================
+// Task 8: compile-time capability coverage on the middleware array
+// ===========================
+
+// A typed adapter for type-level tests — no `any`, no cast. AnyTextAdapter is
+// the repo's existing permissive adapter alias.
+declare const mockAdapter: AnyTextAdapter
+
+// Curried form: value type explicit, name literal inferred from the argument.
+const sandboxCap = createCapability<number>()('sandbox-typecheck')
+const persistenceCap = createCapability<number>()('persistence-typecheck')
+
+const providesPersistence = defineChatMiddleware({
+  name: 'persistence',
+  provides: [persistenceCap],
+  setup: (ctx) => persistenceCap[1](ctx, 1),
+})
+const needsPersistence = defineChatMiddleware({
+  name: 'needs-persistence',
+  requires: [persistenceCap],
+})
+const needsSandbox = defineChatMiddleware({
+  name: 'needs-sandbox',
+  requires: [sandboxCap],
+})
+
+// OK: persistence required and provided within the array.
+chat({
+  adapter: mockAdapter,
+  messages: [],
+  middleware: [providesPersistence, needsPersistence],
+})
+
+// sandbox is required but never provided — coverage fails.
+chat({
+  adapter: mockAdapter,
+  messages: [],
+  // @ts-expect-error sandbox capability is required but never provided.
+  middleware: [providesPersistence, needsSandbox],
+})
+
+// ===========================
+// Task 9: order-aware createChatMiddleware builder
+// ===========================
+
+const builderCap = createCapability<number>()('builder-cap')
+const buProvides = defineChatMiddleware({
+  name: 'p',
+  provides: [builderCap],
+  setup: (ctx) => builderCap[1](ctx, 1),
+})
+const buConsumes = defineChatMiddleware({ name: 'c', requires: [builderCap] })
+
+// OK: provider used before consumer.
+const built = createChatMiddleware().use(buProvides).use(buConsumes).build()
+expectTypeOf(built).toMatchTypeOf<ReadonlyArray<unknown>>()
+
+// @ts-expect-error consumer used before its requirement is provided.
+createChatMiddleware().use(buConsumes)
+
+// The fully-built array satisfies chat()'s coverage check.
+chat({ adapter: mockAdapter, messages: [], middleware: built })
+
+// ===========================
+// ctx.get / ctx.getOptional are typed by the capability identity passed
+// ===========================
+declare const ctx: ChatMiddlewareContext
+
+// `persistenceCap` is Capability<number, ...> → get returns number.
+expectTypeOf(ctx.get(persistenceCap)).toEqualTypeOf<number>()
+expectTypeOf(ctx.getOptional(persistenceCap)).toEqualTypeOf<
+  number | undefined
+>()
+
+// @ts-expect-error a middleware is not a capability identity.
+ctx.get(providesPersistence)
diff --git a/packages/ai/tests/middleware-capabilities.test.ts b/packages/ai/tests/middleware-capabilities.test.ts
new file mode 100644
index 000000000..35e705015
--- /dev/null
+++ b/packages/ai/tests/middleware-capabilities.test.ts
@@ -0,0 +1,284 @@
+import { describe, it, expect, vi } from 'vitest'
+import {
+  createCapability,
+  CapabilityRegistry,
+} from '../src/activities/chat/middleware/capabilities'
+import { validateCapabilities } from '../src/activities/chat/middleware/validate'
+import { createChatMiddleware } from '../src/activities/chat/middleware/builder'
+import { defineChatMiddleware } from '../src/activities/chat/middleware/define'
+import type { CapabilityContext } from '../src/activities/chat/middleware/capabilities'
+import { MiddlewareRunner } from '../src/activities/chat/middleware/compose'
+import { resolveDebugOption } from '../src/logger/resolve'
+import { chat } from '../src'
+import { createMockAdapter, ev, collectChunks } from './test-utils'
+import type {
+  ChatMiddleware,
+  ChatMiddlewareContext,
+} from '../src/activities/chat/middleware/types'
+
+// A capability accessor only needs `ctx.capabilities`, so test contexts are
+// typed against the minimal CapabilityContext — no casts.
+function makeCtx(): CapabilityContext {
+  return { capabilities: new CapabilityRegistry() }
+}
+
+describe('createCapability + CapabilityRegistry', () => {
+  it('provides and gets a value by handle reference', () => {
+    const cap = createCapability<{ n: number }>()('thing')
+    const [getThing, provideThing] = cap
+    const ctx = makeCtx()
+    provideThing(ctx, { n: 1 })
+    expect(getThing(ctx)).toEqual({ n: 1 })
+  })
+
+  it('get throws a named error when absent', () => {
+    const [getThing] = createCapability<number>()('counter')
+    const ctx = makeCtx()
+    expect(() => getThing(ctx)).toThrowError(
+      /capability "counter".*never provided/i,
+    )
+  })
+
+  it('get with { optional: true } returns undefined when absent', () => {
+    const [getThing] = createCapability<number>()('counter')
+    const ctx = makeCtx()
+    expect(getThing(ctx, { optional: true })).toBeUndefined()
+  })
+
+  it('two capabilities with the same name are distinct identities', () => {
+    const [getA, provideA] = createCapability<string>()('dup')
+    const [getB] = createCapability<string>()('dup')
+    const ctx = makeCtx()
+    provideA(ctx, 'a')
+    expect(getA(ctx)).toBe('a')
+    expect(getB(ctx, { optional: true })).toBeUndefined()
+  })
+
+  it('exposes capabilityName for diagnostics', () => {
+    const cap = createCapability<number>()('labelled')
+    expect(cap.capabilityName).toBe('labelled')
+  })
+
+  it('duplicate provide is last-wins and notifies the registry', () => {
+    const [getThing, provideThing] = createCapability<number>()('over')
+    const ctx = makeCtx()
+    const warn = vi.fn()
+    ctx.capabilities.setOnDuplicate(warn)
+    provideThing(ctx, 1)
+    provideThing(ctx, 2)
+    expect(getThing(ctx)).toBe(2)
+    expect(warn).toHaveBeenCalledWith('over')
+  })
+})
+
+// runSetup forwards the full stable context to each setup hook and to
+// instrumentation, so the test builds a complete (inert) ChatMiddlewareContext
+// — typed against the real interface, no casts.
+function makeRunnerCtx(): ChatMiddlewareContext {
+  const ctx: ChatMiddlewareContext = {
+    requestId: 'r',
+    streamId: 's',
+    runId: 'run',
+    threadId: 't',
+    phase: 'init',
+    iteration: 0,
+    chunkIndex: 0,
+    abort: () => {},
+    context: undefined,
+    defer: () => {},
+    provider: 'test',
+    model: 'test-model',
+    source: 'server',
+    streaming: true,
+    systemPrompts: [],
+    messageCount: 0,
+    hasTools: false,
+    currentMessageId: null,
+    accumulatedContent: '',
+    messages: [],
+    createId: (prefix) => `${prefix}-id`,
+    capabilities: new CapabilityRegistry(),
+    get: (capability) => capability[0](ctx),
+    getOptional: (capability) => capability[0](ctx, { optional: true }),
+    provide: (capability, value) => capability[1](ctx, value),
+  }
+  return ctx
+}
+
+describe('MiddlewareRunner.runSetup', () => {
+  it('runs setup hooks in array order before consumers can read', async () => {
+    const aCap = createCapability<number>()('order-a')
+    const [getA, provideA] = aCap
+    const order: Array<string> = []
+    const provider: ChatMiddleware = {
+      name: 'provider',
+      provides: [aCap],
+      setup(ctx) {
+        order.push('provider')
+        provideA(ctx, 7)
+      },
+    }
+    const consumer: ChatMiddleware = {
+      name: 'consumer',
+      requires: [aCap],
+      setup(ctx) {
+        order.push('consumer')
+        expect(getA(ctx)).toBe(7)
+      },
+    }
+    const runner = new MiddlewareRunner(
+      [provider, consumer],
+      resolveDebugOption(false),
+    )
+    await runner.runSetup(makeRunnerCtx())
+    expect(order).toEqual(['provider', 'consumer'])
+  })
+
+  it('throws if a middleware declares provides but never provides in setup', async () => {
+    const cap = createCapability<number>()('declared-not-provided')
+    const broken: ChatMiddleware = {
+      name: 'broken',
+      provides: [cap],
+      setup() {},
+    }
+    const runner = new MiddlewareRunner([broken], resolveDebugOption(false))
+    await expect(runner.runSetup(makeRunnerCtx())).rejects.toThrow(
+      /middleware "broken".*declares.*"declared-not-provided".*never called provide/i,
+    )
+  })
+})
+
+describe('validateCapabilities', () => {
+  it('passes when all middleware + adapter requires are provided', () => {
+    const cap = createCapability<number>()('ok-cap')
+    const provider: ChatMiddleware = { name: 'p', provides: [cap] }
+    const consumer: ChatMiddleware = { name: 'c', requires: [cap] }
+    expect(() =>
+      validateCapabilities([provider, consumer], { name: 'openai' }),
+    ).not.toThrow()
+  })
+
+  it('throws naming the missing capability and listing provided ones', () => {
+    const sandbox = createCapability<number>()('sandbox')
+    const persistence = createCapability<number>()('persistence')
+    const adapter = { name: 'claude-code', requires: [sandbox] }
+    const mw: ChatMiddleware = { name: 'persistence', provides: [persistence] }
+    expect(() => validateCapabilities([mw], adapter)).toThrowError(
+      /adapter "claude-code" requires capability "sandbox"/i,
+    )
+  })
+
+  it('ignores optionalRequires when computing missing', () => {
+    const opt = createCapability<number>()('opt')
+    const mw: ChatMiddleware = { name: 'x', optionalRequires: [opt] }
+    expect(() => validateCapabilities([mw], { name: 'a' })).not.toThrow()
+  })
+})
+
+describe('chat() capability integration', () => {
+  it('runs setup before onConfig and lets onConfig consume a capability', async () => {
+    const cap = createCapability<{ greeting: string }>()('greeter')
+    const [getGreeting, provideGreeting] = cap
+    const seen: Array<string> = []
+    const provider: ChatMiddleware = {
+      name: 'greeter-provider',
+      provides: [cap],
+      setup(ctx) {
+        seen.push('setup')
+        provideGreeting(ctx, { greeting: 'hi' })
+      },
+    }
+    const consumer: ChatMiddleware = {
+      name: 'greeter-consumer',
+      requires: [cap],
+      onConfig(ctx) {
+        seen.push('onConfig')
+        expect(getGreeting(ctx).greeting).toBe('hi')
+      },
+    }
+    const { adapter } = createMockAdapter({
+      iterations: [
+        [
+          ev.runStarted(),
+          ev.textStart(),
+          ev.textContent('hi'),
+          ev.textEnd(),
+          ev.runFinished(),
+        ],
+      ],
+    })
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hello' }],
+        middleware: [provider, consumer],
+      }),
+    )
+    expect(seen[0]).toBe('setup')
+    expect(seen).toContain('onConfig')
+  })
+
+  it('supports ctx.provide / ctx.get / ctx.getOptional by handle', async () => {
+    const cap = createCapability<{ greeting: string }>()('ctx-greeter')
+    const absent = createCapability<number>()('ctx-absent')
+    let read: { greeting: string } | undefined
+    let optionalMissing: number | undefined = 1
+    const provider: ChatMiddleware = {
+      name: 'ctx-provider',
+      provides: [cap],
+      setup(ctx) {
+        ctx.provide(cap, { greeting: 'hey' })
+      },
+    }
+    const consumer: ChatMiddleware = {
+      name: 'ctx-consumer',
+      requires: [cap],
+      onConfig(ctx) {
+        read = ctx.get(cap)
+        optionalMissing = ctx.getOptional(absent)
+      },
+    }
+    const { adapter } = createMockAdapter({
+      iterations: [[ev.runStarted(), ev.runFinished()]],
+    })
+    await collectChunks(
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'hello' }],
+        middleware: [provider, consumer],
+      }),
+    )
+    expect(read).toEqual({ greeting: 'hey' })
+    expect(optionalMissing).toBeUndefined()
+  })
+
+  it('throws synchronously when a required capability is unprovided', () => {
+    const sandbox = createCapability<number>()('sandbox-int')
+    const needsSandbox: ChatMiddleware = {
+      name: 'needs-sandbox',
+      requires: [sandbox],
+    }
+    const { adapter } = createMockAdapter({ iterations: [[]] })
+    expect(() =>
+      chat({
+        adapter,
+        messages: [{ role: 'user', content: 'x' }],
+        middleware: [needsSandbox],
+      }),
+    ).toThrowError(/requires capability "sandbox-int"/i)
+  })
+})
+
+describe('createChatMiddleware builder', () => {
+  it('build() returns the middleware in use() order', () => {
+    const cap = createCapability<number>()('built-order')
+    const a = defineChatMiddleware({
+      name: 'a',
+      provides: [cap],
+      setup: (ctx) => cap[1](ctx, 1),
+    })
+    const b = defineChatMiddleware({ name: 'b', requires: [cap] })
+    const built = createChatMiddleware().use(a).use(b).build()
+    expect(built.map((m) => m.name)).toEqual(['a', 'b'])
+  })
+})
diff --git a/packages/ai/tsconfig.json b/packages/ai/tsconfig.json
index b804cc7bc..c38689f4e 100644
--- a/packages/ai/tsconfig.json
+++ b/packages/ai/tsconfig.json
@@ -4,5 +4,5 @@
     "outDir": "dist"
   },
   "include": ["src", "tests"],
-  "exclude": ["node_modules", "dist", "tests/**/*.test-d.ts"]
+  "exclude": ["node_modules", "dist"]
 }
diff --git a/testing/e2e/fixtures/middleware-test/capability.json b/testing/e2e/fixtures/middleware-test/capability.json
new file mode 100644
index 000000000..d4a063484
--- /dev/null
+++ b/testing/e2e/fixtures/middleware-test/capability.json
@@ -0,0 +1,10 @@
+{
+  "fixtures": [
+    {
+      "match": { "userMessage": "[capability] run test", "sequenceIndex": 0 },
+      "response": {
+        "content": "Hello from the assistant."
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/src/routes/api.middleware-test.ts b/testing/e2e/src/routes/api.middleware-test.ts
index 9d6f065bd..9879df7dd 100644
--- a/testing/e2e/src/routes/api.middleware-test.ts
+++ b/testing/e2e/src/routes/api.middleware-test.ts
@@ -2,6 +2,7 @@ import { createFileRoute } from '@tanstack/react-router'
 import {
   chat,
   chatParamsFromRequestBody,
+  createCapability,
   maxIterations,
   toServerSentEventsResponse,
   toolDefinition,
@@ -81,6 +82,49 @@ const toolSkipMiddleware: ChatMiddleware = {
   },
 }
 
+/**
+ * Capability provide/consume flow (`capability` mode).
+ *
+ * Exercises the server-side middleware capability primitive end-to-end:
+ *
+ * - `prefixCapability` is a typed handle created via `createCapability`. It is
+ *   simultaneously a `[get, provide]` tuple and the identity referenced in the
+ *   middleware `provides`/`requires` declarations.
+ * - `prefixProviderMiddleware` declares `provides: [prefixCapability]` and calls
+ *   `providePrefix(ctx, ...)` in `setup` — the hook that runs first, before any
+ *   `onConfig`/`onChunk`.
+ * - `prefixConsumerMiddleware` declares `requires: [prefixCapability]` and reads
+ *   the value with `getPrefix(ctx)` inside `onChunk`, using it to prefix every
+ *   text delta. The consumed value therefore shows up verbatim in the streamed
+ *   assistant text, which the spec asserts against the deterministic fixture.
+ */
+const prefixCapability = createCapability<string>()('capability-prefix')
+const [getPrefix, providePrefix] = prefixCapability
+
+const prefixProviderMiddleware: ChatMiddleware = {
+  name: 'prefix-provider',
+  provides: [prefixCapability],
+  setup(ctx) {
+    providePrefix(ctx, '[CAP]')
+  },
+}
+
+const prefixConsumerMiddleware: ChatMiddleware = {
+  name: 'prefix-consumer',
+  requires: [prefixCapability],
+  onChunk(ctx, chunk) {
+    if (chunk.type === 'TEXT_MESSAGE_CONTENT' && chunk.delta) {
+      const prefix = getPrefix(ctx)
+      return {
+        ...chunk,
+        delta: prefix + ' ' + chunk.delta,
+        content: prefix + ' ' + (chunk.content || ''),
+      }
+    }
+    return chunk
+  },
+}
+
 /**
  * Per-testId recorder used by `phase-recorder` mode.
  *
@@ -289,6 +333,11 @@ export const Route = createFileRoute('/api/middleware-test')({
             middleware.push(chunkTransformMiddleware)
           if (middlewareMode === 'tool-skip')
             middleware.push(toolSkipMiddleware)
+          if (middlewareMode === 'capability') {
+            // Order matters: the provider's setup() must run before the
+            // consumer reads the capability. Array order is preserved.
+            middleware.push(prefixProviderMiddleware, prefixConsumerMiddleware)
+          }
           if (middlewareMode === 'phase-recorder') {
             if (!testId) {
               return new Response(
diff --git a/testing/e2e/src/routes/middleware-test.tsx b/testing/e2e/src/routes/middleware-test.tsx
index d4a3f2a50..784c4067a 100644
--- a/testing/e2e/src/routes/middleware-test.tsx
+++ b/testing/e2e/src/routes/middleware-test.tsx
@@ -6,6 +6,7 @@ const MIDDLEWARE_MODES = [
   { id: 'none', label: 'No Middleware' },
   { id: 'chunk-transform', label: 'Chunk Transform (prefix text)' },
   { id: 'tool-skip', label: 'Tool Skip (skip with custom result)' },
+  { id: 'capability', label: 'Capability (provide/consume prefix)' },
   { id: 'phase-recorder', label: 'Phase Recorder (capture phase + chunks)' },
   { id: 'otel', label: 'OpenTelemetry (capture spans/metrics)' },
 ] as const
@@ -144,6 +145,7 @@ function MiddlewareTestPage() {
           }}
         >
           <option value="basic-text">Basic Text</option>
+          <option value="capability">Capability</option>
           <option value="with-tool">With Tool</option>
           <option value="structured-output">Structured Output</option>
           <option value="structured-output-stream">
diff --git a/testing/e2e/tests/middleware.spec.ts b/testing/e2e/tests/middleware.spec.ts
index e039d78ab..f826cbac4 100644
--- a/testing/e2e/tests/middleware.spec.ts
+++ b/testing/e2e/tests/middleware.spec.ts
@@ -82,6 +82,41 @@ test.describe('Middleware Lifecycle', () => {
     expect(toolResults[0].content).toContain('skipped')
   })
 
+  test('capability provide/consume flow surfaces the consumed value in the stream', async ({
+    page,
+    testId,
+    aimockPort,
+  }) => {
+    const params = new URLSearchParams()
+    if (testId) params.set('testId', testId)
+    if (aimockPort) params.set('aimockPort', String(aimockPort))
+    const qs = params.toString()
+    await page.goto(`/middleware-test${qs ? '?' + qs : ''}`)
+    await page.waitForTimeout(2000) // hydration
+    await page.locator('#mw-scenario-select').selectOption('capability')
+    await page.locator('#mw-mode-select').selectOption('capability')
+    await page.locator('#mw-run-button').click()
+
+    await page.waitForFunction(
+      () =>
+        document
+          .querySelector('#mw-metadata')
+          ?.getAttribute('data-test-complete') === 'true',
+      { timeout: 10000 },
+    )
+
+    const messagesJson = await page.locator('#mw-messages-json').textContent()
+    const messages = JSON.parse(messagesJson || '[]')
+    const assistantMsg = messages.find((m: any) => m.role === 'assistant')
+    const textPart = assistantMsg?.parts?.find((p: any) => p.type === 'text')
+    // The provider middleware provides "[CAP]" in setup(); the consumer
+    // middleware reads it via the capability getter in onChunk and prefixes
+    // each text delta. Seeing "[CAP]" in the streamed text proves the provided
+    // capability value flowed across middleware to the consumer.
+    expect(textPart?.content).toContain('[CAP]')
+    expect(textPart?.content).toContain('Hello')
+  })
+
   test('otel middleware emits chat span + per-iteration token histograms', async ({
     page,
     testId,