diff --git a/.agent/domain-map.json b/.agent/domain-map.json
index b09f64e809..9ba603e418 100644
--- a/.agent/domain-map.json
+++ b/.agent/domain-map.json
@@ -133,6 +133,11 @@
       ],
       "talksTo": ["core"]
     },
+    {
+      "id": "effect",
+      "owns": ["packages/ai-effect"],
+      "talksTo": ["core"]
+    },
     {
       "id": "e2e",
       "owns": ["testing/e2e"],
@@ -141,6 +146,7 @@
         "code-mode",
         "computer-use",
         "core",
+        "effect",
         "harness",
         "middleware",
         "persistence",
diff --git a/.changeset/ai-effect.md b/.changeset/ai-effect.md
new file mode 100644
index 0000000000..82feca9b0f
--- /dev/null
+++ b/.changeset/ai-effect.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-effect': minor
+---
+
+Add `@tanstack/ai-effect`, a new package that runs every TanStack AI activity as an Effect or a Stream and lets you write server tools as Effects.
diff --git a/docs/api/ai-effect.md b/docs/api/ai-effect.md
new file mode 100644
index 0000000000..402acc9feb
--- /dev/null
+++ b/docs/api/ai-effect.md
@@ -0,0 +1,144 @@
+---
+title: "@tanstack/ai-effect"
+id: tanstack-ai-effect-api
+order: 11
+description: "API reference for @tanstack/ai-effect: chat, serverTool, toolSchema, AIError, and every TanStack AI activity as an Effect 4 Effect or Stream."
+keywords:
+  - tanstack ai
+  - "@tanstack/ai-effect"
+  - effect
+  - serverTool
+  - toolSchema
+  - AIError
+  - api reference
+---
+
+Effect 4 bindings for TanStack AI. Each function takes the options of the core function and returns an Effect `Effect` or `Stream`. For a walkthrough, start with [Effect](../effect/index).
+
+## Installation
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-effect effect
+
+<!-- ::end:tabs -->
+
+Peer dependencies: `@tanstack/ai` and `effect` 4.1 or later.
+
+## `chat(options)`
+
+Runs core `chat()` as an Effect. See [Effect](../effect/index).
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+
+const stream = AI.chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'Hello' }],
+  threadId: 'hello',
+})
+```
+
+### Options
+
+The options of core [`chat`](./ai#chat), with two changes:
+
+- `abortController` is not an option. Interruption aborts the run.
+- `tools` can also hold `serverTool` values.
+
+### Returns
+
+| Options | Returns |
+| --- | --- |
+| Default | `Stream.Stream<StreamChunk, AIError, R>` |
+| `stream: false` | `Effect.Effect<ChatResult, AIError, R>`. `ChatResult` is `{ text, chunks }`. |
+| `outputSchema` | `Effect.Effect<T, AIError, R>`. `T` is the type of the schema. |
+| `outputSchema` and `stream: true` | `Stream.Stream<StreamChunk, AIError, R>` |
+
+`R` is the union of the services of the `serverTool` values in `tools`. With no `serverTool`, `R` is `never`.
+
+## `serverTool(definition, execute)`
+
+Makes a server tool from a tool definition and a function that returns an Effect. See [Effect tools](../effect/tools).
+
+```ts ignore
+function serverTool<TDef, E, R>(
+  definition: TDef,
+  execute: (
+    input: InferSchemaType<TDef['inputSchema']>,
+    context: ToolExecutionContext,
+  ) => Effect.Effect<InferSchemaType<TDef['outputSchema']>, E, R>,
+): EffectServerTool<TDef, R>
+```
+
+- `definition`: the result of `toolDefinition()` from `@tanstack/ai`.
+- `execute`: gets the parsed input and the tool context. It returns an Effect of the output.
+
+A failure of the Effect goes to the model as a tool error. The run continues. If the run aborts, the tool fiber is interrupted.
+
+## `toolSchema(schema)`
+
+Turns an Effect Schema into an `inputSchema` or `outputSchema` for `toolDefinition()`.
+
+```ts ignore
+function toolSchema<S extends Schema.Constraint>(
+  schema: S,
+): StandardJSONSchemaV1<S['Encoded'], S['Type']>
+```
+
+- Every object in the JSON Schema has `additionalProperties: false`. This lets providers such as OpenAI use strict mode.
+- The tool input in `serverTool` gets the type of the schema.
+
+## `EffectServerTool<TDef, R>`
+
+The type that `serverTool` returns. Pass it in the `tools` of `chat`.
+
+| Field | Type |
+| --- | --- |
+| `_tag` | `'EffectServerTool'` |
+| `def` | `TDef` |
+| `execute` | `(input, ctx) => Effect.Effect<Output, unknown, R>` |
+
+## `AIError`
+
+The error of every function in this package. It wraps a throw or a rejection from TanStack AI.
+
+```ts ignore
+class AIError extends Data.TaggedError('AIError')<{
+  readonly message: string
+  readonly cause: unknown
+}> {}
+```
+
+- `_tag`: `'AIError'`. Catch it with `Effect.catchTag('AIError', ...)`.
+- `message`: the message of the original error.
+- `cause`: the original error.
+
+A `RUN_ERROR` chunk does not fail a `Stream`. It is a normal chunk. See [Effect activities](../effect/activities#a-run_error-chunk-does-not-fail-the-stream).
+
+## Activities
+
+Each activity takes the options of its core function, without `abortSignal`. It returns `Effect.Effect<Result, AIError>`. With `stream: true`, it returns `Stream.Stream<StreamChunk, AIError>`.
+
+| Function | Core function | Supports `stream: true` |
+| --- | --- | --- |
+| `summarize` | `summarize` | Yes |
+| `generateImage` | `generateImage` | Yes |
+| `generateAudio` | `generateAudio` | Yes |
+| `generateSpeech` | `generateSpeech` | Yes |
+| `generateVoice` | `generateVoice` | Yes |
+| `generateTranscription` | `generateTranscription` | Yes |
+| `generateVideo` | `generateVideo` | Yes |
+| `generateWorld` | `generateWorld` | Yes |
+| `generateLiveVideo` | `generateLiveVideo` | Yes |
+| `getVideoJobStatus` | `getVideoJobStatus` | No |
+| `embed` | `embed` | No |
+| `rerank` | `rerank` | No |
+| `decide` | `decide` | No |
+| `listVoices` | `listVoices` | No |
+| `uploadFile` | `uploadFile` | No |
+| `getFile` | `getFile` | No |
+| `deleteFile` | `deleteFile` | No |
+
+For the core options and results, see [`@tanstack/ai`](./ai). For examples, see [Effect activities](../effect/activities).
diff --git a/docs/config.json b/docs/config.json
index b4eca00ace..d1f636d5b8 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -104,6 +104,11 @@
           "label": "Subscribe to MCP Events",
           "to": "tutorials/mcp-events",
           "addedAt": "2026-10-17"
+        },
+        {
+          "label": "Effect Chat",
+          "to": "tutorials/effect-chat",
+          "addedAt": "2026-11-06"
         }
       ]
     },
@@ -155,6 +160,11 @@
           "label": "MCP Events",
           "to": "framework/react/examples/mcp-events",
           "addedAt": "2026-10-17"
+        },
+        {
+          "label": "Effect Chat",
+          "to": "framework/react/examples/effect-chat",
+          "addedAt": "2026-11-06"
         }
       ]
     },
@@ -1674,6 +1684,27 @@
       ],
       "tab": "guides"
     },
+    {
+      "label": "Effect",
+      "tab": "guides",
+      "children": [
+        {
+          "label": "Stream a Chat",
+          "to": "effect/index",
+          "addedAt": "2026-11-06"
+        },
+        {
+          "label": "Tools",
+          "to": "effect/tools",
+          "addedAt": "2026-11-06"
+        },
+        {
+          "label": "Activities",
+          "to": "effect/activities",
+          "addedAt": "2026-11-06"
+        }
+      ]
+    },
     {
       "label": "Adapters",
       "children": [
@@ -2062,6 +2093,11 @@
           "to": "api/ai-remix",
           "addedAt": "2026-09-01",
           "updatedAt": "2026-10-21"
+        },
+        {
+          "label": "@tanstack/ai-effect",
+          "to": "api/ai-effect",
+          "addedAt": "2026-11-06"
         }
       ]
     },
diff --git a/docs/effect/activities.md b/docs/effect/activities.md
new file mode 100644
index 0000000000..bb37b6ab6e
--- /dev/null
+++ b/docs/effect/activities.md
@@ -0,0 +1,188 @@
+---
+title: Effect Activities
+id: effect-activities
+order: 3
+description: "Run TanStack AI image, audio, speech, embedding, and other activities as Effects or Streams with @tanstack/ai-effect. Handle AIError with catchTag and stop requests with interruption."
+keywords:
+  - tanstack ai
+  - effect
+  - ai-effect
+  - generateImage
+  - embed
+  - AIError
+  - interruption
+---
+
+You also generate images, embed text, or make speech in your Effect code. The core functions return promises, so their errors are not typed and you cannot interrupt them.
+
+Each activity in `@tanstack/ai-effect` takes the options of the core function. It returns an `Effect`, or a `Stream` with `stream: true`. Every failure is an `AIError`.
+
+## 1. Run an activity as an Effect
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiImage } from '@tanstack/ai-openai'
+import { Effect } from 'effect'
+
+const program = Effect.gen(function* () {
+  const { images } = yield* AI.generateImage({
+    adapter: openaiImage('gpt-image-2.5-flare'),
+    prompt: 'A red fox in the snow',
+    threadId: 'fox',
+    size: '1024x1024',
+  })
+  return images[0]?.url
+})
+
+const url = await Effect.runPromise(program)
+```
+
+The Effect is lazy. Each run sends a new request. TypeScript checks `size` and `modelOptions` against the model, the same as in core.
+
+## 2. Stream an activity
+
+Pass `stream: true` to get a `Stream` of chunks. Send it to the browser the same way as a chat:
+
+```ts ignore
+import {
+  generationParamsFromRequest,
+  toServerSentEventsResponse,
+} from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiImage } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+
+export async function POST(request: Request) {
+  const { input, threadId } = await generationParamsFromRequest('image', request)
+  if (typeof input.prompt !== 'string') {
+    return new Response('Send a text prompt.', { status: 400 })
+  }
+
+  const stream = AI.generateImage({
+    adapter: openaiImage('gpt-image-2.5-flare'),
+    prompt: input.prompt,
+    threadId,
+    stream: true,
+  })
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+```
+
+On the client, read it with a generation hook. The client does not use Effect:
+
+```tsx
+import { fetchServerSentEvents, useGenerateImage } from '@tanstack/ai-react'
+
+export function FoxImage() {
+  const { generate, result, isLoading } = useGenerateImage({
+    connection: fetchServerSentEvents('/api/generate/image'),
+    threadId: 'fox',
+  })
+
+  return (
+    <div>
+      <button
+        onClick={() => generate({ prompt: 'A red fox in the snow' })}
+        disabled={isLoading}
+      >
+        Generate
+      </button>
+      {result?.images.map((image, index) => (
+        <img key={index} src={image.url} alt="A red fox" />
+      ))}
+    </div>
+  )
+}
+```
+
+Click **Generate**. The image appears when the stream sends its result. For the other hooks, see [Generation Hooks](../media/generation-hooks).
+
+## Handle AIError
+
+Every activity fails with `AIError` when the core call throws or rejects:
+
+- `message` is the message of the original error.
+- `cause` is the original error.
+- `_tag` is `'AIError'`, so `Effect.catchTag` can catch it.
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiEmbedding } from '@tanstack/ai-openai'
+import { Effect } from 'effect'
+
+const vectors = AI.embed({
+  adapter: openaiEmbedding('text-embedding-3-small'),
+  input: ['a red guitar', 'a blue drum kit'],
+}).pipe(
+  Effect.map((result) => result.embeddings.map((embedding) => embedding.vector)),
+  Effect.catchTag('AIError', (error) =>
+    Effect.logError('Embedding failed', error.cause).pipe(Effect.as([])),
+  ),
+)
+```
+
+### A RUN_ERROR chunk does not fail the Stream
+
+In a `Stream`, a `RUN_ERROR` chunk is a normal chunk. The Stream sends it on, and the client shows the error. The Stream fails with `AIError` only when the core iterator throws.
+
+To act on a run error on the server, look for the chunk:
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Effect, Stream } from 'effect'
+
+const stream = AI.chat({
+  adapter: openaiText('gpt-6.1-sol'),
+  messages: [{ role: 'user', content: 'Hello' }],
+  threadId: 'hello',
+}).pipe(
+  Stream.tap((chunk) =>
+    chunk.type === 'RUN_ERROR' ? Effect.logError(chunk.message) : Effect.void,
+  ),
+)
+```
+
+## Stop a request
+
+You do not pass an `abortSignal`. Interruption aborts the request:
+
+- If you interrupt the fiber, the request to the provider stops.
+- If a `Stream` stops early, for example with `Stream.take`, the request stops.
+- `Effect.timeout` interrupts the Effect, so it also stops the request.
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiImage } from '@tanstack/ai-openai'
+import { Effect } from 'effect'
+
+const quick = AI.generateImage({
+  adapter: openaiImage('gpt-image-2.5-flare'),
+  prompt: 'A red fox in the snow',
+  threadId: 'fox',
+}).pipe(Effect.timeout('30 seconds'))
+```
+
+## All wrapped activities
+
+| Function | Returns | With `stream: true` |
+| --- | --- | --- |
+| `summarize` | `Effect` of the summary | `Stream` of chunks |
+| `generateImage` | `Effect` of the images | `Stream` of chunks |
+| `generateAudio` | `Effect` of the audio | `Stream` of chunks |
+| `generateSpeech` | `Effect` of the speech | `Stream` of chunks |
+| `generateVoice` | `Effect` of the voices | `Stream` of chunks |
+| `generateTranscription` | `Effect` of the text | `Stream` of chunks |
+| `generateVideo` | `Effect` of the job | `Stream` of the job lifecycle |
+| `generateWorld` | `Effect` of the world | `Stream` of chunks |
+| `generateLiveVideo` | `Effect` of the session | `Stream` of chunks |
+| `getVideoJobStatus` | `Effect` of the job status | |
+| `embed` | `Effect` of the vectors | |
+| `rerank` | `Effect` of the ranked documents | |
+| `decide` | `Effect` of the answers | |
+| `listVoices` | `Effect` of the voices | |
+| `uploadFile`, `getFile` | `Effect` of the file handle | |
+| `deleteFile` | `Effect` of `void` | |
+
+`chat` has its own page: [Effect](./index). For the exact types, see the [API reference](../api/ai-effect).
diff --git a/docs/effect/index.md b/docs/effect/index.md
new file mode 100644
index 0000000000..bb003d1c58
--- /dev/null
+++ b/docs/effect/index.md
@@ -0,0 +1,130 @@
+---
+title: Effect
+id: effect
+order: 1
+description: "Stream a TanStack AI chat from an Effect 4 server. AI.chat from @tanstack/ai-effect returns an Effect Stream that you send to useChat as Server-Sent Events."
+keywords:
+  - tanstack ai
+  - effect
+  - effect 4
+  - ai-effect
+  - stream
+  - server-sent events
+  - useChat
+---
+
+Your server code uses Effect 4. Core `chat()` returns an async iterable and throws plain errors, so it does not fit in your Effect program.
+
+`@tanstack/ai-effect` wraps TanStack AI for Effect. `AI.chat` returns an Effect `Stream` of chunks. Its errors are typed, and interruption stops the model request.
+
+## 1. Install the packages
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-effect @tanstack/ai-openai @tanstack/ai-react effect
+
+<!-- ::end:tabs -->
+
+The package needs Effect 4 (`effect` 4.1 or later).
+
+## 2. Stream the chat from your server route
+
+```ts ignore
+import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+  })
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+```
+
+What each piece does:
+
+- `AI.chat` takes the options of core `chat()`. It returns a `Stream<StreamChunk, AIError>`.
+- `Stream.toAsyncIterable` turns the `Stream` into the async iterable that `toServerSentEventsResponse` reads.
+- If the browser closes the request, the stream stops. Then `AI.chat` aborts the request to the model.
+
+## 3. Show the chat on the client
+
+The client does not use Effect. It reads the Server-Sent Events with `useChat`:
+
+```tsx
+import { useState } from 'react'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+export function Chat() {
+  const [input, setInput] = useState('')
+  const { messages, sendMessage, isLoading } = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+    threadId: 'effect-chat',
+  })
+
+  return (
+    <div>
+      {messages.map((message) => (
+        <p key={message.id}>
+          {message.role}:{' '}
+          {message.parts.map((part) =>
+            part.type === 'text' ? part.content : null,
+          )}
+        </p>
+      ))}
+      <form
+        onSubmit={(event) => {
+          event.preventDefault()
+          sendMessage(input)
+          setInput('')
+        }}
+      >
+        <input value={input} onChange={(event) => setInput(event.target.value)} />
+        <button type="submit" disabled={isLoading}>
+          Send
+        </button>
+      </form>
+    </div>
+  )
+}
+```
+
+Send a message. The reply streams in token by token from your Effect server.
+
+## Get the whole reply as an Effect
+
+If you do not need tokens as they arrive, pass `stream: false`. Then `AI.chat` returns an `Effect` of `{ text, chunks }`:
+
+```ts ignore
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Effect } from 'effect'
+
+const program = Effect.gen(function* () {
+  const { text } = yield* AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: [{ role: 'user', content: 'Write a haiku about rivers.' }],
+    threadId: 'haiku',
+    stream: false,
+  })
+  return text
+})
+
+const haiku = await Effect.runPromise(program)
+```
+
+With `outputSchema`, `AI.chat` returns an `Effect` of the parsed object. See [Structured Outputs](../structured-outputs/overview) for the schema options.
+
+## Next
+
+- Build the full app step by step: [Effect Chat tutorial](../tutorials/effect-chat).
+- Give your tools Effect services: [Effect tools](./tools).
+- Run images, embeddings, and speech as Effects: [Effect activities](./activities).
diff --git a/docs/effect/tools.md b/docs/effect/tools.md
new file mode 100644
index 0000000000..8885fc995b
--- /dev/null
+++ b/docs/effect/tools.md
@@ -0,0 +1,131 @@
+---
+title: Effect Tools
+id: effect-tools
+order: 2
+description: "Write TanStack AI server tools as Effects with AI.serverTool. The tool reads your Effect services, and a Layer provides them to the AI.chat stream."
+keywords:
+  - tanstack ai
+  - effect
+  - ai-effect
+  - serverTool
+  - layer
+  - services
+  - tools
+---
+
+Your tools need your database and your other Effect services. A core server tool is an async function, so it cannot read those services, and its errors are not typed.
+
+`AI.serverTool` makes a tool from a function that returns an Effect. The services of that Effect become requirements of the `AI.chat` stream. You provide them with a Layer.
+
+This page uses the server route from [Effect](./index). The client does not change.
+
+## 1. Define the service and its Layer
+
+```ts ignore
+import { Context, Data, Effect, Layer } from 'effect'
+
+export class OrderNotFound extends Data.TaggedError('OrderNotFound')<{
+  readonly id: string
+}> {}
+
+export class Db extends Context.Service<
+  Db,
+  {
+    readonly findOrder: (
+      id: string,
+    ) => Effect.Effect<{ status: string }, OrderNotFound>
+  }
+>()('Db') {}
+
+// A fixed order. Read from your real database here.
+export const DbLive = Layer.succeed(Db, {
+  findOrder: (id) =>
+    id === 'A-100'
+      ? Effect.succeed({ status: 'shipped' })
+      : Effect.fail(new OrderNotFound({ id })),
+})
+```
+
+## 2. Write the tool as an Effect
+
+```ts ignore
+import { toolDefinition } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { Effect, Schema } from 'effect'
+import { Db } from './db'
+
+const getOrderDef = toolDefinition({
+  name: 'get_order',
+  description: 'Get the status of an order',
+  inputSchema: AI.toolSchema(Schema.Struct({ id: Schema.String })),
+  outputSchema: AI.toolSchema(Schema.Struct({ status: Schema.String })),
+})
+
+export const getOrder = AI.serverTool(getOrderDef, ({ id }) =>
+  Effect.gen(function* () {
+    const db = yield* Db
+    return yield* db.findOrder(id)
+  }),
+)
+```
+
+`AI.toolSchema` turns an Effect Schema into a tool schema. It closes every object (`additionalProperties: false`), so OpenAI can check the tool arguments in strict mode.
+
+`AI.serverTool` takes a tool definition and a function. The function gets the parsed input and returns an Effect of the output. The type of `getOrder` keeps `Db` as a requirement.
+
+## 3. Pass the tool and provide the Layer
+
+```ts ignore
+import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+import { DbLive } from './db'
+import { getOrder } from './tools'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    tools: [getOrder],
+  }).pipe(Stream.provide(DbLive))
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+```
+
+The stream needs `Db` until you provide `DbLive`. If you remove `Stream.provide(DbLive)`, `Stream.toAsyncIterable` does not type-check.
+
+Ask "Where is order A-100?". The model calls `get_order`, your Effect reads `Db`, and the reply says the order shipped.
+
+## When the tool fails
+
+If the tool Effect fails, the model gets a tool error:
+
+- The error message goes back to the model as the tool result. The model can tell the user or try again.
+- The run continues. The stream does not fail.
+- A typed failure (`OrderNotFound`) and a defect (`Effect.die`) both work this way.
+
+Ask for order B-200. `findOrder` fails with `OrderNotFound`. The model gets the tool error and answers the user.
+
+To send the model a normal result instead, catch the error in the tool. For example, `Effect.catchTag('OrderNotFound', () => Effect.succeed({ status: 'unknown' }))`.
+
+## When the run stops
+
+The tool Effect runs with the services of the `AI.chat` stream. It stops when the run stops:
+
+- The browser closes the request.
+- Your code stops the stream early, for example with `Stream.take`.
+- Your code interrupts the fiber that runs the stream.
+
+In each case, the running tool fiber is interrupted. Its finalizers run, so `Effect.acquireRelease` and `Effect.onInterrupt` clean up as usual.
+
+## Mix with other tools
+
+The `tools` array can also hold core tools, for example `toolDefinition(...).server(...)` or client tools. Only the `AI.serverTool` values add services to the stream.
+
+The full app is in the [Effect Chat tutorial](../tutorials/effect-chat). For images, embeddings, and other activities, see [Effect activities](./activities).
diff --git a/docs/tutorials/effect-chat.md b/docs/tutorials/effect-chat.md
new file mode 100644
index 0000000000..b562d4eac7
--- /dev/null
+++ b/docs/tutorials/effect-chat.md
@@ -0,0 +1,250 @@
+---
+title: Effect Chat
+id: effect-chat
+order: 9
+description: "Build a streaming React chat with an Effect server. AI.chat from @tanstack/ai-effect streams the reply, and a get_weather tool is an Effect that reads a service from a Layer."
+keywords:
+  - tanstack ai
+  - tutorial
+  - effect
+  - ai-effect
+  - serverTool
+  - layer
+  - useChat
+  - openai
+  - tanstack start
+---
+
+Your server code uses Effect, and you want a chat that streams tokens. Core `chat()` gives an async iterable, and its tools return promises. Your Effect services do not reach those tools.
+
+`@tanstack/ai-effect` connects the two. `AI.chat` returns an Effect `Stream`. A tool made with `AI.serverTool` returns an Effect, and a Layer gives the tool its services.
+
+In this tutorial, the model calls a `get_weather` tool, and the tool reads a `Weather` service. This tutorial uses React, TanStack Start, and OpenAI. It takes about 10 minutes.
+
+## 1. Create a Start app
+
+```bash
+npx @tanstack/cli@latest create
+```
+
+Pick React. Then install the packages:
+
+<!-- ::start:tabs variant="package-manager" mode="install" -->
+
+react: @tanstack/ai @tanstack/ai-react @tanstack/ai-openai @tanstack/ai-effect effect
+
+<!-- ::end:tabs -->
+
+Put your OpenAI key in `.env.local`:
+
+```bash
+OPENAI_API_KEY=sk-...
+```
+
+## Client and server
+
+- **The server** runs the chat in Effect. It owns the tool and the Layer that gives the tool its service.
+- **The client** sends the messages and shows the reply. It does not use Effect.
+
+The next steps build the server first. Then they build the client.
+
+## 2. Add a service and a tool
+
+Create `src/lib/weather.ts`:
+
+```typescript ignore
+import { toolDefinition } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { Context, Effect, Layer, Schema } from 'effect'
+
+export class Weather extends Context.Service<
+  Weather,
+  { readonly forecast: (city: string) => Effect.Effect<string> }
+>()('Weather') {}
+
+// A fixed forecast. Call a real weather API here.
+export const WeatherLive = Layer.succeed(Weather, {
+  forecast: (city) => Effect.succeed(`Sunny and 22 C in ${city}`),
+})
+
+const getWeatherDef = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the weather forecast for a city',
+  inputSchema: AI.toolSchema(Schema.Struct({ city: Schema.String })),
+  outputSchema: AI.toolSchema(Schema.Struct({ forecast: Schema.String })),
+})
+
+export const getWeather = AI.serverTool(getWeatherDef, ({ city }) =>
+  Effect.gen(function* () {
+    const weather = yield* Weather
+    return { forecast: yield* weather.forecast(city) }
+  }),
+)
+```
+
+This file has three parts:
+
+- `Weather` is an Effect service with one function, `forecast`.
+- `WeatherLive` is a Layer that gives a fixed forecast. Put a call to a real weather API here.
+- `getWeather` is the tool. `AI.serverTool` takes a tool definition and a function that returns an Effect.
+
+The type of `getWeather` keeps `Weather` as a requirement. If the Effect fails, the model gets a tool error, and the run continues.
+
+## 3. Add the server route
+
+Create `src/routes/api.chat.ts`, next to `index.tsx`. Start maps this file name to the `/api/chat` path.
+
+```typescript ignore
+import { createFileRoute } from '@tanstack/react-router'
+import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+import { WeatherLive, getWeather } from '@/lib/weather'
+
+export async function POST({ request }: { request: Request }) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    tools: [getWeather],
+  }).pipe(Stream.provide(WeatherLive))
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST,
+    },
+  },
+})
+```
+
+What each piece does:
+
+- `chatParamsFromRequest` reads the messages and the thread id from the POST body.
+- `AI.chat` takes the options of core `chat()`. It returns a `Stream` of chunks, and `Weather` is in its requirements.
+- `Stream.provide(WeatherLive)` gives the `Weather` service to the tool. If you remove this line, `Stream.toAsyncIterable` does not type-check.
+- `toServerSentEventsResponse` sends the chunks to the browser as Server-Sent Events.
+
+If the browser closes the request, the stream stops. Then `AI.chat` aborts the request to OpenAI.
+
+## 4. Add the chat page
+
+Replace `src/routes/index.tsx` with this file:
+
+```tsx ignore
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+function ChatPage() {
+  const [input, setInput] = useState('')
+  const { messages, sendMessage, isLoading, error, stop } = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+    threadId: 'effect-chat',
+  })
+
+  const handleSendMessage = () => {
+    if (!input.trim()) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
+  return (
+    <div className="mx-auto flex h-screen max-w-2xl flex-col gap-3 p-4 text-white">
+      <div className="flex-1 space-y-3 overflow-y-auto">
+        {messages.length === 0 ? (
+          <p className="text-center text-sm text-gray-400">
+            Ask for the weather in a city.
+          </p>
+        ) : null}
+        {messages.map((message) => (
+          <div key={message.id}>
+            <p className="text-xs text-gray-400">{message.role}</p>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text') {
+                return (
+                  <p key={index} className="whitespace-pre-wrap">
+                    {part.content}
+                  </p>
+                )
+              }
+              if (part.type === 'tool-call') {
+                return (
+                  <p key={index} className="text-sm text-orange-400">
+                    Called {part.name}
+                  </p>
+                )
+              }
+              return null
+            })}
+          </div>
+        ))}
+      </div>
+      {error ? <p className="text-sm text-red-400">{error.message}</p> : null}
+      <div className="flex gap-2">
+        <textarea
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter' && !event.shiftKey) {
+              event.preventDefault()
+              handleSendMessage()
+            }
+          }}
+          placeholder="What is the weather in Oslo?"
+          rows={1}
+          disabled={isLoading}
+          className="flex-1 resize-none rounded-lg border border-gray-700 bg-gray-800 px-3 py-2 text-sm"
+        />
+        {isLoading ? (
+          <button
+            type="button"
+            onClick={stop}
+            className="rounded-lg bg-red-600 px-4 py-2 text-sm"
+          >
+            Stop
+          </button>
+        ) : (
+          <button
+            type="button"
+            onClick={handleSendMessage}
+            disabled={!input.trim()}
+            className="rounded-lg bg-orange-500 px-4 py-2 text-sm disabled:opacity-50"
+          >
+            Send
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/')({
+  component: ChatPage,
+})
+```
+
+The client does not use Effect:
+
+- `useChat` sends the messages to `/api/chat` and updates `messages` as tokens arrive.
+- A `tool-call` part shows each time the model calls `get_weather`.
+
+Run the app and send "What is the weather in Oslo?". The page shows "Called get_weather". Then the reply streams in with the forecast from your `Weather` service.
+
+<!-- ::client-example library=ai framework=react slug=effect-chat -->
+
+You have a streaming chat with an Effect server, and a tool that gets its service from a Layer.
+
+Next, pick one:
+
+- More about Effect tools and tool errors: [Effect tools](../effect/tools).
+- Images, embeddings, and other activities in Effect: [Effect activities](../effect/activities).
+
+The full example is on GitHub: [TanStack/ai `examples/react/effect-chat`](https://github.com/TanStack/ai/tree/main/examples/react/effect-chat).
diff --git a/examples/README.md b/examples/README.md
index 58ce2c069c..123eb88eb0 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -7,6 +7,7 @@ This directory contains comprehensive examples demonstrating TanStack AI across
 Choose an example based on your use case:
 
 - **Want the smallest React + Start chat?** → [Basic Chat](#basic-chat)
+- **Want a chat server written with Effect?** → [Effect Chat](#effect-chat)
 - **Want an image from a prompt?** → [Generate Image](#generate-image)
 - **Want a table that fills as JSON streams?** → [Streaming Structured Table](#streaming-structured-table)
 - **Want typed ticket routing?** → [Evaluate](#evaluate)
@@ -41,6 +42,24 @@ Open http://localhost:3100. Paste an OpenRouter key. Send a message.
 
 ---
 
+### Effect Chat
+
+A slim TanStack Start chat with an Effect server. One provider (OpenAI). `@tanstack/ai-effect` streams the chat, and one tool is an Effect that reads a service from a Layer.
+
+**Path:** `examples/react/effect-chat`
+
+**Getting Started:**
+
+```bash
+pnpm --filter effect-chat dev
+```
+
+Put `OPENAI_API_KEY` in `.env.local`. Open http://localhost:3100. Send `What is the weather in Oslo?`.
+
+📖 [Full Documentation](react/effect-chat/README.md)
+
+---
+
 ### Generate Image
 
 A slim TanStack Start image app. One provider (OpenRouter). You paste your own key.
diff --git a/examples/react/effect-chat/.env.example b/examples/react/effect-chat/.env.example
new file mode 100644
index 0000000000..f29ec948f1
--- /dev/null
+++ b/examples/react/effect-chat/.env.example
@@ -0,0 +1,2 @@
+# The server route reads this key.
+OPENAI_API_KEY=
diff --git a/examples/react/effect-chat/.gitignore b/examples/react/effect-chat/.gitignore
new file mode 100644
index 0000000000..b6ceee9913
--- /dev/null
+++ b/examples/react/effect-chat/.gitignore
@@ -0,0 +1,7 @@
+node_modules
+dist
+.env
+.env.local
+.nitro
+.tanstack
+.output
diff --git a/examples/react/effect-chat/README.md b/examples/react/effect-chat/README.md
new file mode 100644
index 0000000000..76de0d1316
--- /dev/null
+++ b/examples/react/effect-chat/README.md
@@ -0,0 +1,13 @@
+# Effect Chat
+
+You want a streaming chat where the server is written with Effect. Ask for the weather in a city. The model calls a tool that is an Effect, and a Layer gives that tool its service.
+
+## Run it
+
+1. Copy `.env.example` to `.env.local` and put your OpenAI key in it.
+2. From the repo root, run `pnpm install`.
+3. Run `pnpm --filter effect-chat dev`.
+4. Open http://localhost:3100.
+5. Type "What is the weather in Oslo?" and click Send.
+
+The tool and its service are in `src/lib/weather.ts`. The server route is `src/routes/api.chat.ts`. The chat UI is `src/routes/index.tsx`.
diff --git a/examples/react/effect-chat/package.json b/examples/react/effect-chat/package.json
new file mode 100644
index 0000000000..faf0c4d2e5
--- /dev/null
+++ b/examples/react/effect-chat/package.json
@@ -0,0 +1,32 @@
+{
+  "name": "effect-chat",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev --port 3100",
+    "build": "vite build",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-effect": "workspace:*",
+    "@tanstack/ai-openai": "workspace:*",
+    "@tanstack/ai-react": "workspace:*",
+    "@tanstack/react-router": "^1.170.41",
+    "@tanstack/react-start": "^1.168.60",
+    "@tanstack/router-plugin": "^1.168.42",
+    "effect": "^4.1.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.2.1",
+    "typescript": "5.9.3",
+    "vite": "^8.2.1"
+  }
+}
diff --git a/examples/react/effect-chat/src/lib/weather.ts b/examples/react/effect-chat/src/lib/weather.ts
new file mode 100644
index 0000000000..bd53c1b587
--- /dev/null
+++ b/examples/react/effect-chat/src/lib/weather.ts
@@ -0,0 +1,27 @@
+import { toolDefinition } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { Context, Effect, Layer, Schema } from 'effect'
+
+export class Weather extends Context.Service<
+  Weather,
+  { readonly forecast: (city: string) => Effect.Effect<string> }
+>()('Weather') {}
+
+// A fixed forecast. Call a real weather API here.
+export const WeatherLive = Layer.succeed(Weather, {
+  forecast: (city) => Effect.succeed(`Sunny and 22 C in ${city}`),
+})
+
+const getWeatherDef = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the weather forecast for a city',
+  inputSchema: AI.toolSchema(Schema.Struct({ city: Schema.String })),
+  outputSchema: AI.toolSchema(Schema.Struct({ forecast: Schema.String })),
+})
+
+export const getWeather = AI.serverTool(getWeatherDef, ({ city }) =>
+  Effect.gen(function* () {
+    const weather = yield* Weather
+    return { forecast: yield* weather.forecast(city) }
+  }),
+)
diff --git a/examples/react/effect-chat/src/routeTree.gen.ts b/examples/react/effect-chat/src/routeTree.gen.ts
new file mode 100644
index 0000000000..861dc17e2b
--- /dev/null
+++ b/examples/react/effect-chat/src/routeTree.gen.ts
@@ -0,0 +1,86 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiChatRouteImport } from './routes/api.chat'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiChatRoute = ApiChatRouteImport.update({
+  id: '/api/chat',
+  path: '/api/chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/api/chat': typeof ApiChatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/api/chat': typeof ApiChatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/api/chat': typeof ApiChatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/api/chat'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/api/chat'
+  id: '__root__' | '/' | '/api/chat'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ApiChatRoute: typeof ApiChatRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/chat': {
+      id: '/api/chat'
+      path: '/api/chat'
+      fullPath: '/api/chat'
+      preLoaderRoute: typeof ApiChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ApiChatRoute: ApiChatRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}
diff --git a/examples/react/effect-chat/src/router.tsx b/examples/react/effect-chat/src/router.tsx
new file mode 100644
index 0000000000..a595444648
--- /dev/null
+++ b/examples/react/effect-chat/src/router.tsx
@@ -0,0 +1,10 @@
+import { createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export const getRouter = () => {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreloadStaleTime: 0,
+  })
+}
diff --git a/examples/react/effect-chat/src/routes/__root.tsx b/examples/react/effect-chat/src/routes/__root.tsx
new file mode 100644
index 0000000000..ffa2b44701
--- /dev/null
+++ b/examples/react/effect-chat/src/routes/__root.tsx
@@ -0,0 +1,41 @@
+import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
+import appCss from '../styles.css?url'
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'Effect Chat',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+    ],
+  }),
+
+  shellComponent: RootDocument,
+})
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body className="min-h-screen bg-gray-900">
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
diff --git a/examples/react/effect-chat/src/routes/api.chat.ts b/examples/react/effect-chat/src/routes/api.chat.ts
new file mode 100644
index 0000000000..f2e24aa46e
--- /dev/null
+++ b/examples/react/effect-chat/src/routes/api.chat.ts
@@ -0,0 +1,28 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+import { WeatherLive, getWeather } from '@/lib/weather'
+
+export async function POST({ request }: { request: Request }) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+    tools: [getWeather],
+  }).pipe(Stream.provide(WeatherLive))
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+
+export const Route = createFileRoute('/api/chat')({
+  server: {
+    handlers: {
+      POST,
+    },
+  },
+})
diff --git a/examples/react/effect-chat/src/routes/index.tsx b/examples/react/effect-chat/src/routes/index.tsx
new file mode 100644
index 0000000000..2ae2105472
--- /dev/null
+++ b/examples/react/effect-chat/src/routes/index.tsx
@@ -0,0 +1,90 @@
+import { useState } from 'react'
+import { createFileRoute } from '@tanstack/react-router'
+import { fetchServerSentEvents, useChat } from '@tanstack/ai-react'
+
+function ChatPage() {
+  const [input, setInput] = useState('')
+  const { messages, sendMessage, isLoading, error, stop } = useChat({
+    connection: fetchServerSentEvents('/api/chat'),
+    threadId: 'effect-chat',
+  })
+
+  const handleSendMessage = () => {
+    if (!input.trim()) return
+    sendMessage(input.trim())
+    setInput('')
+  }
+
+  return (
+    <div className="mx-auto flex h-screen max-w-2xl flex-col gap-3 p-4 text-white">
+      <div className="flex-1 space-y-3 overflow-y-auto">
+        {messages.length === 0 ? (
+          <p className="text-center text-sm text-gray-400">
+            Ask for the weather in a city.
+          </p>
+        ) : null}
+        {messages.map((message) => (
+          <div key={message.id}>
+            <p className="text-xs text-gray-400">{message.role}</p>
+            {message.parts.map((part, index) => {
+              if (part.type === 'text') {
+                return (
+                  <p key={index} className="whitespace-pre-wrap">
+                    {part.content}
+                  </p>
+                )
+              }
+              if (part.type === 'tool-call') {
+                return (
+                  <p key={index} className="text-sm text-orange-400">
+                    Called {part.name}
+                  </p>
+                )
+              }
+              return null
+            })}
+          </div>
+        ))}
+      </div>
+      {error ? <p className="text-sm text-red-400">{error.message}</p> : null}
+      <div className="flex gap-2">
+        <textarea
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter' && !event.shiftKey) {
+              event.preventDefault()
+              handleSendMessage()
+            }
+          }}
+          placeholder="What is the weather in Oslo?"
+          rows={1}
+          disabled={isLoading}
+          className="flex-1 resize-none rounded-lg border border-gray-700 bg-gray-800 px-3 py-2 text-sm"
+        />
+        {isLoading ? (
+          <button
+            type="button"
+            onClick={stop}
+            className="rounded-lg bg-red-600 px-4 py-2 text-sm"
+          >
+            Stop
+          </button>
+        ) : (
+          <button
+            type="button"
+            onClick={handleSendMessage}
+            disabled={!input.trim()}
+            className="rounded-lg bg-orange-500 px-4 py-2 text-sm disabled:opacity-50"
+          >
+            Send
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export const Route = createFileRoute('/')({
+  component: ChatPage,
+})
diff --git a/examples/react/effect-chat/src/styles.css b/examples/react/effect-chat/src/styles.css
new file mode 100644
index 0000000000..2cd2c65a05
--- /dev/null
+++ b/examples/react/effect-chat/src/styles.css
@@ -0,0 +1,10 @@
+@import 'tailwindcss';
+
+body {
+  @apply m-0;
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu',
+    'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
diff --git a/examples/react/effect-chat/tsconfig.json b/examples/react/effect-chat/tsconfig.json
new file mode 100644
index 0000000000..3fd120cf69
--- /dev/null
+++ b/examples/react/effect-chat/tsconfig.json
@@ -0,0 +1,25 @@
+{
+  "include": ["**/*.ts", "**/*.tsx"],
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "allowJs": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client", "node"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
diff --git a/examples/react/effect-chat/vite.config.ts b/examples/react/effect-chat/vite.config.ts
new file mode 100644
index 0000000000..39ff1b09e2
--- /dev/null
+++ b/examples/react/effect-chat/vite.config.ts
@@ -0,0 +1,19 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { defineConfig } from 'vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import viteReact from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+// Server routes read process.env. Vite does not copy unprefixed .env keys
+// into the SSR process. Load them here. Already-set vars win.
+for (const name of ['.env.local', '.env']) {
+  const path = resolve(import.meta.dirname, name)
+  if (existsSync(path)) process.loadEnvFile(path)
+}
+
+export default defineConfig({
+  resolve: { tsconfigPaths: true },
+  server: { port: 3100 },
+  plugins: [tailwindcss(), tanstackStart(), viteReact()],
+})
diff --git a/packages/ai-effect/README.md b/packages/ai-effect/README.md
new file mode 100644
index 0000000000..ea13804074
--- /dev/null
+++ b/packages/ai-effect/README.md
@@ -0,0 +1,67 @@
+<div align="center">
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://tanstack.com/api/readme/ai.png?theme=dark"
+    />
+    <source
+      media="(prefers-color-scheme: light)"
+      srcset="https://tanstack.com/api/readme/ai.png"
+    />
+    <img
+      src="https://tanstack.com/api/readme/ai.png"
+      alt="TanStack AI"
+      width="900"
+    />
+  </picture>
+</div>
+
+<br />
+
+# @tanstack/ai-effect
+
+Effect 4 bindings for TanStack AI.
+
+- `chat` returns an Effect `Stream` of chunks.
+- `serverTool` makes a tool from a function that returns an Effect. A Layer gives the tool its services.
+- `toolSchema` turns an Effect Schema into a tool schema that works with OpenAI strict mode.
+- Every other activity (images, speech, embeddings, and more) returns an `Effect`, or a `Stream` with `stream: true`.
+- Every failure is a typed `AIError`. Interruption aborts the request to the provider.
+
+## Install
+
+```bash
+npm install @tanstack/ai @tanstack/ai-effect effect
+```
+
+The package needs `effect` 4.1 or later.
+
+## Stream a chat
+
+```ts ignore
+import { chatParamsFromRequest, toServerSentEventsResponse } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { openaiText } from '@tanstack/ai-openai'
+import { Stream } from 'effect'
+
+export async function POST(request: Request) {
+  const params = await chatParamsFromRequest(request)
+
+  const stream = AI.chat({
+    adapter: openaiText('gpt-6.1-sol'),
+    messages: params.messages,
+    threadId: params.threadId,
+    runId: params.runId,
+  })
+
+  return toServerSentEventsResponse(Stream.toAsyncIterable(stream))
+}
+```
+
+## Docs
+
+- [Effect guide](https://tanstack.com/ai/latest/docs/effect/index)
+- [Effect tools](https://tanstack.com/ai/latest/docs/effect/tools)
+- [Effect activities](https://tanstack.com/ai/latest/docs/effect/activities)
+- [Effect Chat tutorial](https://tanstack.com/ai/latest/docs/tutorials/effect-chat)
+- [API reference](https://tanstack.com/ai/latest/docs/api/ai-effect)
diff --git a/packages/ai-effect/package.json b/packages/ai-effect/package.json
new file mode 100644
index 0000000000..740d932671
--- /dev/null
+++ b/packages/ai-effect/package.json
@@ -0,0 +1,52 @@
+{
+  "name": "@tanstack/ai-effect",
+  "version": "0.0.0",
+  "description": "Effect 4 bindings for TanStack AI: every activity as an Effect or Stream, plus Effect server tools.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-effect"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "oxlint src --type-aware --fix",
+    "test:build": "publint --strict",
+    "test:oxlint": "oxlint src --type-aware",
+    "test:coverage": "vitest run --passWithNoTests --coverage --coverage.include='src/**' --coverage.reporter=text-summary --coverage.reporter=json-summary",
+    "test:lib": "vitest --passWithNoTests",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "tanstack",
+    "effect",
+    "stream"
+  ],
+  "peerDependencies": {
+    "@tanstack/ai": "workspace:^",
+    "effect": "^4.1.0"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.1.10",
+    "effect": "^4.1.0"
+  }
+}
diff --git a/packages/ai-effect/src/activities.ts b/packages/ai-effect/src/activities.ts
new file mode 100644
index 0000000000..bfada6c8e0
--- /dev/null
+++ b/packages/ai-effect/src/activities.ts
@@ -0,0 +1,129 @@
+import * as core from '@tanstack/ai'
+import { toEffect, toStream } from './lift'
+import type { Effect, Stream } from 'effect'
+import type {
+  AnyImageAdapter,
+  AnyVideoAdapter,
+  StreamChunk,
+} from '@tanstack/ai'
+import type {
+  ImageActivityOptions,
+  VideoCreateOptions,
+} from '@tanstack/ai/adapters'
+import type { AIError } from './lift'
+
+/** The wrapper owns the signal, so callers cannot pass one. */
+type NoSignal = { abortSignal?: never }
+
+/** A core stream result becomes a `Stream`. A promise result becomes an `Effect`. */
+type Lifted<R> =
+  R extends AsyncIterable<infer C>
+    ? Stream.Stream<C, AIError>
+    : Effect.Effect<Awaited<R>, AIError>
+
+/**
+ * Wraps one core activity. TypeScript carries the core generics over to the
+ * returned function, so per-model option checks still work.
+ */
+const wrap =
+  <O extends { abortSignal?: AbortSignal; stream?: boolean }, R>(
+    run: (options: O) => R,
+  ) =>
+  (options: O & NoSignal) =>
+    // Core types its result as a conditional on `TStream`, so TypeScript cannot pick the branch here. `options.stream` picks it at runtime.
+    (options.stream === true
+      ? toStream(
+          (signal) =>
+            run({
+              ...options,
+              abortSignal: signal,
+            }) as AsyncIterable<StreamChunk>,
+        )
+      : toEffect(
+          (signal) =>
+            run({ ...options, abortSignal: signal }) as Promise<Awaited<R>>,
+        )) as Lifted<R>
+
+/**
+ * Summarizes text. Returns an `Effect` of the summary, or a `Stream` of chunks
+ * with `stream: true`.
+ *
+ * @example
+ * const summary = yield* summarize({ adapter, text })
+ */
+export const summarize = wrap(core.summarize)
+
+/** Orders documents by relevance to a query. Returns an `Effect`. */
+export const rerank = wrap(core.rerank)
+
+/** Asks the model typed questions about a state. Returns an `Effect` of the answers. */
+export const decide = wrap(core.decide)
+
+/**
+ * Generates images. Returns an `Effect` of the result, or a `Stream` of
+ * chunks with `stream: true`. `size` and `modelOptions` are checked against
+ * the adapter's model.
+ *
+ * @example
+ * const { images } = yield* generateImage({ adapter, prompt: 'A red fox' })
+ */
+export const generateImage = <
+  TAdapter extends AnyImageAdapter,
+  TStream extends boolean = false,
+>(
+  options: ImageActivityOptions<TAdapter, TStream> & NoSignal,
+) => wrap(core.generateImage<TAdapter, TStream>)(options)
+
+/** Generates audio. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateAudio = wrap(core.generateAudio)
+
+/**
+ * Starts a video job. Returns an `Effect` of the job, or a `Stream` of the
+ * whole job lifecycle with `stream: true`.
+ */
+export const generateVideo = <
+  TAdapter extends AnyVideoAdapter,
+  TStream extends boolean = false,
+>(
+  options: VideoCreateOptions<TAdapter, TStream> & NoSignal,
+) => wrap(core.generateVideo<TAdapter, TStream>)(options)
+
+/** Reads the status of a video job. Returns an `Effect`. */
+export const getVideoJobStatus = <TAdapter extends AnyVideoAdapter>(
+  options: Parameters<typeof core.getVideoJobStatus<TAdapter>>[0] & NoSignal,
+  // Core does not export the result type, so the declaration file needs this annotation to name it.
+): Lifted<ReturnType<typeof core.getVideoJobStatus<TAdapter>>> =>
+  wrap(core.getVideoJobStatus<TAdapter>)(options)
+
+/** Turns text into speech. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateSpeech = wrap(core.generateSpeech)
+
+/** Lists the voices of a speech adapter's account. Returns an `Effect`. */
+export const listVoices = wrap(core.listVoices)
+
+/** Designs or clones a voice. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateVoice = wrap(core.generateVoice)
+
+/** Turns audio into text. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateTranscription = wrap(core.generateTranscription)
+
+/**
+ * Makes embedding vectors. Returns an `Effect`. Interrupting the fiber aborts
+ * the request.
+ */
+export const embed = wrap(core.embed)
+
+/** Generates a world. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateWorld = wrap(core.generateWorld)
+
+/** Starts a live video session. Returns an `Effect`, or a `Stream` with `stream: true`. */
+export const generateLiveVideo = wrap(core.generateLiveVideo)
+
+/** Uploads a file to the provider. Returns an `Effect` of the file handle. */
+export const uploadFile = wrap(core.uploadFile)
+
+/** Reads the metadata of an uploaded file. Returns an `Effect` of the file handle. */
+export const getFile = wrap(core.getFile)
+
+/** Deletes an uploaded file. Returns an `Effect`. */
+export const deleteFile = wrap(core.deleteFile)
diff --git a/packages/ai-effect/src/chat.ts b/packages/ai-effect/src/chat.ts
new file mode 100644
index 0000000000..4e6f440219
--- /dev/null
+++ b/packages/ai-effect/src/chat.ts
@@ -0,0 +1,295 @@
+import { chat as coreChat } from '@tanstack/ai'
+import { Effect, JsonSchema, Schema, Stream } from 'effect'
+import type {
+  AnyTextAdapter,
+  DefinedAgent,
+  InferSchemaType,
+  InterruptDefinition,
+  SchemaInput,
+  StandardJSONSchemaV1,
+  StreamChunk,
+  ToolDefinition,
+  ToolExecutionContext,
+} from '@tanstack/ai'
+import type { TextActivityOptions } from '@tanstack/ai/adapters'
+import type { Context } from 'effect'
+import { toEffect, toStream } from './lift'
+import type { AIError } from './lift'
+
+type AnyToolDefinition = ToolDefinition<any, any, string, boolean, any>
+
+/**
+ * A server tool whose `execute` returns an Effect. Make it with
+ * `serverTool`. `R` is the services the Effect needs.
+ */
+export interface EffectServerTool<TDef extends AnyToolDefinition, R> {
+  readonly _tag: 'EffectServerTool'
+  readonly def: TDef
+  readonly execute: (
+    input: InferSchemaType<TDef['inputSchema']>,
+    ctx: ToolExecutionContext,
+  ) => Effect.Effect<InferSchemaType<TDef['outputSchema']>, unknown, R>
+}
+
+/**
+ * Makes a server tool from a tool definition and a function that returns an
+ * Effect. Pass it in the `tools` of `chat`. The Effect runs with the services
+ * of the `chat` caller, and stops when the run aborts. A failure goes to the
+ * model as a tool error.
+ *
+ * @example
+ * const getUser = serverTool(getUserDef, ({ id }) =>
+ *   Effect.gen(function* () {
+ *     const db = yield* Db
+ *     return yield* db.findUser(id)
+ *   }),
+ * )
+ */
+export const serverTool = <TDef extends AnyToolDefinition, E, R>(
+  def: TDef,
+  execute: (
+    input: InferSchemaType<TDef['inputSchema']>,
+    ctx: ToolExecutionContext,
+  ) => Effect.Effect<InferSchemaType<TDef['outputSchema']>, E, R>,
+) => {
+  const tool: EffectServerTool<TDef, R> = {
+    _tag: 'EffectServerTool',
+    def,
+    execute,
+  }
+  return tool
+}
+
+const closedJsonSchema =
+  (schema: Schema.Constraint) =>
+  (options: StandardJSONSchemaV1.Options): Record<string, unknown> => {
+    const doc = Schema.toJsonSchemaDocument(schema, {
+      onExcessProperty: 'error',
+    })
+    // Same shape as Effect's own toStandardJSONSchemaV1: no empty defs key,
+    // because OpenAI strict mode rejects `definitions` / `$defs`.
+    if (options.target === 'draft-2020-12') {
+      const hasDefs = Object.keys(doc.definitions).length > 0
+      return {
+        $schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
+        ...doc.schema,
+        ...(hasDefs && { $defs: doc.definitions }),
+      }
+    }
+    const doc07 = JsonSchema.toDocumentDraft07(doc)
+    const hasDefs = Object.keys(doc07.definitions).length > 0
+    return {
+      $schema: JsonSchema.META_SCHEMA_URI_DRAFT_07,
+      ...doc07.schema,
+      ...(hasDefs && { definitions: doc07.definitions }),
+    }
+  }
+
+/**
+ * Turn an Effect Schema into a tool `inputSchema` or `outputSchema`.
+ * Objects are closed (`additionalProperties: false`), so providers such as
+ * OpenAI can use strict mode. `Schema.toStandardJSONSchemaV1` leaves objects
+ * open, which turns strict mode off.
+ *
+ * @example
+ * toolDefinition({
+ *   name: 'get_weather',
+ *   inputSchema: toolSchema(Schema.Struct({ city: Schema.String })),
+ * })
+ */
+export const toolSchema = <S extends Schema.Constraint>(
+  schema: S,
+): StandardJSONSchemaV1<S['Encoded'], S['Type']> => ({
+  '~standard': {
+    version: 1,
+    vendor: 'effect',
+    jsonSchema: {
+      input: closedJsonSchema(schema),
+      output: closedJsonSchema(Schema.toType(schema)),
+    },
+  },
+})
+
+type CoreTool<T> =
+  T extends EffectServerTool<infer TDef, unknown>
+    ? ReturnType<TDef['server']>
+    : T
+
+type CoreTools<TTools> =
+  TTools extends ReadonlyArray<unknown>
+    ? { readonly [K in keyof TTools]: CoreTool<TTools[K]> }
+    : TTools
+
+type ToolServices<TTools> =
+  TTools extends ReadonlyArray<infer TTool>
+    ? TTool extends EffectServerTool<AnyToolDefinition, infer R>
+      ? R
+      : never
+    : never
+
+type CoreToolsOption<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined,
+  TStream extends boolean,
+> = TextActivityOptions<TAdapter, TSchema, TStream, any>['tools']
+
+type CoreChat<
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined,
+  TStream extends boolean,
+  TTools,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+  TContext,
+  TMiddleware extends Array<unknown> | undefined,
+  TAgents extends ReadonlyArray<DefinedAgent>,
+> = typeof coreChat<
+  TAdapter,
+  TSchema,
+  TStream,
+  Extract<CoreTools<TTools>, CoreToolsOption<TAdapter, TSchema, TStream>>,
+  TInterrupts,
+  TContext,
+  TMiddleware,
+  TAgents
+>
+
+type Lift<TResult, R> =
+  TResult extends AsyncIterable<infer TChunk>
+    ? Stream.Stream<TChunk, AIError, R>
+    : Effect.Effect<Awaited<TResult>, AIError, R>
+
+type RuntimeChatOptions = Parameters<typeof coreChat>[0]
+
+type RuntimeTool<R> =
+  | EffectServerTool<AnyToolDefinition, R>
+  | NonNullable<RuntimeChatOptions['tools']>[number]
+
+type RuntimeOptions<R> = Omit<RuntimeChatOptions, 'tools'> & {
+  tools?: ReadonlyArray<RuntimeTool<R>> | undefined
+}
+
+const isEffectServerTool = <R>(
+  tool: RuntimeTool<R>,
+): tool is EffectServerTool<AnyToolDefinition, R> =>
+  '_tag' in tool && tool._tag === 'EffectServerTool'
+
+// Core chat takes an AbortController. toEffect and toStream give a signal.
+const controllerFor = (signal: AbortSignal) => {
+  const controller = new AbortController()
+  signal.addEventListener('abort', () => controller.abort(signal.reason), {
+    once: true,
+  })
+  return controller
+}
+
+// Core picks the result kind at runtime. The public `chat` type mirrors it.
+const runCore: (
+  options: RuntimeChatOptions,
+) => AsyncIterable<StreamChunk> | Promise<unknown> = coreChat
+
+const runChat = <R>(
+  options: RuntimeOptions<R>,
+  context: Context.Context<R>,
+  signal: AbortSignal,
+) =>
+  runCore({
+    ...options,
+    tools: options.tools?.map((tool) =>
+      isEffectServerTool(tool)
+        ? tool.def.server((input, ctx) =>
+            Effect.runPromiseWith(context)(
+              // One core path passes no context. Give the empty one core builds there.
+              tool.execute(input, ctx ?? { emitCustomEvent: () => {} }),
+              { signal: ctx?.abortSignal },
+            ),
+          )
+        : tool,
+    ),
+    abortController: controllerFor(signal),
+  })
+
+/**
+ * Runs core `chat` as an Effect. Takes the options of core `chat`, without
+ * `abortController`: interruption aborts the run. `tools` can also hold
+ * `serverTool` values. Their services join the requirements of the result.
+ *
+ * Returns a `Stream` of chunks by default. With `stream: false` it returns an
+ * `Effect` of the result. With `outputSchema` (and no `stream: true`) it
+ * returns an `Effect` of the parsed object. A throw or a rejection of core
+ * fails with `AIError`.
+ */
+export const chat = <
+  TAdapter extends AnyTextAdapter,
+  TSchema extends SchemaInput | undefined = undefined,
+  TStream extends boolean = boolean,
+  const TTools extends
+    | ReadonlyArray<
+        | EffectServerTool<AnyToolDefinition, unknown>
+        | NonNullable<CoreToolsOption<TAdapter, TSchema, TStream>>[number]
+      >
+    | undefined = undefined,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = [],
+  TContext = unknown,
+  const TMiddleware extends Array<unknown> | undefined = undefined,
+  const TAgents extends ReadonlyArray<DefinedAgent> =
+    ReadonlyArray<DefinedAgent>,
+>(
+  options: Omit<
+    Parameters<
+      CoreChat<
+        TAdapter,
+        TSchema,
+        TStream,
+        TTools,
+        TInterrupts,
+        TContext,
+        TMiddleware,
+        TAgents
+      >
+    >[0],
+    'tools' | 'abortController'
+  > & { tools?: TTools },
+) => {
+  type R = ToolServices<TTools>
+  // The public types above mirror core. At runtime core picks the result kind by this same rule.
+  const runtimeOptions = options as RuntimeOptions<R>
+  const isStream = options.outputSchema
+    ? options.stream === true
+    : options.stream !== false
+  const result = isStream
+    ? Stream.unwrap(
+        Effect.map(Effect.context<R>(), (context) =>
+          toStream(
+            (signal) =>
+              runChat(
+                runtimeOptions,
+                context,
+                signal,
+              ) as AsyncIterable<StreamChunk>,
+          ),
+        ),
+      )
+    : Effect.flatMap(Effect.context<R>(), (context) =>
+        toEffect(
+          (signal) =>
+            runChat(runtimeOptions, context, signal) as Promise<unknown>,
+        ),
+      )
+  return result as Lift<
+    ReturnType<
+      CoreChat<
+        TAdapter,
+        TSchema,
+        TStream,
+        TTools,
+        TInterrupts,
+        TContext,
+        TMiddleware,
+        TAgents
+      >
+    >,
+    R
+  >
+}
diff --git a/packages/ai-effect/src/index.ts b/packages/ai-effect/src/index.ts
new file mode 100644
index 0000000000..8d20fd2921
--- /dev/null
+++ b/packages/ai-effect/src/index.ts
@@ -0,0 +1,22 @@
+export { AIError } from './lift'
+export { chat, serverTool, toolSchema } from './chat'
+export type { EffectServerTool } from './chat'
+export {
+  summarize,
+  rerank,
+  decide,
+  generateImage,
+  generateAudio,
+  generateVideo,
+  getVideoJobStatus,
+  generateSpeech,
+  listVoices,
+  generateVoice,
+  generateTranscription,
+  embed,
+  generateWorld,
+  generateLiveVideo,
+  uploadFile,
+  getFile,
+  deleteFile,
+} from './activities'
diff --git a/packages/ai-effect/src/lift.ts b/packages/ai-effect/src/lift.ts
new file mode 100644
index 0000000000..85dcfe7f6c
--- /dev/null
+++ b/packages/ai-effect/src/lift.ts
@@ -0,0 +1,52 @@
+import { Data, Effect, Stream } from 'effect'
+
+/**
+ * The error of every `@tanstack/ai-effect` call. It wraps a rejection or a
+ * throw from TanStack AI. `cause` holds the original value.
+ */
+export class AIError extends Data.TaggedError('AIError')<{
+  readonly message: string
+  readonly cause: unknown
+}> {}
+
+const toAIError = (cause: unknown) =>
+  new AIError({
+    message: cause instanceof Error ? cause.message : String(cause),
+    cause,
+  })
+
+/**
+ * Turns a promise call into a lazy `Effect`. Each run calls `run` with a new
+ * `AbortSignal`. Interruption aborts that signal. A throw or a rejection
+ * fails the Effect with `AIError`.
+ *
+ * @example
+ * toEffect((signal) => summarize({ adapter, text, abortSignal: signal }))
+ */
+export const toEffect = <A>(run: (signal: AbortSignal) => Promise<A>) =>
+  // The thunk must declare `signal`: tryPromise only makes a controller when the thunk's length is not 0.
+  Effect.tryPromise({ try: (signal) => run(signal), catch: toAIError })
+
+/**
+ * Turns an async iterable call into a lazy `Stream`. Each run calls `run`
+ * with a new `AbortSignal`. The signal aborts when the consumer stops or the
+ * stream ends. A throw fails the Stream with `AIError`. Chunks pass through
+ * as they are, so a `RUN_ERROR` chunk does not fail the Stream.
+ *
+ * @example
+ * toStream((signal) => chat({ adapter, messages, abortSignal: signal }))
+ */
+export const toStream = <C>(run: (signal: AbortSignal) => AsyncIterable<C>) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const controller = yield* Effect.acquireRelease(
+        Effect.sync(() => new AbortController()),
+        (created) => Effect.sync(() => created.abort()),
+      )
+      const iterable = yield* Effect.try({
+        try: () => run(controller.signal),
+        catch: toAIError,
+      })
+      return Stream.fromAsyncIterable(iterable, toAIError)
+    }),
+  )
diff --git a/packages/ai-effect/tests/activities.test.ts b/packages/ai-effect/tests/activities.test.ts
new file mode 100644
index 0000000000..7b0fc54e75
--- /dev/null
+++ b/packages/ai-effect/tests/activities.test.ts
@@ -0,0 +1,418 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Effect, Fiber, Stream } from 'effect'
+import { choice } from '@tanstack/ai'
+import {
+  BaseEmbeddingAdapter,
+  BaseImageAdapter,
+  BaseVideoAdapter,
+} from '@tanstack/ai/adapters'
+import {
+  decide,
+  deleteFile,
+  embed,
+  generateAudio,
+  generateImage,
+  generateLiveVideo,
+  generateSpeech,
+  generateTranscription,
+  generateVideo,
+  generateVoice,
+  generateWorld,
+  getFile,
+  getVideoJobStatus,
+  listVoices,
+  rerank,
+  summarize,
+  uploadFile,
+} from '../src/activities'
+import type {
+  AudioAdapter,
+  EmbeddingOptions,
+  EmbeddingResult,
+  EvaluateAdapter,
+  FilesAdapter,
+  ImageGenerationResult,
+  LiveVideoAdapter,
+  RerankAdapter,
+  StreamChunk,
+  SummarizeAdapter,
+  TTSAdapter,
+  TranscriptionAdapter,
+  VoiceAdapter,
+  WorldAdapter,
+} from '@tanstack/ai'
+import type { AIError } from '../src/lift'
+
+const usage = { promptTokens: 1, completionTokens: 1, totalTokens: 2 }
+const types = { providerOptions: {} }
+const threadId = 'thread-1'
+const run = <A>(effect: Effect.Effect<A, AIError>) => Effect.runPromise(effect)
+
+const imageResult: ImageGenerationResult = {
+  id: 'img-1',
+  model: 'm',
+  images: [{ url: 'https://example.com/fox.png' }],
+}
+
+class FakeImage extends BaseImageAdapter<
+  'm',
+  object,
+  { m: object },
+  { m: '1024x1024' }
+> {
+  readonly name = 'fake'
+  constructor() {
+    super('m')
+  }
+  generateImages() {
+    return Promise.resolve(imageResult)
+  }
+}
+
+class FakeVideo extends BaseVideoAdapter<'m'> {
+  readonly name = 'fake'
+  constructor() {
+    super({}, 'm')
+  }
+  createVideoJob() {
+    return Promise.resolve({ jobId: 'job-1', model: 'm' })
+  }
+  getVideoStatus(jobId: string) {
+    return Promise.resolve({ jobId, status: 'processing' as const })
+  }
+  getVideo(jobId: string) {
+    return Promise.resolve({ jobId, url: 'https://example.com/v.mp4' })
+  }
+}
+
+class HangingEmbed extends BaseEmbeddingAdapter<'m'> {
+  readonly name = 'fake'
+  seen: AbortSignal | undefined
+  markStarted = () => {}
+  started = new Promise<void>((resolve) => {
+    this.markStarted = resolve
+  })
+  constructor() {
+    super('m')
+  }
+  createEmbeddings(options: EmbeddingOptions): Promise<EmbeddingResult> {
+    this.seen = options.abortSignal
+    this.markStarted()
+    return new Promise(() => {})
+  }
+}
+
+const files: FilesAdapter<'fake'> & { kind: 'files' } = {
+  kind: 'files',
+  name: 'fake',
+  upload: () =>
+    Promise.resolve({ id: 'file-1', provider: 'fake', mimeType: 'image/png' }),
+  get: (id) => Promise.resolve({ id, provider: 'fake' }),
+  delete: () => Promise.resolve(),
+}
+
+describe('generateImage', () => {
+  it('returns the core result as an Effect', async () => {
+    const result = await run(
+      generateImage({
+        adapter: new FakeImage(),
+        prompt: 'A red fox',
+        threadId,
+      }),
+    )
+
+    expect(result).toEqual({
+      id: 'img-1',
+      model: 'm',
+      images: [{ url: 'https://example.com/fox.png' }],
+    })
+  })
+
+  it('with stream: true returns a Stream of chunks', async () => {
+    const chunks = await Effect.runPromise(
+      Stream.runCollect(
+        generateImage({
+          adapter: new FakeImage(),
+          prompt: 'A red fox',
+          threadId,
+          stream: true,
+        }),
+      ),
+    )
+
+    const result = chunks.find(
+      (chunk) => chunk.type === 'CUSTOM' && chunk.name === 'generation:result',
+    )
+    expect(result).toMatchObject({ value: { id: 'img-1' } })
+    expect(chunks.at(-1)?.type).toBe('RUN_FINISHED')
+  })
+
+  it('keeps the core types: Effect by default, Stream with stream: true', () => {
+    const adapter = new FakeImage()
+
+    expectTypeOf(
+      generateImage({ adapter, prompt: 'x', threadId }),
+    ).toEqualTypeOf<Effect.Effect<ImageGenerationResult, AIError>>()
+    expectTypeOf(
+      generateImage({ adapter, prompt: 'x', threadId, stream: true }),
+    ).toEqualTypeOf<Stream.Stream<StreamChunk, AIError>>()
+    // @ts-expect-error the size is not one of the model's sizes
+    generateImage({ adapter, prompt: 'x', threadId, size: '512x512' })
+    generateImage({
+      adapter,
+      prompt: 'x',
+      threadId,
+      // @ts-expect-error the wrapper owns the abort signal
+      abortSignal: AbortSignal.abort(),
+    })
+  })
+})
+
+describe('embed', () => {
+  it('passes the abort signal to the adapter', async () => {
+    const adapter = new HangingEmbed()
+    const fiber = Effect.runFork(embed({ adapter, input: 'hello' }))
+    await adapter.started
+
+    await Effect.runPromise(Fiber.interrupt(fiber))
+
+    expect(adapter.seen?.aborted).toBe(true)
+  })
+})
+
+describe('smoke: each wrapper calls its core activity', () => {
+  it('summarize', async () => {
+    const adapter: SummarizeAdapter<'m', object> = {
+      kind: 'summarize',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      summarize: () =>
+        Promise.resolve({ id: 's-1', model: 'm', summary: 'short', usage }),
+    }
+
+    const result = await run(
+      summarize({ adapter, text: 'a long text', threadId }),
+    )
+
+    expect(result.summary).toBe('short')
+  })
+
+  it('rerank', async () => {
+    const adapter: RerankAdapter<'m', object> = {
+      kind: 'rerank',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      rerank: () =>
+        Promise.resolve({
+          id: 'r-1',
+          ranking: [
+            { index: 1, score: 0.9 },
+            { index: 0, score: 0.1 },
+          ],
+          usage,
+        }),
+    }
+
+    const result = await run(
+      rerank({ adapter, query: 'fox', documents: ['cat', 'fox'] }),
+    )
+
+    expect(result.rerankedDocuments).toEqual(['fox', 'cat'])
+  })
+
+  it('decide', async () => {
+    const adapter: EvaluateAdapter<'m', object> = {
+      kind: 'evaluate',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      evaluate: () =>
+        Promise.resolve({
+          model: 'm',
+          answers: {
+            kind: {
+              type: 'choice',
+              choice: 'a',
+              probabilities: { a: 1 },
+              confidence: 1,
+            },
+          },
+          usage,
+        }),
+    }
+
+    const result = await run(
+      decide({
+        adapter,
+        state: { text: 'hi' },
+        questions: {
+          kind: choice({ instructions: 'Pick one', options: { a: 'A' } }),
+        },
+      }),
+    )
+
+    expect(result.kind.value).toBe('a')
+  })
+
+  it('generateAudio', async () => {
+    const adapter: AudioAdapter<'m', object> = {
+      kind: 'audio',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      generateAudio: () =>
+        Promise.resolve({
+          id: 'a-1',
+          model: 'm',
+          audio: { url: 'https://example.com/a.mp3' },
+        }),
+    }
+
+    const result = await run(
+      generateAudio({ adapter, prompt: 'rain', threadId }),
+    )
+
+    expect(result.audio).toEqual({ url: 'https://example.com/a.mp3' })
+  })
+
+  it('generateVideo and getVideoJobStatus', async () => {
+    const adapter = new FakeVideo()
+
+    const job = await run(
+      generateVideo({ adapter, prompt: 'A fox runs', threadId }),
+    )
+    const status = await run(
+      getVideoJobStatus({ adapter, jobId: job.jobId, threadId }),
+    )
+
+    expect(job.jobId).toBe('job-1')
+    expect(status).toMatchObject({ jobId: 'job-1', status: 'processing' })
+  })
+
+  it('generateSpeech and listVoices', async () => {
+    const adapter: TTSAdapter<'m', object> = {
+      kind: 'tts',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      generateSpeech: () =>
+        Promise.resolve({
+          id: 't-1',
+          model: 'm',
+          audio: 'AAAA',
+          format: 'mp3',
+        }),
+      listVoices: () =>
+        Promise.resolve({ voices: [{ voiceId: 'v-1', name: 'Ada' }] }),
+    }
+
+    const speech = await run(
+      generateSpeech({ adapter, text: 'Hello', threadId }),
+    )
+    const { voices } = await run(listVoices({ adapter }))
+
+    expect(speech.audio).toBe('AAAA')
+    expect(voices).toEqual([{ voiceId: 'v-1', name: 'Ada' }])
+  })
+
+  it('generateVoice', async () => {
+    const adapter: VoiceAdapter<'m', object> = {
+      kind: 'voice',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      generateVoice: () =>
+        Promise.resolve({ id: 'vo-1', model: 'm', voices: [] }),
+    }
+
+    const result = await run(
+      generateVoice({ adapter, prompt: 'A calm voice', threadId }),
+    )
+
+    expect(result.id).toBe('vo-1')
+  })
+
+  it('generateTranscription', async () => {
+    const adapter: TranscriptionAdapter<'m', object> = {
+      kind: 'transcription',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      transcribe: () =>
+        Promise.resolve({ id: 'tr-1', model: 'm', text: 'hello world' }),
+    }
+
+    const result = await run(
+      generateTranscription({ adapter, audio: 'AAAA', threadId }),
+    )
+
+    expect(result.text).toBe('hello world')
+  })
+
+  it('generateWorld', async () => {
+    const adapter: WorldAdapter<'m', object> = {
+      kind: 'world',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      createWorld: () =>
+        Promise.resolve({
+          id: 'w-1',
+          model: 'm',
+          prompt: 'a forest',
+          status: 'ready',
+        }),
+    }
+
+    const result = await run(
+      generateWorld({ adapter, prompt: 'a forest', threadId }),
+    )
+
+    expect(result.id).toBe('w-1')
+  })
+
+  it('generateLiveVideo', async () => {
+    const adapter: LiveVideoAdapter<'m', object> = {
+      kind: 'liveVideo',
+      name: 'fake',
+      model: 'm',
+      '~types': types,
+      createLiveVideo: () =>
+        Promise.resolve({
+          id: 'l-1',
+          model: 'm',
+          token: 'tok',
+          expiresAt: 1,
+          prompt: 'a city',
+          status: 'ready',
+        }),
+    }
+
+    const result = await run(
+      generateLiveVideo({ adapter, prompt: 'a city', threadId }),
+    )
+
+    expect(result.token).toBe('tok')
+  })
+
+  it('uploadFile, getFile and deleteFile', async () => {
+    const handle = await run(
+      uploadFile({
+        adapter: files,
+        input: { data: 'AAAA', mimeType: 'image/png' },
+      }),
+    )
+    const fetched = await run(getFile({ adapter: files, id: handle }))
+    const deleted = await run(deleteFile({ adapter: files, id: handle }))
+
+    expect(handle).toEqual({
+      id: 'file-1',
+      provider: 'fake',
+      mimeType: 'image/png',
+    })
+    expect(fetched).toEqual({ id: 'file-1', provider: 'fake' })
+    expect(deleted).toBeUndefined()
+  })
+})
diff --git a/packages/ai-effect/tests/chat.test.ts b/packages/ai-effect/tests/chat.test.ts
new file mode 100644
index 0000000000..614a64be8a
--- /dev/null
+++ b/packages/ai-effect/tests/chat.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Context, Effect, Fiber, Layer, Schema, Stream } from 'effect'
+import { toolDefinition } from '@tanstack/ai'
+import { fakeText } from '@tanstack/ai/testing'
+import { chat, serverTool, toolSchema } from '../src/chat'
+import type { ChatResult, ModelMessage, StreamChunk } from '@tanstack/ai'
+import type { FakeResponseStep } from '@tanstack/ai/testing'
+import type { AIError } from '../src/lift'
+
+class Db extends Context.Service<
+  Db,
+  { readonly cityOf: (id: string) => Effect.Effect<string> }
+>()('Db') {}
+
+const DbLive = Layer.succeed(Db, {
+  cityOf: (id) => Effect.succeed(`city-of-${id}`),
+})
+
+const cityDef = toolDefinition({
+  name: 'getCity',
+  description: 'Get the city of a user',
+  inputSchema: toolSchema(Schema.Struct({ id: Schema.String })),
+  outputSchema: toolSchema(Schema.Struct({ city: Schema.String })),
+})
+
+const callGetCity: FakeResponseStep = {
+  toolCalls: [{ name: 'getCity', input: { id: 'u1' } }],
+}
+
+const messages: Array<ModelMessage> = [{ role: 'user', content: 'Hi' }]
+
+function fakeWith(responses: Array<FakeResponseStep>) {
+  const adapter = fakeText()
+  adapter.setResponses(responses)
+  return adapter
+}
+
+/** A response step that keeps the request it answers. */
+function recordRequest(text: string) {
+  const seen: { messages?: Array<ModelMessage>; signal?: AbortSignal } = {}
+  const step: FakeResponseStep = ({ request }) => {
+    seen.messages = request.messages
+    seen.signal = request.request?.signal ?? request.abortController?.signal
+    return { text }
+  }
+  return { step, seen }
+}
+
+function textOf(chunks: ReadonlyArray<StreamChunk>) {
+  return chunks
+    .flatMap((chunk) =>
+      chunk.type === 'TEXT_MESSAGE_CONTENT' ? [chunk.delta] : [],
+    )
+    .join('')
+}
+
+function toolMessageOf(sent: Array<ModelMessage> | undefined) {
+  return sent?.find((message) => message.role === 'tool')?.content
+}
+
+describe('chat', () => {
+  it('streams chunks from the adapter', async () => {
+    const adapter = fakeWith([{ text: 'Hello world' }])
+
+    const chunks = await Effect.runPromise(
+      Stream.runCollect(chat({ adapter, messages, threadId: 't1' })),
+    )
+
+    expect(textOf(chunks)).toBe('Hello world')
+    expect(chunks.at(-1)?.type).toBe('RUN_FINISHED')
+  })
+
+  it('with stream: false returns the text as an Effect', async () => {
+    const adapter = fakeWith([{ text: 'Hello world' }])
+
+    const result = await Effect.runPromise(
+      chat({ adapter, messages, threadId: 't1', stream: false }),
+    )
+
+    expect(result.text).toBe('Hello world')
+  })
+
+  it('with outputSchema returns the parsed object', async () => {
+    const adapter = fakeWith([{ text: '{"city":"Oslo"}' }])
+
+    const result = await Effect.runPromise(
+      chat({
+        adapter,
+        messages,
+        threadId: 't1',
+        outputSchema: Schema.toStandardJSONSchemaV1(
+          Schema.Struct({ city: Schema.String }),
+        ),
+      }),
+    )
+
+    expect(result).toEqual({ city: 'Oslo' })
+  })
+
+  it('Effect tool reads a service provided with a Layer', async () => {
+    const { step, seen } = recordRequest('done')
+    const adapter = fakeWith([callGetCity, step])
+    const getCity = serverTool(cityDef, ({ id }) =>
+      Effect.gen(function* () {
+        const db = yield* Db
+        return { city: yield* db.cityOf(id) }
+      }),
+    )
+
+    const chunks = await Effect.runPromise(
+      Stream.runCollect(
+        chat({ adapter, messages, threadId: 't1', tools: [getCity] }),
+      ).pipe(Effect.provide(DbLive)),
+    )
+
+    expect(JSON.parse(String(toolMessageOf(seen.messages)))).toEqual({
+      city: 'city-of-u1',
+    })
+    expect(textOf(chunks)).toBe('done')
+  })
+
+  it.each([
+    ['a typed failure', Effect.fail(new Error('db is down'))],
+    ['a defect', Effect.die(new Error('db is down'))],
+  ])(
+    'Effect tool failure (%s) reaches the model as a tool error and the run finishes',
+    async (_name, failure) => {
+      const { step, seen } = recordRequest('sorry')
+      const adapter = fakeWith([callGetCity, step])
+      const getCity = serverTool(cityDef, () => failure)
+
+      const chunks = await Effect.runPromise(
+        Stream.runCollect(
+          chat({ adapter, messages, threadId: 't1', tools: [getCity] }),
+        ),
+      )
+
+      expect(String(toolMessageOf(seen.messages))).toContain('db is down')
+      expect(textOf(chunks)).toBe('sorry')
+      expect(chunks.at(-1)?.type).toBe('RUN_FINISHED')
+    },
+  )
+
+  it('stopping the stream early aborts the run', async () => {
+    const { step, seen } = recordRequest('a long answer in many chunks')
+    const adapter = fakeWith([step])
+
+    const chunks = await Effect.runPromise(
+      Stream.runCollect(
+        chat({ adapter, messages, threadId: 't1' }).pipe(
+          Stream.filter((chunk) => chunk.type === 'TEXT_MESSAGE_CONTENT'),
+          Stream.take(1),
+        ),
+      ),
+    )
+
+    expect(textOf(chunks)).toBe('a lo')
+    expect(seen.signal?.aborted).toBe(true)
+  })
+
+  it('aborting during an Effect tool interrupts the tool fiber', async () => {
+    const adapter = fakeWith([callGetCity, { text: 'never sent' }])
+    let markStarted = () => {}
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve
+    })
+    let markInterrupted = () => {}
+    const interrupted = new Promise<void>((resolve) => {
+      markInterrupted = resolve
+    })
+    const getCity = serverTool(cityDef, () =>
+      Effect.sync(markStarted).pipe(
+        Effect.andThen(Effect.never),
+        Effect.onInterrupt(() => Effect.sync(markInterrupted)),
+      ),
+    )
+    const fiber = Effect.runFork(
+      Stream.runDrain(
+        chat({ adapter, messages, threadId: 't1', tools: [getCity] }),
+      ),
+    )
+    await started
+
+    await Effect.runPromise(Fiber.interrupt(fiber))
+
+    await expect(interrupted).resolves.toBeUndefined()
+  })
+
+  it('types: R is the services of the Effect tools, and stream: false gives an Effect', () => {
+    const adapter = fakeText()
+    const getCity = serverTool(cityDef, ({ id }) =>
+      Effect.gen(function* () {
+        const db = yield* Db
+        return { city: yield* db.cityOf(id) }
+      }),
+    )
+    const withTool = chat({
+      adapter,
+      messages,
+      threadId: 't1',
+      tools: [getCity],
+    })
+    const plain = chat({ adapter, messages, threadId: 't1' })
+    const whole = chat({ adapter, messages, threadId: 't1', stream: false })
+
+    expectTypeOf<Stream.Services<typeof withTool>>().toEqualTypeOf<Db>()
+    expectTypeOf<Stream.Services<typeof plain>>().toEqualTypeOf<never>()
+    expectTypeOf<Stream.Error<typeof plain>>().toEqualTypeOf<AIError>()
+    expectTypeOf(whole).toEqualTypeOf<
+      Effect.Effect<ChatResult, AIError, never>
+    >()
+  })
+})
+
+describe('toolSchema', () => {
+  const input = toolSchema(
+    Schema.Struct({
+      id: Schema.String,
+      address: Schema.Struct({ zip: Schema.String }),
+    }),
+  )
+
+  it('closes every object in draft-07, so strict mode stays on', () => {
+    expect(input['~standard'].jsonSchema.input({ target: 'draft-07' })).toEqual(
+      {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          address: {
+            type: 'object',
+            properties: { zip: { type: 'string' } },
+            required: ['zip'],
+            additionalProperties: false,
+          },
+        },
+        required: ['id', 'address'],
+        additionalProperties: false,
+      },
+    )
+  })
+
+  it('closes objects in draft-2020-12 too', () => {
+    expect(
+      input['~standard'].jsonSchema.input({ target: 'draft-2020-12' }),
+    ).toMatchObject({
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      additionalProperties: false,
+    })
+  })
+
+  it('keeps the tool input typed', () => {
+    serverTool(cityDef, (args) => {
+      expectTypeOf(args).toEqualTypeOf<{ readonly id: string }>()
+      return Effect.succeed({ city: 'Oslo' })
+    })
+  })
+})
diff --git a/packages/ai-effect/tests/lift.test.ts b/packages/ai-effect/tests/lift.test.ts
new file mode 100644
index 0000000000..a608c80ca6
--- /dev/null
+++ b/packages/ai-effect/tests/lift.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import { Effect, Fiber, Stream } from 'effect'
+import { AIError, toEffect, toStream } from '../src/lift'
+
+type Chunk = { type: string; delta?: string }
+
+const failureOf = <A>(effect: Effect.Effect<A, AIError>) =>
+  Effect.runPromise(Effect.flip(effect))
+
+const collect = <C>(stream: Stream.Stream<C, AIError>) =>
+  Effect.runPromise(Stream.runCollect(stream))
+
+describe('toEffect', () => {
+  it('resolves the promise value', async () => {
+    const value = await Effect.runPromise(toEffect(() => Promise.resolve(42)))
+
+    expect(value).toBe(42)
+  })
+
+  it('maps a rejection to AIError with the cause', async () => {
+    const error = await failureOf(toEffect(() => Promise.reject('nope')))
+
+    expect(error).toBeInstanceOf(AIError)
+    expect(error.message).toBe('nope')
+    expect(error.cause).toBe('nope')
+  })
+
+  it('maps a sync throw from run to AIError', async () => {
+    const thrown = new Error('threadId is empty')
+    const error = await failureOf(
+      toEffect(() => {
+        throw thrown
+      }),
+    )
+
+    expect(error._tag).toBe('AIError')
+    expect(error.message).toBe('threadId is empty')
+    expect(error.cause).toBe(thrown)
+  })
+
+  it('interruption aborts the signal', async () => {
+    let seen: AbortSignal | undefined
+    let markStarted = () => {}
+    const started = new Promise<void>((resolve) => {
+      markStarted = resolve
+    })
+    const fiber = Effect.runFork(
+      toEffect((signal) => {
+        seen = signal
+        markStarted()
+        return new Promise<never>(() => {})
+      }),
+    )
+    await started
+
+    await Effect.runPromise(Fiber.interrupt(fiber))
+
+    expect(seen?.aborted).toBe(true)
+  })
+
+  it('running the same Effect twice calls run twice with two different signals', async () => {
+    const signals: Array<AbortSignal> = []
+    const effect = toEffect((signal) => {
+      signals.push(signal)
+      return Promise.resolve('ok')
+    })
+
+    await Effect.runPromise(effect)
+    await Effect.runPromise(effect)
+
+    expect(signals).toHaveLength(2)
+    expect(signals[0]).not.toBe(signals[1])
+  })
+})
+
+describe('toStream', () => {
+  it('emits every chunk, including a RUN_ERROR chunk, and does not fail', async () => {
+    const chunks: Array<Chunk> = [
+      { type: 'TEXT_MESSAGE_CONTENT', delta: 'Hi' },
+      { type: 'RUN_ERROR' },
+      { type: 'RUN_FINISHED' },
+    ]
+    async function* run() {
+      yield* chunks
+    }
+
+    const out = await collect(toStream(run))
+
+    expect(out).toEqual([
+      { type: 'TEXT_MESSAGE_CONTENT', delta: 'Hi' },
+      { type: 'RUN_ERROR' },
+      { type: 'RUN_FINISHED' },
+    ])
+  })
+
+  it('maps an iterator throw to AIError', async () => {
+    const thrown = new Error('socket closed')
+    async function* run() {
+      yield { type: 'TEXT_MESSAGE_CONTENT', delta: 'Hi' }
+      throw thrown
+    }
+
+    const error = await failureOf(Stream.runCollect(toStream(run)))
+
+    expect(error).toBeInstanceOf(AIError)
+    expect(error.message).toBe('socket closed')
+    expect(error.cause).toBe(thrown)
+  })
+
+  it('early stop (Stream.take) aborts the signal', async () => {
+    let seen: AbortSignal | undefined
+    async function* run(signal: AbortSignal) {
+      seen = signal
+      while (true) yield { type: 'TEXT_MESSAGE_CONTENT', delta: 'x' }
+    }
+
+    const out = await collect(toStream(run).pipe(Stream.take(1)))
+
+    expect(out).toEqual([{ type: 'TEXT_MESSAGE_CONTENT', delta: 'x' }])
+    expect(seen?.aborted).toBe(true)
+  })
+})
diff --git a/packages/ai-effect/tsconfig.json b/packages/ai-effect/tsconfig.json
new file mode 100644
index 0000000000..29112eff9f
--- /dev/null
+++ b/packages/ai-effect/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["vite.config.ts", "./src", "./tests"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/ai-effect/vite.config.ts b/packages/ai-effect/vite.config.ts
new file mode 100644
index 0000000000..1f3542380f
--- /dev/null
+++ b/packages/ai-effect/vite.config.ts
@@ -0,0 +1,35 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import { tanstackViteConfig } from '@tanstack/vite-config'
+import packageJson from './package.json'
+
+const config = defineConfig({
+  test: {
+    name: packageJson.name,
+    dir: './',
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.test.ts', 'tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'tests/',
+        '**/*.test.ts',
+        '**/*.config.ts',
+      ],
+      include: ['src/**/*.ts'],
+    },
+  },
+})
+
+export default mergeConfig(
+  config,
+  tanstackViteConfig({
+    entry: ['./src/index.ts'],
+    srcDir: './src',
+    cjs: false,
+  }),
+)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ab05f09fb6..071fcf637a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -328,6 +328,64 @@ importers:
         specifier: ^8.2.1
         version: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  examples/react/effect-chat:
+    dependencies:
+      '@tailwindcss/vite':
+        specifier: ^4.1.18
+        version: 4.1.18(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../../../packages/ai
+      '@tanstack/ai-effect':
+        specifier: workspace:*
+        version: link:../../../packages/ai-effect
+      '@tanstack/ai-openai':
+        specifier: workspace:*
+        version: link:../../../packages/ai-openai
+      '@tanstack/ai-react':
+        specifier: workspace:*
+        version: link:../../../packages/ai-react
+      '@tanstack/react-router':
+        specifier: ^1.170.41
+        version: 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/react-start':
+        specifier: ^1.168.60
+        version: 1.168.60(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/router-plugin':
+        specifier: ^1.168.42
+        version: 1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      effect:
+        specifier: ^4.1.0
+        version: 4.1.2
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.2.3
+        version: 19.2.3(react@19.2.3)
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.1.18
+    devDependencies:
+      '@types/node':
+        specifier: ^24.10.1
+        version: 24.13.6
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.3.0
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.3.0)
+      '@vitejs/plugin-react':
+        specifier: ^6.2.1
+        version: 6.2.1(babel-plugin-react-compiler@1.0.0)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      typescript:
+        specifier: 5.9.3
+        version: 5.9.3
+      vite:
+        specifier: ^8.2.1
+        version: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+
   examples/react/evaluate:
     dependencies:
       '@tailwindcss/vite':
@@ -2676,6 +2734,18 @@ importers:
         specifier: 4.1.10
         version: 4.1.10(vitest@4.1.11)
 
+  packages/ai-effect:
+    devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@vitest/coverage-v8':
+        specifier: 4.1.10
+        version: 4.1.10(vitest@4.1.11)
+      effect:
+        specifier: ^4.1.0
+        version: 4.1.2
+
   packages/ai-elevenlabs:
     dependencies:
       '@elevenlabs/client':
@@ -4033,6 +4103,9 @@ importers:
       '@tanstack/ai-computer-use':
         specifier: workspace:*
         version: link:../../packages/ai-computer-use
+      '@tanstack/ai-effect':
+        specifier: workspace:*
+        version: link:../../packages/ai-effect
       '@tanstack/ai-elevenlabs':
         specifier: workspace:*
         version: link:../../packages/ai-elevenlabs
@@ -4129,6 +4202,9 @@ importers:
       arktype:
         specifier: ^2.1.28
         version: 2.2.0
+      effect:
+        specifier: ^4.1.0
+        version: 4.1.2
       react:
         specifier: ^19.2.3
         version: 19.2.3
@@ -14087,6 +14163,9 @@ packages:
   effect@3.20.0:
     resolution: {integrity: sha512-qMLfDJscrNG8p/aw+IkT9W7fgj50Z4wG5bLBy0Txsxz8iUHjDIkOgO3SV0WZfnQbNG2VJYb0b+rDLMrhM4+Krw==}
 
+  effect@4.1.2:
+    resolution: {integrity: sha512-d3Oah1WyKxFLFh19yWheS5IXIVaITzxZ71JkE1rkUozq/6EcJSU5nPk5bF2QrSygZ3SQoiNQB8TsxFriyMeMaQ==}
+
   ejs@5.0.1:
     resolution: {integrity: sha512-COqBPFMxuPTPspXl2DkVYaDS3HtrD1GpzOGkNTJ1IYkifq/r9h8SVEFrjA3D9/VJGOEoMQcrlhpntcSUrM8k6A==}
     engines: {node: '>=0.12.18'}
@@ -15173,6 +15252,7 @@ packages:
   image-size@0.5.5:
     resolution: {integrity: sha512-6TDAlDPZxUFCv+fuOkIoXT/V/f3Qbq8e37p+YOiYrUv3v9cc3/6x78VdfPgFVaB9dZYeLUfKgHRebpkm/oP2VQ==}
     engines: {node: '>=0.10.0'}
+    deprecated: Please migrate to image-size@2.x
     hasBin: true
 
   image-size@1.2.1:
@@ -28527,6 +28607,13 @@ snapshots:
       tailwindcss: 4.1.18
       vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  '@tailwindcss/vite@4.1.18(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@tailwindcss/node': 4.1.18
+      '@tailwindcss/oxide': 4.1.18
+      tailwindcss: 4.1.18
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+
   '@tanstack/db-ivm@0.1.18(typescript@5.9.3)':
     dependencies:
       fractional-indexing: 3.2.0
@@ -28952,6 +29039,32 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/react-start-rsc@0.1.59(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@tanstack/react-router': 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/router-core': 1.171.34
+      '@tanstack/router-utils': 1.162.3
+      '@tanstack/start-client-core': 1.170.34
+      '@tanstack/start-fn-stubs': 1.162.0
+      '@tanstack/start-plugin-core': 1.171.49(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/start-storage-context': 1.167.36
+      pathe: 2.0.3
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    transitivePeerDependencies:
+      - '@farmfe/core'
+      - '@rsbuild/core'
+      - bun-types-no-globals
+      - crossws
+      - esbuild
+      - rolldown
+      - rollup
+      - supports-color
+      - unloader
+      - vite
+      - vite-plugin-solid
+      - webpack
+
   '@tanstack/react-start-server@1.167.46(crossws@0.4.6(srvx@0.11.17))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@tanstack/react-router': 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -29059,6 +29172,35 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/react-start@1.168.60(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@tanstack/react-router': 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/react-start-client': 1.168.39(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/react-start-rsc': 0.1.59(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/react-start-server': 1.167.46(crossws@0.4.6(srvx@0.11.22))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@tanstack/router-utils': 1.162.3
+      '@tanstack/start-client-core': 1.170.34
+      '@tanstack/start-plugin-core': 1.171.49(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/start-server-core': 1.169.39(crossws@0.4.6(srvx@0.11.22))
+      pathe: 2.0.3
+      react: 19.2.3
+      react-dom: 19.2.3(react@19.2.3)
+    optionalDependencies:
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - '@farmfe/core'
+      - '@rspack/core'
+      - bun-types-no-globals
+      - crossws
+      - esbuild
+      - react-server-dom-rspack
+      - rolldown
+      - rollup
+      - supports-color
+      - unloader
+      - vite-plugin-solid
+      - webpack
+
   '@tanstack/react-store@0.11.2(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@tanstack/store': 0.11.2
@@ -29155,6 +29297,31 @@ snapshots:
       - supports-color
       - unloader
 
+  '@tanstack/router-plugin@1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@babel/core': 7.29.7(supports-color@7.2.0)
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.8
+      '@tanstack/router-core': 1.171.34
+      '@tanstack/router-generator': 1.167.40
+      '@tanstack/router-utils': 1.162.3
+      chokidar: 5.0.0
+      unplugin: 3.4.0(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      zod: 4.6.5
+    optionalDependencies:
+      '@tanstack/react-router': 1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+      vite-plugin-solid: 2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+    transitivePeerDependencies:
+      - '@farmfe/core'
+      - '@rspack/core'
+      - bun-types-no-globals
+      - esbuild
+      - rolldown
+      - rollup
+      - supports-color
+      - unloader
+
   '@tanstack/router-ssr-query-core@1.141.1(@tanstack/query-core@5.90.12)(@tanstack/router-core@1.171.34)':
     dependencies:
       '@tanstack/query-core': 5.90.12
@@ -29398,6 +29565,45 @@ snapshots:
       - vite-plugin-solid
       - webpack
 
+  '@tanstack/start-plugin-core@1.171.49(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(crossws@0.4.6(srvx@0.11.22))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/core': 7.29.7(supports-color@7.2.0)
+      '@babel/types': 7.29.8
+      '@jridgewell/remapping': 2.3.5
+      '@tanstack/router-core': 1.171.34
+      '@tanstack/router-generator': 1.167.40
+      '@tanstack/router-plugin': 1.168.42(@tanstack/react-router@1.170.41(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)))(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      '@tanstack/router-utils': 1.162.3
+      '@tanstack/start-server-core': 1.169.39(crossws@0.4.6(srvx@0.11.22))
+      exsolve: 1.1.1
+      lightningcss: 1.33.0
+      pathe: 2.0.3
+      picomatch: 4.0.7
+      seroval: 1.6.7
+      source-map: 0.7.6
+      srvx: 0.11.22
+      tinyglobby: 0.2.17
+      ufo: 1.6.4
+      vitefu: 1.1.3(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+      xmlbuilder2: 4.0.3
+      zod: 4.6.5
+    optionalDependencies:
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+    transitivePeerDependencies:
+      - '@farmfe/core'
+      - '@rspack/core'
+      - '@tanstack/react-router'
+      - bun-types-no-globals
+      - crossws
+      - esbuild
+      - rolldown
+      - rollup
+      - supports-color
+      - unloader
+      - vite-plugin-solid
+      - webpack
+
   '@tanstack/start-server-core@1.169.39(crossws@0.4.6(srvx@0.11.17))':
     dependencies:
       '@tanstack/history': 1.162.4
@@ -30205,6 +30411,13 @@ snapshots:
     optionalDependencies:
       babel-plugin-react-compiler: 1.0.0
 
+  '@vitejs/plugin-react@6.2.1(babel-plugin-react-compiler@1.0.0)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))':
+    dependencies:
+      '@rolldown/pluginutils': 1.0.1
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+    optionalDependencies:
+      babel-plugin-react-compiler: 1.0.0
+
   '@vitejs/plugin-vue@6.0.8(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))(vue@3.5.25(typescript@5.9.3))':
     dependencies:
       '@rolldown/pluginutils': 1.0.1
@@ -32192,6 +32405,8 @@ snapshots:
       fast-check: 3.23.2
     optional: true
 
+  effect@4.1.2: {}
+
   ejs@5.0.1: {}
 
   electron-to-chromium@1.5.434: {}
@@ -39456,6 +39671,17 @@ snapshots:
       rollup: 4.60.1
       vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  unplugin@3.4.0(esbuild@0.28.2)(rolldown@1.2.9)(rollup@4.60.1)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)):
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      picomatch: 4.0.7
+      webpack-virtual-modules: 0.6.2
+    optionalDependencies:
+      esbuild: 0.28.2
+      rolldown: 1.2.9
+      rollup: 4.60.1
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+
   unrun@0.2.19(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)(synckit@0.11.13):
     dependencies:
       rolldown: 1.0.0-beta.53(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.3)
@@ -39703,6 +39929,20 @@ snapshots:
       - supports-color
     optional: true
 
+  vite-plugin-solid@2.11.14(solid-js@1.9.10)(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)):
+    dependencies:
+      '@babel/core': 7.29.7(supports-color@7.2.0)
+      '@types/babel__core': 7.20.5
+      babel-preset-solid: 1.9.10(@babel/core@7.29.7)(solid-js@1.9.10)
+      merge-anything: 5.1.7
+      solid-js: 1.9.10
+      solid-refresh: 0.6.3(solid-js@1.9.10)
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+      vitefu: 1.1.3(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0))
+    transitivePeerDependencies:
+      - supports-color
+    optional: true
+
   vite-tsconfig-paths@6.1.1(supports-color@7.2.0)(typescript@7.0.2)(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)):
     dependencies:
       debug: 4.4.3(supports-color@7.2.0)
@@ -39854,6 +40094,10 @@ snapshots:
     optionalDependencies:
       vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  vitefu@1.1.3(vite@8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)):
+    optionalDependencies:
+      vite: 8.3.0(@types/node@24.13.6)(esbuild@0.28.2)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)
+
   vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@24.10.3)(@vitest/coverage-v8@4.1.10)(happy-dom@20.11.2)(jsdom@27.4.0(@noble/hashes@2.3.0))(vite@8.2.1(@types/node@24.10.3)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.6)(sass-embedded@1.107.1)(sass@1.107.1)(terser@5.44.1)(tsx@4.23.12)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.10
diff --git a/testing/e2e/fixtures/effect-chat/basic.json b/testing/e2e/fixtures/effect-chat/basic.json
new file mode 100644
index 0000000000..710c8f9376
--- /dev/null
+++ b/testing/e2e/fixtures/effect-chat/basic.json
@@ -0,0 +1,37 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[effect-chat] weather in Oslo",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "toolCalls": [
+          {
+            "name": "get_weather",
+            "arguments": "{\"city\":\"Oslo\"}"
+          }
+        ]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[effect-chat] weather in Oslo",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "Pack sunglasses for Oslo."
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[effect-image] a red fox"
+      },
+      "response": {
+        "image": {
+          "b64Json": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYPgPAAEDAQA2dBFAAAAAAElFTkSuQmCC"
+        }
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/package.json b/testing/e2e/package.json
index 80e6a96274..8be1a2d521 100644
--- a/testing/e2e/package.json
+++ b/testing/e2e/package.json
@@ -31,6 +31,7 @@
     "@tanstack/ai-computer-local": "workspace:*",
     "@tanstack/ai-computer-playwright": "workspace:*",
     "@tanstack/ai-computer-use": "workspace:*",
+    "@tanstack/ai-effect": "workspace:*",
     "@tanstack/ai-elevenlabs": "workspace:*",
     "@tanstack/ai-fal": "workspace:*",
     "@tanstack/ai-gemini": "workspace:*",
@@ -63,6 +64,7 @@
     "@tanstack/react-router": "^1.170.41",
     "@tanstack/react-start": "^1.168.60",
     "arktype": "^2.1.28",
+    "effect": "^4.1.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-markdown": "^10.1.0",
diff --git a/testing/e2e/src/routeTree.gen.ts b/testing/e2e/src/routeTree.gen.ts
index 3988d3e0bc..b7b3992915 100644
--- a/testing/e2e/src/routeTree.gen.ts
+++ b/testing/e2e/src/routeTree.gen.ts
@@ -94,6 +94,7 @@ import { Route as ApiDurableDeliveryRouteImport } from './routes/api.durable-del
 import { Route as ApiDurableDeliveryCancelRouteImport } from './routes/api.durable-delivery-cancel'
 import { Route as ApiDurableMcpInputRouteImport } from './routes/api.durable-mcp-input'
 import { Route as ApiDurableTakeoverRouteImport } from './routes/api.durable-takeover'
+import { Route as ApiEffectChatRouteImport } from './routes/api.effect-chat'
 import { Route as ApiEmbeddingRouteImport } from './routes/api.embedding'
 import { Route as ApiEmbeddingAbortRouteImport } from './routes/api.embedding-abort'
 import { Route as ApiEvaluateHttpStatusRouteImport } from './routes/api.evaluate-http-status'
@@ -664,6 +665,11 @@ const ApiDurableTakeoverRoute = ApiDurableTakeoverRouteImport.update({
   path: '/api/durable-takeover',
   getParentRoute: () => rootRouteImport,
 } as any)
+const ApiEffectChatRoute = ApiEffectChatRouteImport.update({
+  id: '/api/effect-chat',
+  path: '/api/effect-chat',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiEmbeddingRoute = ApiEmbeddingRouteImport.update({
   id: '/api/embedding',
   path: '/api/embedding',
@@ -1389,6 +1395,7 @@ export interface FileRoutesByFullPath {
   '/api/durable-delivery-cancel': typeof ApiDurableDeliveryCancelRoute
   '/api/durable-mcp-input': typeof ApiDurableMcpInputRoute
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
+  '/api/effect-chat': typeof ApiEffectChatRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/embedding-abort': typeof ApiEmbeddingAbortRoute
   '/api/evaluate-http-status': typeof ApiEvaluateHttpStatusRoute
@@ -1598,6 +1605,7 @@ export interface FileRoutesByTo {
   '/api/durable-delivery-cancel': typeof ApiDurableDeliveryCancelRoute
   '/api/durable-mcp-input': typeof ApiDurableMcpInputRoute
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
+  '/api/effect-chat': typeof ApiEffectChatRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/embedding-abort': typeof ApiEmbeddingAbortRoute
   '/api/evaluate-http-status': typeof ApiEvaluateHttpStatusRoute
@@ -1808,6 +1816,7 @@ export interface FileRoutesById {
   '/api/durable-delivery-cancel': typeof ApiDurableDeliveryCancelRoute
   '/api/durable-mcp-input': typeof ApiDurableMcpInputRoute
   '/api/durable-takeover': typeof ApiDurableTakeoverRoute
+  '/api/effect-chat': typeof ApiEffectChatRoute
   '/api/embedding': typeof ApiEmbeddingRoute
   '/api/embedding-abort': typeof ApiEmbeddingAbortRoute
   '/api/evaluate-http-status': typeof ApiEvaluateHttpStatusRoute
@@ -2019,6 +2028,7 @@ export interface FileRouteTypes {
     | '/api/durable-delivery-cancel'
     | '/api/durable-mcp-input'
     | '/api/durable-takeover'
+    | '/api/effect-chat'
     | '/api/embedding'
     | '/api/embedding-abort'
     | '/api/evaluate-http-status'
@@ -2228,6 +2238,7 @@ export interface FileRouteTypes {
     | '/api/durable-delivery-cancel'
     | '/api/durable-mcp-input'
     | '/api/durable-takeover'
+    | '/api/effect-chat'
     | '/api/embedding'
     | '/api/embedding-abort'
     | '/api/evaluate-http-status'
@@ -2437,6 +2448,7 @@ export interface FileRouteTypes {
     | '/api/durable-delivery-cancel'
     | '/api/durable-mcp-input'
     | '/api/durable-takeover'
+    | '/api/effect-chat'
     | '/api/embedding'
     | '/api/embedding-abort'
     | '/api/evaluate-http-status'
@@ -2647,6 +2659,7 @@ export interface RootRouteChildren {
   ApiDurableDeliveryCancelRoute: typeof ApiDurableDeliveryCancelRoute
   ApiDurableMcpInputRoute: typeof ApiDurableMcpInputRoute
   ApiDurableTakeoverRoute: typeof ApiDurableTakeoverRoute
+  ApiEffectChatRoute: typeof ApiEffectChatRoute
   ApiEmbeddingRoute: typeof ApiEmbeddingRoute
   ApiEmbeddingAbortRoute: typeof ApiEmbeddingAbortRoute
   ApiEvaluateHttpStatusRoute: typeof ApiEvaluateHttpStatusRoute
@@ -3364,6 +3377,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiDurableTakeoverRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/api/effect-chat': {
+      id: '/api/effect-chat'
+      path: '/api/effect-chat'
+      fullPath: '/api/effect-chat'
+      preLoaderRoute: typeof ApiEffectChatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/embedding': {
       id: '/api/embedding'
       path: '/api/embedding'
@@ -4369,6 +4389,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiDurableDeliveryCancelRoute: ApiDurableDeliveryCancelRoute,
   ApiDurableMcpInputRoute: ApiDurableMcpInputRoute,
   ApiDurableTakeoverRoute: ApiDurableTakeoverRoute,
+  ApiEffectChatRoute: ApiEffectChatRoute,
   ApiEmbeddingRoute: ApiEmbeddingRoute,
   ApiEmbeddingAbortRoute: ApiEmbeddingAbortRoute,
   ApiEvaluateHttpStatusRoute: ApiEvaluateHttpStatusRoute,
diff --git a/testing/e2e/src/routes/api.effect-chat.ts b/testing/e2e/src/routes/api.effect-chat.ts
new file mode 100644
index 0000000000..5aac689838
--- /dev/null
+++ b/testing/e2e/src/routes/api.effect-chat.ts
@@ -0,0 +1,71 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { toServerSentEventsResponse, toolDefinition } from '@tanstack/ai'
+import * as AI from '@tanstack/ai-effect'
+import { Context, Effect, Layer, Schema, Stream } from 'effect'
+import { createTextAdapter } from '@/lib/providers'
+import { createImageAdapter } from '@/lib/media-providers'
+
+/**
+ * `@tanstack/ai-effect` over a real adapter wire (aimock).
+ *
+ * - Default: `AI.chat` with an Effect tool. The tool reads a `Weather`
+ *   service that a `Layer` provides. The run streams back as SSE.
+ * - `?kind=image`: `AI.generateImage` runs as an Effect and returns JSON.
+ */
+class Weather extends Context.Service<
+  Weather,
+  { readonly forecast: (city: string) => Effect.Effect<string> }
+>()('Weather') {}
+
+const WeatherLive = Layer.succeed(Weather, {
+  forecast: (city) => Effect.succeed(`Sunny and 21C in ${city}`),
+})
+
+const getWeatherDef = toolDefinition({
+  name: 'get_weather',
+  description: 'Get the weather for a city',
+  inputSchema: AI.toolSchema(Schema.Struct({ city: Schema.String })),
+  outputSchema: AI.toolSchema(Schema.Struct({ forecast: Schema.String })),
+})
+
+const getWeather = AI.serverTool(getWeatherDef, ({ city }) =>
+  Effect.gen(function* () {
+    const weather = yield* Weather
+    return { forecast: yield* weather.forecast(city) }
+  }),
+)
+
+export const Route = createFileRoute('/api/effect-chat')({
+  server: {
+    handlers: {
+      POST: async ({ request }) => {
+        const url = new URL(request.url)
+        const testId = url.searchParams.get('testId') ?? undefined
+        const port = url.searchParams.get('aimockPort')
+        const aimockPort = port ? Number(port) : undefined
+
+        if (url.searchParams.get('kind') === 'image') {
+          const result = await Effect.runPromise(
+            AI.generateImage({
+              adapter: createImageAdapter('openai', aimockPort, testId),
+              threadId: 'effect-image',
+              prompt: '[effect-image] a red fox',
+            }),
+          )
+          return Response.json(result)
+        }
+
+        const chunks = AI.chat({
+          ...createTextAdapter('openai', undefined, aimockPort, testId),
+          threadId: 'effect-chat',
+          messages: [
+            { role: 'user', content: '[effect-chat] weather in Oslo' },
+          ],
+          tools: [getWeather],
+        }).pipe(Stream.provide(WeatherLive))
+
+        return toServerSentEventsResponse(Stream.toAsyncIterable(chunks))
+      },
+    },
+  },
+})
diff --git a/testing/e2e/tests/effect-chat.spec.ts b/testing/e2e/tests/effect-chat.spec.ts
new file mode 100644
index 0000000000..df42846b8e
--- /dev/null
+++ b/testing/e2e/tests/effect-chat.spec.ts
@@ -0,0 +1,70 @@
+import { test, expect } from './fixtures'
+
+/**
+ * `@tanstack/ai-effect` against aimock. The route runs `AI.chat` with an
+ * Effect tool that reads a `Weather` service from a `Layer`, and
+ * `AI.generateImage` as an Effect. Fixtures: `fixtures/effect-chat/basic.json`.
+ */
+
+const PIXEL_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR42mNgYPgPAAEDAQA2dBFAAAAAAElFTkSuQmCC'
+
+type WireEvent = {
+  type: string
+  delta?: string
+  content?: string
+}
+
+function eventsOf(sse: string): Array<WireEvent> {
+  return sse
+    .split('\n')
+    .filter((line) => line.startsWith('data: '))
+    .map((line) => JSON.parse(line.slice('data: '.length)))
+}
+
+function routeUrl(testId: string, aimockPort: number, kind?: 'image') {
+  const params = new URLSearchParams({
+    testId,
+    aimockPort: String(aimockPort),
+  })
+  if (kind) params.set('kind', kind)
+  return `/api/effect-chat?${params}`
+}
+
+test.describe('ai-effect', () => {
+  test('chat runs the Effect tool with the Layer service and streams the answer', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const res = await request.post(routeUrl(testId, aimockPort))
+    expect(res.ok()).toBe(true)
+
+    const events = eventsOf(await res.text())
+    const toolResult = events.find((event) => event.type === 'TOOL_CALL_RESULT')
+    expect(JSON.parse(toolResult?.content ?? 'null')).toEqual({
+      forecast: 'Sunny and 21C in Oslo',
+    })
+
+    const text = events
+      .filter((event) => event.type === 'TEXT_MESSAGE_CONTENT')
+      .map((event) => event.delta)
+      .join('')
+    expect(text).toBe('Pack sunglasses for Oslo.')
+    expect(events.at(-1)?.type).toBe('RUN_FINISHED')
+  })
+
+  test('generateImage returns the image as JSON', async ({
+    request,
+    testId,
+    aimockPort,
+  }) => {
+    const res = await request.post(routeUrl(testId, aimockPort, 'image'))
+    expect(res.ok()).toBe(true)
+
+    const result: { images: Array<{ b64Json?: string }> } = await res.json()
+    expect(result.images).toEqual([
+      expect.objectContaining({ b64Json: PIXEL_PNG }),
+    ])
+  })
+})