@ably/ai-transport 0.0.1 → 0.2.0

package/README.md

@@ -8,23 +8,23 @@ A durable transport layer between AI agents and users. Streams AI responses over
 
 Most AI frameworks stream tokens over HTTP response bodies or SSE. That works until it doesn't: connections drop through corporate proxies, responses vanish on page refresh, and sessions are stuck on a single device or tab. Once an agent starts a long-running task, the user has no way to interrupt it, check if it's still running, or continue the conversation from another device. If a human needs to take over from the agent, the session context is lost.
 
-Ably AI Transport replaces the HTTP stream with an Ably channel. The server publishes tokens to the channel as they arrive from the LLM; the response accumulates on the channel and persists, so partial responses survive disconnection. Any client can subscribe to the same channel from any device. Cancel signals, turn lifecycle events, and conversation history all flow through the channel rather than depending on a single HTTP connection.
+Ably AI Transport replaces the HTTP stream with an Ably channel. The server publishes tokens to the channel as they arrive from the LLM; the response accumulates on the channel and persists, so partial responses survive disconnection. Any client can subscribe to the same channel from any device. Cancel signals, run lifecycle events, and conversation history all flow through the channel rather than depending on a single HTTP connection.
 
 ```mermaid
 sequenceDiagram
     participant U as User
-    participant CT as Client Transport
+    participant CS as Client Session
     participant AC as Ably Channel
-    participant ST as Server Transport
+    participant AS as Agent Session
     participant LLM
 
-    U->>CT: type message
-    CT->>ST: HTTP POST (messages)
-    ST->>LLM: prompt
-    LLM-->>ST: token stream
-    ST->>AC: publish chunks
-    AC->>CT: subscribe (decode)
-    CT->>U: render tokens
+    U->>CS: type message
+    CS->>AS: HTTP POST (messages)
+    AS->>LLM: prompt
+    LLM-->>AS: token stream
+    AS->>AC: publish chunks
+    AC->>CS: subscribe (decode)
+    CS->>U: render tokens
 ```
 
 Ably AI Transport SDK is not an agent framework or orchestration layer - it works alongside whatever agent framework/model provider you choose, through a pluggable codec architecture (Vercel AI SDK supported now, more frameworks and models coming soon). It can be used in a serverless architecture (e.g. Next.js), with a durable execution framework (e.g. Temporal, Vercel Workflow DevKit) or in a traditional client-server architecture.
@@ -34,9 +34,9 @@ Ably AI Transport SDK is not an agent framework or orchestration layer - it work
 - **Resumable streaming** - If a connection drops mid-response, client reconnects and picks up where it left off. The response persists on the channel, so nothing is lost.
 - **Session continuity across surfaces** - The session belongs to the channel, not the connection. A user can change tab or device and pick up at the same point.
 - **Multi-client sync** - Multiple users, agents, or operators subscribe to the same channel. Human-AI handover is a channel operation, not a session migration.
-- **Cancellation** - Cancel signals travel over the Ably channel, not the HTTP connection, and the server turn's `abortSignal` fires automatically.
+- **Cancellation** - Cancel signals travel over the Ably channel, not the HTTP connection, and the server run's `abortSignal` fires automatically.
 - **Interruption** - Users send new messages while the AI is still responding, with composable primitives for cancel-and-resend or queue-until-complete.
-- **Concurrent turns** - Multiple request-response cycles run in parallel on the same channel. Each turn has its own stream and abort signal.
+- **Concurrent runs** - Multiple request-response cycles run in parallel on the same channel. Each run has its own stream and abort signal.
 - **History** - The Ably channel is the conversation record. Clients hydrate from channel history on load - no separate database query needed.
 - **Branching** - Regenerate or edit messages to fork the conversation. The SDK tracks parent/child relationships and exposes a navigable tree.
 - **Framework-agnostic** - A codec interface decouples transport from the AI framework. Ships with a Vercel AI SDK codec; bring your own for any other stack.
@@ -68,7 +68,7 @@ npm install @ably/ai-transport ably ai
 
 | Platform      | Support                                            |
 | ------------- | -------------------------------------------------- |
-| Node.js       | 20+                                                |
+| Node.js       | 22+                                                |
 | Browsers      | All major browsers (Chrome, Firefox, Edge, Safari) |
 | TypeScript    | Written in TypeScript, ships with types            |
 | React         | 18+ and 19+ via dedicated hooks                    |
@@ -88,49 +88,41 @@ import { streamText, convertToModelMessages } from 'ai';
 import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
-import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
-
-interface ChatRequestBody {
-  turnId: string;
-  clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
-  id: string;
-  forkOf?: string;
-  parent?: string | null;
-}
+import { createAgentSession } from '@ably/ai-transport/vercel';
+import { Invocation, type InvocationData } from '@ably/ai-transport';
+import type { UIMessageChunk } from 'ai';
 
 const ably = new Ably.Realtime({ key: process.env.ABLY_API_KEY });
 
 export async function POST(req: Request) {
-  const { messages, history, id, turnId, clientId, forkOf, parent } = (await req.json()) as ChatRequestBody;
+  const data = (await req.json()) as InvocationData<UIMessageChunk, UIMessage>;
+  const invocation = Invocation.fromJSON(data);
 
-  const channel = ably.channels.get(id);
-  const transport = createServerTransport({ channel });
-  const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
+  const session = createAgentSession({ client: ably, channelName: invocation.sessionName });
+  await session.connect();
+  const run = session.createRun(invocation, { signal: req.signal });
 
-  await turn.start();
+  await run.start();
 
-  if (messages.length > 0) {
-    await turn.addMessages(messages, { clientId });
+  if (invocation.messages.length > 0) {
+    await run.addMessages(invocation.messages, { clientId: invocation.clientId });
   }
 
-  const historyMsgs = (history ?? []).map((h) => h.message);
-  const newMsgs = messages.map((m) => m.message);
+  const historyMsgs = invocation.history.map((h) => h.message);
+  const newMsgs = invocation.messages.map((m) => m.message);
 
   const result = streamText({
-    model: anthropic('claude-sonnet-4-20250514'),
+    model: anthropic('claude-sonnet-4-6'),
     system: 'You are a helpful assistant.',
     messages: await convertToModelMessages([...historyMsgs, ...newMsgs]),
-    abortSignal: turn.abortSignal,
+    abortSignal: run.abortSignal,
   });
 
   // Stream the response over Ably in the background
   after(async () => {
-    const { reason } = await turn.streamResponse(result.toUIMessageStream());
-    await turn.end(reason);
-    transport.close();
+    const { reason } = await run.pipe(result.toUIMessageStream());
+    await run.end(reason);
+    session.close();
   });
 
   return new Response(null, { status: 200 });
@@ -143,26 +135,20 @@ export async function POST(req: Request) {
 'use client';
 
 import { useChat } from '@ai-sdk/react';
-import { useChannel } from 'ably/react';
-import { useClientTransport, useActiveTurns, useHistory } from '@ably/ai-transport/react';
-import { useChatTransport, useMessageSync } from '@ably/ai-transport/vercel/react';
-import { UIMessageCodec } from '@ably/ai-transport/vercel';
-
-function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
-  const { channel } = useChannel({ channelName: chatId });
+import { ChatTransportProvider, useChatTransport, useMessageSync, useView } from '@ably/ai-transport/vercel/react';
 
-  const transport = useClientTransport({ channel, codec: UIMessageCodec, clientId });
-  const chatTransport = useChatTransport(transport);
+function ChatInner({ chatId }: { chatId: string }) {
+  const { chatTransport } = useChatTransport();
 
-  const { messages, setMessages, sendMessage, stop } = useChat({
+  const { messages, setMessages, sendMessage, stop, status } = useChat({
     id: chatId,
     transport: chatTransport,
   });
 
-  useMessageSync(transport, setMessages);
+  useMessageSync({ setMessages });
 
-  const activeTurns = useActiveTurns(transport);
-  const history = useHistory(transport, { limit: 30 });
+  const isStreaming = status === 'submitted' || status === 'streaming';
+  useView({ limit: 30 });
 
   return (
     <div>
@@ -175,7 +161,7 @@ function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
           sendMessage({ text: 'Hello' });
         }}
       >
-        {activeTurns.size > 0 ? (
+        {isStreaming ? (
           <button
             type="button"
             onClick={stop}
@@ -189,6 +175,17 @@ function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
     </div>
   );
 }
+
+function Chat({ chatId, clientId }: { chatId: string; clientId?: string }) {
+  return (
+    <ChatTransportProvider
+      channelName={chatId}
+      clientId={clientId}
+    >
+      <ChatInner chatId={chatId} />
+    </ChatTransportProvider>
+  );
+}
 ```
 
 ### Authentication
@@ -229,20 +226,22 @@ The core entry point is framework-agnostic. Bring your own `Codec` to map betwee
 ### Client
 
 ```typescript
-import { createClientTransport } from '@ably/ai-transport';
+import { createClientSession } from '@ably/ai-transport';
 import { myCodec } from './my-codec';
 
-const transport = createClientTransport({
-  channel, // Ably RealtimeChannel
+const session = createClientSession({
+  client: ably, // Ably.Realtime
+  channelName: 'ai:demo',
   codec: myCodec,
   clientId: 'user-123',
   api: '/api/chat',
 });
+await session.connect();
 
-const turn = await transport.send(messages);
+const run = await session.view.send(messages);
 
 // Read the stream
-const reader = turn.stream.getReader();
+const reader = run.stream.getReader();
 while (true) {
   const { done, value } = await reader.read();
   if (done) break;
@@ -250,29 +249,30 @@ while (true) {
 }
 ```
 
-### Server
+### Agent (server-side)
 
 ```typescript
-import { createServerTransport } from '@ably/ai-transport';
+import { createAgentSession, Invocation } from '@ably/ai-transport';
 import { myCodec } from './my-codec';
 
-const transport = createServerTransport({ channel, codec: myCodec });
-const turn = transport.newTurn({ turnId, clientId, parent, forkOf });
+const session = createAgentSession({ client: ably, channelName: 'ai:demo', codec: myCodec });
+await session.connect();
+const run = session.createRun(invocation);
 
-await turn.start();
-await turn.addMessages(messages, { clientId });
+await run.start();
+await run.addMessages(invocation.messages, { clientId: invocation.clientId });
 
-const { reason } = await turn.streamResponse(aiStream);
-await turn.end(reason);
-transport.close();
+const { reason } = await run.pipe(aiStream);
+await run.end(reason);
+session.close();
 ```
 
 ---
 
 ## Package exports
 
-| Export path                               | Purpose                                     | Peer dependencies     |
-| ----------------------------------------- | ------------------------------------------- | --------------------- |
+| Export path                       | Purpose                                     | Peer dependencies     |
+| --------------------------------- | ------------------------------------------- | --------------------- |
 | `@ably/ai-transport`              | Core transport, codec interfaces, utilities | `ably`                |
 | `@ably/ai-transport/react`        | React hooks for any codec                   | `ably`, `react`       |
 | `@ably/ai-transport/vercel`       | Vercel AI SDK codec, transport factories    | `ably`, `ai`          |
@@ -280,19 +280,14 @@ transport.close();
 
 ### React hooks
 
-| Hook                  | Entry point     | Description                                         |
-| --------------------- | --------------- | --------------------------------------------------- |
-| `useClientTransport`  | `/react`        | Create and memoize a client transport instance      |
-| `useMessages`         | `/react`        | Subscribe to decoded messages                       |
-| `useSend`             | `/react`        | Stable send callback                                |
-| `useRegenerate`       | `/react`        | Regenerate a message (fork the conversation)        |
-| `useEdit`             | `/react`        | Edit a message and regenerate from that point       |
-| `useActiveTurns`      | `/react`        | Track active turns by client ID                     |
-| `useHistory`          | `/react`        | Paginate through conversation history               |
-| `useConversationTree` | `/react`        | Navigate branches in a forked conversation          |
-| `useAblyMessages`     | `/react`        | Access raw Ably messages                            |
-| `useChatTransport`    | `/vercel/react` | Wrap transport for Vercel's `useChat`               |
-| `useMessageSync`      | `/vercel/react` | Sync transport state with `useChat`'s `setMessages` |
+| Hook               | Entry point     | Description                                       |
+| ------------------ | --------------- | ------------------------------------------------- |
+| `useClientSession` | `/react`        | Read a client session from the nearest provider   |
+| `useView`          | `/react`        | Subscribe to messages with history loading        |
+| `useTree`          | `/react`        | Navigate branches in a forked conversation        |
+| `useAblyMessages`  | `/react`        | Access raw Ably messages                          |
+| `useChatTransport` | `/vercel/react` | Wrap session for Vercel's `useChat`               |
+| `useMessageSync`   | `/vercel/react` | Sync session state with `useChat`'s `setMessages` |
 
 ---
 
@@ -303,22 +298,23 @@ transport.close();
 Two mechanisms cover different failure modes:
 
 - **Network blips** - Ably's connection protocol automatically reconnects and delivers any messages published while the client was disconnected. No application code required.
-- **Resumable streams** - A client that joins or rejoins a channel mid-response (after a page refresh, on a new device, or as a second participant) receives the in-progress stream immediately on subscribing. Load previous conversation history from the channel via `history()`, or from your own database.
+- **Resumable streams** - A client that joins or rejoins a channel mid-response (after a page refresh, on a new device, or as a second participant) receives the in-progress stream immediately on subscribing. Load previous conversation history from the channel via `view.loadOlder()`, or from your own database.
 
 ### Cancellation
 
 ```typescript
-// Client: cancel your own active turns
-await transport.cancel();
+// Client: cancel a specific run by id
+await session.cancel('run-abc');
 
-// Cancel a specific turn
-await transport.cancel({ turnId: 'turn-abc' });
+// Or via the ActiveRun returned by send / regenerate / edit
+const run = await view.send(codec.createUserMessage(userMsg));
+await run.cancel();
 
-// Server: the turn's abortSignal fires automatically
+// Agent: the run's abortSignal fires automatically
 const result = streamText({
-  model: anthropic('claude-sonnet-4-20250514'),
+  model: anthropic('claude-sonnet-4-6'),
   messages,
-  abortSignal: turn.abortSignal, // Aborted when client cancels
+  abortSignal: run.abortSignal, // Aborted when client cancels
 });
 ```
 
@@ -328,15 +324,15 @@ Regenerate or edit messages to create forks in the conversation tree. The SDK tr
 
 ```typescript
 // Regenerate the last assistant message
-const turn = await transport.regenerate(assistantMessageId);
+const run = await session.view.regenerate(assistantMessageId);
 
 // Edit a user message and regenerate from that point
-const turn = await transport.edit(userMessageId, [newMessage]);
+const run = await session.view.edit(userMessageId, [newMessage]);
 
 // Navigate branches
-const tree = transport.getTree();
+const tree = session.tree;
 const siblings = tree.getSiblings(messageId);
-tree.select(messageId, 1); // Switch to second branch
+session.view.select(messageId, 1); // Switch to second branch
 ```
 
 ### History and hydration
@@ -344,26 +340,26 @@ tree.select(messageId, 1); // Switch to second branch
 Load previous conversation state when a client joins or returns to a session.
 
 ```typescript
-const page = await transport.history({ limit: 50 });
-console.log(page.items); // Decoded messages
+const view = session.view;
+await view.loadOlder(50);
+// view.getMessages() returns the flat message list loaded so far
 
-if (page.hasNext()) {
-  const older = await page.next();
-}
+// Load more older messages
+await view.loadOlder(50);
 ```
 
 ### Events
 
 ```typescript
-transport.on('message', () => {
-  console.log(transport.getMessages());
+session.view.on('update', () => {
+  console.log(session.view.getMessages());
 });
 
-transport.on('turn', (event) => {
-  console.log(event.turnId, event.type); // 'x-ably-turn-start' | 'x-ably-turn-end'
+session.tree.on('run', (event) => {
+  console.log(event.runId, event.type); // 'ai-run-start' | 'ai-run-end'
 });
 
-transport.on('error', (error) => {
+session.on('error', (error) => {
   console.error(error.code, error.message);
 });
 ```
@@ -374,10 +370,10 @@ transport.on('error', (error) => {
 
 Detailed documentation lives in the [`docs/`](./docs/) directory:
 
-- **[Concepts](./docs/concepts/)** - [Transport architecture](./docs/concepts/transport.md), [Turns](./docs/concepts/turns.md)
-- **[Get started](./docs/get-started/)** - [Vercel AI SDK with useChat](./docs/get-started/vercel-use-chat.md), [Vercel AI SDK with useClientTransport](./docs/get-started/vercel-use-client-transport.md)
+- **[Concepts](./docs/concepts/)** - [Sessions](./docs/concepts/sessions.md), [Runs](./docs/concepts/runs.md)
+- **[Get started](./docs/get-started/)** - [Vercel AI SDK with useChat](./docs/get-started/vercel-use-chat.md), [Vercel AI SDK with useClientSession](./docs/get-started/vercel-use-client-session.md)
 - **[Frameworks](./docs/frameworks/)** - [Vercel AI SDK](./docs/frameworks/vercel-ai-sdk.md)
-- **[Features](./docs/features/)** - [Streaming](./docs/features/streaming.md), [Cancellation](./docs/features/cancel.md), [Barge-in](./docs/features/barge-in.md), [Optimistic updates](./docs/features/optimistic-updates.md), [History](./docs/features/history.md), [Branching](./docs/features/branching.md), [Multi-client sync](./docs/features/multi-client.md), [Tool calls](./docs/features/tool-calls.md), [Concurrent turns](./docs/features/concurrent-turns.md)
+- **[Features](./docs/features/)** - [Streaming](./docs/features/streaming.md), [Cancellation](./docs/features/cancel.md), [Interruption](./docs/features/interruption.md), [Optimistic updates](./docs/features/optimistic-updates.md), [History](./docs/features/history.md), [Branching](./docs/features/branching.md), [Multi-client sync](./docs/features/multi-client.md), [Concurrent runs](./docs/features/concurrent-runs.md)
 - **[Reference](./docs/reference/)** - [React hooks](./docs/reference/react-hooks.md), [Error codes](./docs/reference/error-codes.md)
 - **[Internals](./docs/internals/)** - Architecture details for contributors
 
@@ -388,20 +384,22 @@ Detailed documentation lives in the [`docs/`](./docs/) directory:
 Working demo applications live in the [`demo/`](./demo/) directory:
 
 - **[`demo/vercel/react/use-chat/`](./demo/vercel/react/use-chat/)** - Vercel AI SDK with `useChat` integration
-- **[`demo/vercel/react/use-client-transport/`](./demo/vercel/react/use-client-transport/)** - Vercel AI SDK with direct `useClientTransport` hooks
+- **[`demo/vercel/react/use-client-session/`](./demo/vercel/react/use-client-session/)** - Vercel AI SDK with direct `useClientSession` hooks
 
 ---
 
 ## Development
 
+This repository uses [pnpm](https://pnpm.io/). Enable Corepack once (`corepack enable`) to pick up the pinned version automatically.
+
 ```bash
-npm install
-npm run build             # Build all entry points (ESM + UMD/CJS + .d.ts)
-npm run typecheck         # Type check
-npm run lint              # Lint
-npm test                  # Unit tests (mocks only)
-npm run test:integration  # Integration tests (needs ABLY_API_KEY)
-npm run precommit         # format:check + lint + typecheck
+pnpm install
+pnpm run build             # Build all entry points (ESM + UMD/CJS + .d.ts)
+pnpm run typecheck         # Type check
+pnpm run lint              # Lint
+pnpm test                  # Unit tests (mocks only)
+pnpm run test:integration  # Integration tests (needs ABLY_API_KEY)
+pnpm run precommit         # format:check + lint + typecheck
 ```
 
 ### Project structure
@@ -410,7 +408,7 @@ npm run precommit         # format:check + lint + typecheck
 src/
 ├── core/               # Generic transport and codec (no framework deps)
 │   ├── codec/          # Codec interfaces and core encoder/decoder
-│   └── transport/      # ClientTransport, ServerTransport, ConversationTree
+│   └── transport/      # ClientSession, AgentSession, Tree
 ├── react/              # React hooks for any codec
 ├── vercel/             # Vercel AI SDK codec and transport adapters
 │   ├── codec/          # UIMessageCodec