# Providers

`ClientSessionProvider` creates a `ClientSession` once on mount, connects it, and exposes it to descendants through React context. The hooks in `@ably/ai-transport/react` read the session via this provider, so wrap every subtree that uses them in one.

Nest multiple providers with distinct `channelName` values to manage more than one session in the same tree. Each provider merges its slot into the parent registry so descendants can address any registered session by `channelName`.

<Code>

#### Javascript

```
import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { ClientSessionProvider } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

function App() {
  return (
    <AblyProvider client={ably}>
      <ClientSessionProvider channelName="conversation-42" codec={UIMessageCodec}>
        <Chat />
      </ClientSessionProvider>
    </AblyProvider>
  );
}
```
</Code>

## ClientSessionProvider 

The provider reads the Ably Realtime client from the surrounding `<AblyProvider>` and forwards it, along with the supplied props, to `createClientSession`. The session is created once on first render via `useRef`. `connect()` is invoked from a `useEffect` so the session is subscribed and attached before the first descendant read.

If `createClientSession` throws, the error is stored on the slot alongside an undefined session. `useClientSession` surfaces it as [`sessionError`](https://ably.com/docs/ai-transport/api/react/core/use-client-session.md#returns) so the component tree does not crash.

### Props 

`ClientSessionProviderProps` extends all [`ClientSessionOptions`](https://ably.com/docs/ai-transport/api/javascript/core/client-session.md#constructor-params) except `client` (which is read from `<AblyProvider>`).

<Table id='ClientSessionProviderProps'>

| Property | Description | Type |
| --- | --- | --- |
| channelName | The channel the session subscribes to. Used as the registry key for nested providers. | String |
| codec | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
| clientId | The client's identity, used as the Ably publisher `clientId` for everything the session publishes. | String |
| messages | Initial messages to seed the conversation tree with. | `TMessage[]` |
| logger | Logger instance for diagnostic output. | `Logger` |
| children | Descendant components that consume the session via hooks. | `ReactNode` |

</Table>

## ClientSessionSlot 

A single entry in the registry holding the session and any error from construction. [`useClientSession`](https://ably.com/docs/ai-transport/api/react/core/use-client-session.md) returns this shape.

<Table id='ClientSessionSlot'>

| Property | Description | Type |
| --- | --- | --- |
| session | The constructed session, or `undefined` if construction failed. | `ClientSession<TInput, TOutput, TProjection, TMessage>` or Undefined |
| sessionError | Construction error from `createClientSession`, or `undefined` on success. | `Ably.ErrorInfo` or Undefined |

</Table>

## Bake hook types with createSessionHooks 

`function createSessionHooks<TInput, TOutput, TProjection, TMessage>(): SessionHooks<TInput, TOutput, TProjection, TMessage>`

A factory that captures the codec's four type parameters once and returns a bundle of type-safe hooks plus a narrowed `ClientSessionProvider`. Hook call sites need no type parameters once you have called the factory.

Use this when you have one codec for the whole app and want call sites that look like `const view = useView({ limit: 30 })` without generics. The Vercel React entry point already exports a bundle baked to the Vercel types.

<Code>

### Javascript

```
// session.ts: shared module
import { createSessionHooks } from '@ably/ai-transport/react';
import type {
  VercelInput,
  VercelOutput,
  VercelProjection,
} from '@ably/ai-transport/vercel';
import type { UIMessage } from 'ai';

export const {
  ClientSessionProvider,
  useClientSession,
  useView,
  useTree,
  useCreateView,
  useAblyMessages,
} = createSessionHooks<VercelInput, VercelOutput, VercelProjection, UIMessage>();
```
</Code>

The factory takes four type parameters. Omitting them leaves every hook inferred as `unknown`; pass them explicitly so call sites stay type-safe.

### Returns 

<Table id='SessionHooks'>

| Property | Description | Type |
| --- | --- | --- |
| ClientSessionProvider | `ClientSessionProvider` narrowed to the captured types. No JSX type params needed. | `ComponentType<ClientSessionProviderProps>` |
| useClientSession | Type-narrowed [`useClientSession`](https://ably.com/docs/ai-transport/api/react/core/use-client-session.md). | Function |
| useView | Type-narrowed [`useView`](https://ably.com/docs/ai-transport/api/react/core/use-view.md). | Function |
| useTree | Type-narrowed [`useTree`](https://ably.com/docs/ai-transport/api/react/core/use-tree.md). | Function |
| useAblyMessages | Type-narrowed [`useAblyMessages`](https://ably.com/docs/ai-transport/api/react/core/use-ably-messages.md). | Function |
| useCreateView | Type-narrowed [`useCreateView`](https://ably.com/docs/ai-transport/api/react/core/use-create-view.md). | Function |

</Table>

## Example 

Nested providers with distinct channel names and a child component that addresses each session by name.

<Code>

### Javascript

```
import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

function App() {
  return (
    <AblyProvider client={ably}>
      <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
        <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
          <Chat />
        </ClientSessionProvider>
      </ClientSessionProvider>
    </AblyProvider>
  );
}

function Chat() {
  const { session: main } = useClientSession({ channelName: 'ai:main' });
  const { session: aux, sessionError } = useClientSession({ channelName: 'ai:aux' });

  if (sessionError) return <ErrorBanner error={sessionError} />;
  return <SplitPane mainSession={main} auxSession={aux} />;
}
```
</Code>

## Related Topics

- [useClientSession](https://ably.com/docs/ai-transport/api/react/core/use-client-session.md): Read a ClientSession from the nearest ClientSessionProvider in the AI Transport React integration.
- [useView](https://ably.com/docs/ai-transport/api/react/core/use-view.md): Subscribe to a paginated, branch-aware view of the AI Transport conversation tree from React.
- [useCreateView](https://ably.com/docs/ai-transport/api/react/core/use-create-view.md): Create an independent View over the AI Transport conversation tree from React, with its own branch selections and pagination.
- [useTree](https://ably.com/docs/ai-transport/api/react/core/use-tree.md): Stable structural query callbacks for the AI Transport conversation tree from React.
- [useAblyMessages](https://ably.com/docs/ai-transport/api/react/core/use-ably-messages.md): Subscribe to raw Ably InboundMessages on the AI Transport channel from React.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.