From fa18315ca76ab41b02d6705c6ea91ee70cca0985 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:11:37 +0100
Subject: [PATCH 01/15] AI Transport docs: bump SDK version badge to 0.4

Target the upcoming @ably/ai-transport v0.4.0 release across the AI
Transport docs. The version registry drives both the page version badge
and the code-accuracy baseline, so the samples updated in this PR align
with the v0.4.0 surface.

AIT-1090
---
 src/data/languages/languageData.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/data/languages/languageData.ts b/src/data/languages/languageData.ts
index e1788fdb19..afb821eb72 100644
--- a/src/data/languages/languageData.ts
+++ b/src/data/languages/languageData.ts
@@ -44,7 +44,7 @@ export default {
     android: '1.2',
   },
   aiTransport: {
-    javascript: '0.3',
+    javascript: '0.4',
   },
   spaces: {
     javascript: '0.5',

From 3221cf01d26baf1788f1afe7358e12a0ba112b1a Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:22:18 +0100
Subject: [PATCH 02/15] AI Transport docs: document database-backed hydration

v0.4.0 replaces the removed ClientSessionOptions.messages seed with a
seam-reconciliation model: View.loadUntil pages the channel back to the
newest stored message and returns the not-yet-stored tail, and the new
useMessagesWithSeed React hook composes a persisted seed with the live
view.

- Add features/database-hydration.mdx covering the seam model, agent and
  client hydration, turn persistence (run.messages), and edge cases.
- Add api/react/core/use-messages-with-seed.mdx for the new hook.
- Register both pages in the AI Transport nav and the API reference hub.

AIT-1090
---
 src/data/nav/aitransport.ts                   |   8 ++
 src/pages/docs/ai-transport/api/index.mdx     |  10 +-
 .../api/react/core/use-messages-with-seed.mdx |  73 ++++++++++
 .../features/database-hydration.mdx           | 130 ++++++++++++++++++
 4 files changed, 219 insertions(+), 2 deletions(-)
 create mode 100644 src/pages/docs/ai-transport/api/react/core/use-messages-with-seed.mdx
 create mode 100644 src/pages/docs/ai-transport/features/database-hydration.mdx

diff --git a/src/data/nav/aitransport.ts b/src/data/nav/aitransport.ts
index 57e0271fbc..cae87f97fe 100644
--- a/src/data/nav/aitransport.ts
+++ b/src/data/nav/aitransport.ts
@@ -131,6 +131,10 @@ export default {
           name: 'History and replay',
           link: '/docs/ai-transport/features/history',
         },
+        {
+          name: 'Database hydration',
+          link: '/docs/ai-transport/features/database-hydration',
+        },
         {
           name: 'Branching, edit, and regenerate',
           link: '/docs/ai-transport/features/branching',
@@ -259,6 +263,10 @@ export default {
                   name: 'useCreateView',
                   link: '/docs/ai-transport/api/react/core/use-create-view',
                 },
+                {
+                  name: 'useMessagesWithSeed',
+                  link: '/docs/ai-transport/api/react/core/use-messages-with-seed',
+                },
                 {
                   name: 'useTree',
                   link: '/docs/ai-transport/api/react/core/use-tree',
diff --git a/src/pages/docs/ai-transport/api/index.mdx b/src/pages/docs/ai-transport/api/index.mdx
index 74191c814c..944ad38b70 100644
--- a/src/pages/docs/ai-transport/api/index.mdx
+++ b/src/pages/docs/ai-transport/api/index.mdx
@@ -36,9 +36,9 @@ See the individual reference pages for the full API.
 | Entry point | Import path | Contents |
 | --- | --- | --- |
 | Core | `@ably/ai-transport` | `createClientSession`, `createAgentSession`, `Invocation`, `Codec` interface |
-| React | `@ably/ai-transport/react` | `ClientSessionProvider`, `useClientSession`, `useView`, `useTree`, `useCreateView`, `useAblyMessages`, `createSessionHooks` |
+| React | `@ably/ai-transport/react` | `ClientSessionProvider`, `useClientSession`, `useView`, `useTree`, `useCreateView`, `useMessagesWithSeed`, `useAblyMessages`, `createSessionHooks` |
 | Vercel | `@ably/ai-transport/vercel` | `UIMessageCodec`, Vercel-bound `createClientSession` and `createAgentSession`, `createChatTransport`, `vercelRunOutcome` |
-| Vercel React | `@ably/ai-transport/vercel/react` | `ChatTransportProvider`, `useChatTransport`, `useMessageSync`, plus the Vercel-baked re-exports of `ClientSessionProvider`, `useClientSession`, `useView`, `useCreateView`, `useTree`, and `useAblyMessages` |
+| Vercel React | `@ably/ai-transport/vercel/react` | `ChatTransportProvider`, `useChatTransport`, `useMessageSync`, `useMessagesWithSeed`, plus the Vercel-baked re-exports of `ClientSessionProvider`, `useClientSession`, `useView`, `useCreateView`, `useTree`, and `useAblyMessages` |
 
 <Aside data-type='note'>
 The Vercel entry points re-export the core factories with the codec pre-bound. If you use `@ably/ai-transport/vercel`, you do not need to import from `@ably/ai-transport` separately.
@@ -126,6 +126,12 @@ The Vercel entry points re-export the core factories with the codec pre-bound. I
     image: 'icon-tech-react',
     link: '/docs/ai-transport/api/react/core/use-create-view',
   },
+  {
+    title: 'useMessagesWithSeed',
+    description: 'Reconcile a persisted conversation seed with the live channel and render the composed conversation.',
+    image: 'icon-tech-react',
+    link: '/docs/ai-transport/api/react/core/use-messages-with-seed',
+  },
   {
     title: 'useTree',
     description: 'Stable structural query callbacks for inspecting Runs outside the visible branch.',
diff --git a/src/pages/docs/ai-transport/api/react/core/use-messages-with-seed.mdx b/src/pages/docs/ai-transport/api/react/core/use-messages-with-seed.mdx
new file mode 100644
index 0000000000..65f919a8d7
--- /dev/null
+++ b/src/pages/docs/ai-transport/api/react/core/use-messages-with-seed.mdx
@@ -0,0 +1,73 @@
+---
+title: "useMessagesWithSeed"
+meta_description: "Reconcile a persisted conversation seed with the live AI Transport channel from React and render the composed conversation."
+meta_keywords: "AI Transport, React, useMessagesWithSeed, seed, hydration, loadUntil, Ably"
+---
+
+`useMessagesWithSeed` reconciles a persisted conversation seed with the live Ably channel and returns the composed conversation, oldest-first: the seed followed by the live tail that has not yet been seeded. It is the core primitive behind database-backed [hydration](/docs/ai-transport/features/database-hydration), and the Vercel `useMessageSync` builds on it.
+
+Pass the `view` from a resolved session. [`useClientSession()`](/docs/ai-transport/api/react/core/providers#client-session-provider) returns a handle whose `session.view` is a `View`.
+
+<Code>
+```javascript
+import { useMessagesWithSeed } from '@ably/ai-transport/react';
+
+const messages = useMessagesWithSeed({
+  view: session?.view,
+  seed,
+  getMessageId: (message) => message.id,
+});
+```
+</Code>
+
+This hook is typically used within a [`ClientSessionProvider`](/docs/ai-transport/api/react/core/providers#client-session-provider), which resolves the session whose `view` you pass in.
+
+The hook takes the newest seed message's id, via `getMessageId`, as the seam and drives [`View.loadUntil`](/docs/ai-transport/api/javascript/core/client-session) to page the channel back until that id reappears. It then composes the seed followed by the live tail, dropping the single overlapping message at the seam. With no seed (an empty array) it surfaces the live channel window unchanged.
+
+## Parameters <a id="parameters"/>
+
+`useMessagesWithSeed` accepts a single `UseMessagesWithSeedOptions<TMessage>` object:
+
+<Table id='UseMessagesWithSeedOptions'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| view | optional | The view over the live channel to reconcile against, for example `session.view`, or `undefined` before the session or view resolves. The hook then surfaces the seed as-is. | `View<TMessage>` or Undefined |
+| seed | required | The persisted conversation, oldest-first. Compared by content, so passing a fresh array each render, for example `data ?? []`, is safe. An empty array is a loaded-but-empty conversation and surfaces the live channel window unchanged. While the seed is still loading, set `skip` instead of passing `[]`. | `TMessage[]` |
+| getMessageId | required | Returns a message's stable domain id, the seam key shared between your store and the channel. The transport's internal `codecMessageId` is never persisted. | `(message: TMessage) => string` |
+| skip | optional | Holds the reconciliation while the seed is still loading, for example during an async store fetch. When `true` the hook does not page the channel and returns `[]`. Clear it once the seed has loaded. Defaults to `false`. | Boolean |
+
+</Table>
+
+## Returns <a id="returns"/>
+
+`TMessage[]`. The composed conversation, oldest-first: the seed followed by the live tail newer than the seam. While `skip` is `true`, or before a seed loads, the hook returns `[]`.
+
+## Example <a id="example"/>
+
+A component that fetches its seed from a store, reads the view from the resolved session, and renders the composed conversation:
+
+<Code>
+```javascript
+import { useClientSession, useMessagesWithSeed } from '@ably/ai-transport/react';
+
+function Conversation({ seed }) {
+  const { session } = useClientSession();
+  const messages = useMessagesWithSeed({
+    view: session?.view,
+    seed,
+    getMessageId: (message) => message.id,
+  });
+
+  return (
+    <>
+      {messages.map((message) => (
+        <Message key={message.id} message={message} />
+      ))}
+    </>
+  );
+}
+```
+</Code>
+
+For Vercel AI SDK applications, the pre-typed `useMessagesWithSeed` from `@ably/ai-transport/vercel/react` omits `getMessageId` because it keys on `UIMessage.id`, and `useMessageSync` wraps it for `useChat`.
diff --git a/src/pages/docs/ai-transport/features/database-hydration.mdx b/src/pages/docs/ai-transport/features/database-hydration.mdx
new file mode 100644
index 0000000000..9e8286424a
--- /dev/null
+++ b/src/pages/docs/ai-transport/features/database-hydration.mdx
@@ -0,0 +1,130 @@
+---
+title: "Database hydration"
+meta_description: "Hydrate an AI conversation from your own database with AI Transport and reconcile it with the live Ably channel, with no gap and no duplicate."
+meta_keywords: "database hydration, conversation history, AI Transport, Ably, retention, seam, loadUntil, persistence"
+intro: "Store AI conversation history in your own database. Database hydration reconciles the history you have stored with the live AI Transport session."
+---
+
+Database hydration is the pattern of treating your own database as the durable record of a conversation and reconciling it with the live session each time the conversation loads. Use it when your application already stores conversation history for its own features, such as search, analytics, or audit, or when conversations need to stay available longer than the channel [retention period](/docs/storage-history/storage).
+
+You keep the full AI Transport session for everything live. Resumable token streaming, multi-device continuity, automatic reconnection, and bidirectional control all still run over the session; database hydration changes only where long-term history lives. The session carries live activity, and your own database becomes the durable, queryable record of the conversation.
+
+<Aside data-type='note'>
+Database hydration currently supports linear conversations only. Messages you have persisted cannot be edited or regenerated, because branch-aware hydration is not yet available. Support for branching conversations is coming soon.
+</Aside>
+
+Your agent persists the messages for each completed run to your database when the run completes. When a client or the agent later loads the conversation, it seeds from the database and then loads from the session only the messages newer than the last one it stored (the seam), joining the two into a single conversation with no gaps or duplicates.
+
+On the client, hydration is a single call. Give `useMessagesWithSeed` your session view and the stored seed, and it reconciles them with the live session:
+
+<Code>
+```javascript
+const messages = useMessagesWithSeed({ view: session.view, seed, getMessageId: (m) => m.id });
+```
+</Code>
+
+Hydration has two mirrored sides: the agent rebuilds the model context, and the client rebuilds the UI. Wire up the agent first, then the client.
+
+## Hydrate the agent <a id="server"/>
+
+The agent rebuilds the model context from your store and the live session. Seed the prior conversation from your store, take the newest stored id as the seam, and call `run.view.loadUntil` to fetch the not-yet-stored tail. The view drives the paging itself, which also folds in this invocation's triggering input message from channel history:
+
+<Code>
+```javascript
+const session = createAgentSession({ client: ably, channelName: invocation.sessionName });
+await session.connect();
+const run = session.createRun(invocation, { signal: req.signal });
+
+// Seed the prior conversation from your store; the newest stored message is the seam.
+const seed = loadMessages(invocation.sessionName);
+const seamId = seed.at(-1)?.id;
+
+// loadUntil pages run.view back to the seam and returns only the messages newer
+// than it (the not-yet-stored tail). It drives the paging itself, which also
+// folds in this invocation's triggering input from channel history.
+const tail = await run.view.loadUntil((m) => m.message.id === seamId);
+await run.start();
+
+const conversation = [...seed, ...tail.map((m) => m.message)];
+// ...stream the model response with `conversation` as the message history...
+```
+</Code>
+
+## Persist the completed run <a id="persist"/>
+
+Persist a run once it completes, because a completed run is immutable. While a run is in flight its messages are still changing: tokens append, tool calls resolve, an assistant message grows. Once the run reaches a terminal state its messages can no longer be mutated, so it is the natural atomic unit to write to your store, and a write keyed by `message.id` is safe to repeat.
+
+After the model response streams, persist the run's messages. `run.messages` is a `BaseRun` accessor that returns the run's entire contribution: its triggering input plus all of its streamed output across any suspend and resume. A turn that suspends for a client-side tool result and resumes under the same run therefore still persists as one lossless unit. Persist only completed runs.
+
+<Code>
+```javascript
+const runMessages = run.messages;
+await run.end(outcome);
+if (outcome.reason === 'complete') await appendMessages(invocation.sessionName, runMessages);
+```
+</Code>
+
+Every send introduces at most one new message and triggers exactly one run, so the union of all completed runs' messages reconstructs the conversation with no gaps and no duplicates.
+
+## Hydrate the client <a id="client"/>
+
+The client reconciles the same way as the agent, over its own session view. Seed from your store, then drive `session.view.loadUntil` to fetch the tail newer than the seam and compose the two:
+
+<Code>
+```javascript
+const seed = loadStoredMessages(conversationId);
+const seamId = seed.at(-1)?.id;
+
+const tail = await session.view.loadUntil((m) => m.message.id === seamId);
+const conversation = [...seed, ...tail.map((m) => m.message)];
+```
+</Code>
+
+In React, `useMessagesWithSeed` wraps that walk. Pass your `session.view` and the stored seed, and it returns the composed conversation, kept current as new messages stream in:
+
+<Code>
+```javascript
+const messages = useMessagesWithSeed({ view: session.view, seed, getMessageId: (m) => m.id });
+```
+</Code>
+
+If you use the Vercel AI SDK's `useChat`, [`useMessageSync`](/docs/ai-transport/api/react/vercel/use-message-sync) runs the same reconciliation against `useChat`'s message state from a `messages` seed, so you keep hydration without leaving `useChat`.
+
+## How reconciliation works <a id="how-it-works"/>
+
+Both sides reconcile against the same point, the seam: the newest message your store already holds. Its domain `message.id` is the only id shared by both sides. It is the last thing you persisted, and the same id rides on the channel, because the transport's internal `codecMessageId` never leaves the channel. That makes the domain id the one stable join key.
+
+`View.loadUntil(predicate, signal?)` pages the view backward (through `loadOlder` under the hood) until a message matches the predicate, then returns only the messages strictly newer than it. The seam is an exclusive floor: the matched message is not returned, because your store already holds it, so composing `[...seed, ...tail]` drops exactly one overlap and leaves no gap.
+
+When the store is empty there is no seam. The predicate never matches, so `loadUntil` pages the whole conversation, and hydration behaves exactly like loading history from the channel.
+
+Reconciliation relies on the conversation being linear: each run is persisted whole before the next is sent, and a concurrent send cancels the active run, so there are never two unpersisted runs at once.
+
+## FAQ <a id="faq"/>
+
+### Do I need a database? <a id="faq-database"/>
+
+Only to retain conversations beyond your Ably retention window. Within retention, the channel is the source of truth and [history and replay](/docs/ai-transport/features/history) loads everything from the channel with no store. Add a database when you need conversations to outlive the retention policy.
+
+### What do I persist, the whole conversation or just the latest run? <a id="faq-what-to-persist"/>
+
+Persist each completed run's messages, which is `run.messages`: the run's triggering input plus its streamed output. The union of all runs reconstructs the whole conversation, so you never re-serialise the entire conversation on each run.
+
+### What if the store is behind the channel? <a id="faq-store-behind"/>
+
+That is the expected state on reload. The seam is the newest message your store holds, and `loadUntil` returns the channel messages strictly newer than it. Composing the seed with that tail fills the gap, so a store that lags the channel by several runs still produces a gapless conversation.
+
+### How does this differ from scroll-back history? <a id="faq-vs-scrollback"/>
+
+Scroll-back through [history and replay](/docs/ai-transport/features/history) pages the channel backward within retention and never touches a database. Database hydration seeds the conversation from your own store and reconciles the store with the channel at the seam, so it covers the messages retention has already dropped.
+
+### Why is the domain id the seam and not `codecMessageId`? <a id="faq-seam-id"/>
+
+`codecMessageId` is the transport's internal id and never leaves the channel, so it is not available in your store. The domain `message.id` is the id you control and persist, and the same id appears on the channel, which makes it the only stable join key between the two sides.
+
+## Related features <a id="related"/>
+
+- [History and replay](/docs/ai-transport/features/history): load and paginate conversation history from the channel within retention.
+- [Multi-device sessions](/docs/ai-transport/features/multi-device): how the same hydrated conversation appears across a user's devices.
+- [`useMessagesWithSeed`](/docs/ai-transport/api/react/core/use-messages-with-seed): the core React hook that composes a seed with the live view.
+- [`useMessageSync`](/docs/ai-transport/api/react/vercel/use-message-sync): the Vercel hook that reconciles a `useChat` seed with the channel.

From f00c768cc42ba7f1345d8fe5dcef4481b59eed78 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:26:00 +0100
Subject: [PATCH 03/15] AI Transport docs: align the run model concepts with
 v0.4.0

Update the concept tier for the v0.4.0 run read-model and the input-event
watcher that replaces the history-scan lookup.

- runs.mdx: ActiveRun -> ClientRun; runId is now synchronous (empty until
  run-start), awaited via the new `started`; add a "Read a Run from either
  side" section for the shared BaseRun read-model (runId/status/error/
  messages) and the per-side verbs; the agent rehydrates by draining
  run.view rather than loadConversation; note one input per send.
- invocations.mdx: ClientRun naming; AgentRun.start awaits the input-event
  watcher (live or channel history) instead of a rewind+live lookup.
- connections.mdx: branch navigation via branchSelection().select.

AIT-1090
---
 .../ai-transport/concepts/connections.mdx     |  4 +--
 .../ai-transport/concepts/invocations.mdx     | 14 ++++----
 src/pages/docs/ai-transport/concepts/runs.mdx | 35 ++++++++++++-------
 3 files changed, 32 insertions(+), 21 deletions(-)

diff --git a/src/pages/docs/ai-transport/concepts/connections.mdx b/src/pages/docs/ai-transport/concepts/connections.mdx
index 7fee460c43..d68ecbc06c 100644
--- a/src/pages/docs/ai-transport/concepts/connections.mdx
+++ b/src/pages/docs/ai-transport/concepts/connections.mdx
@@ -50,8 +50,8 @@ A connection moves through four stages. Construct it with `createClientSession`
 Several `ClientSession` instances can be open against the same session simultaneously. Each one independently:
 
 - Materialises the tree from the channel (the same tree, on the wire).
-- Selects its own branch via the [`view.selectSibling`](/docs/ai-transport/api/javascript/core/client-session#view) method.
-- Holds its own pagination window over older Runs.
+- Selects its own branch via the [`view.branchSelection`](/docs/ai-transport/api/javascript/core/client-session#view) handle's `select` method.
+- Holds its own pagination window over older messages.
 
 What they share is the channel-backed state. A message one client publishes lands on every other client's tree via the channel subscription. A cancel one client publishes is observed by the agent (and by every other client) through their own subscriptions.
 
diff --git a/src/pages/docs/ai-transport/concepts/invocations.mdx b/src/pages/docs/ai-transport/concepts/invocations.mdx
index 60367f66de..e35f233ea5 100644
--- a/src/pages/docs/ai-transport/concepts/invocations.mdx
+++ b/src/pages/docs/ai-transport/concepts/invocations.mdx
@@ -9,7 +9,7 @@ An Invocation is the trigger posted to an agent endpoint to start or continue a
 
 ![Diagram showing the channel content path and the HTTP Invocation addressing path converging at the agent](../../../../images/content/diagrams/ait-concepts-invocations.png)
 
-The client SDK mints `inputEventId` (and the input's `codecMessageId`) when you call `view.send()` / `regenerate()` / `edit()` and stamps them on the channel publish. The HTTP POST is owned by your application code (or by the bundled Vercel [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)): call `activeRun.toInvocation().toJSON()` to get the wire body and POST it to the agent. The agent mints the `runId` and `invocationId` when it creates the Run, and returns them on the HTTP response so the caller can observe them.
+The client SDK mints `inputEventId` (and the input's `codecMessageId`) when you call `view.send()` / `regenerate()` / `edit()` and stamps them on the channel publish. The HTTP POST is owned by your application code (or by the bundled Vercel [`ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)): call `clientRun.toInvocation().toJSON()` to get the wire body and POST it to the agent. The agent mints the `runId` and `invocationId` when it creates the Run, and returns them on the HTTP response so the caller can observe them.
 
 The same Run can be triggered more than once: a fresh send triggers a fresh Invocation; a tool result follow-up creates another; a retry after a serverless cold start creates another. Each HTTP request produces one agent-minted `invocationId`. The `runId` is fresh on the first invocation and reused on every subsequent continuation.
 
@@ -17,7 +17,7 @@ The same Run can be triggered more than once: a fresh send triggers a fresh Invo
 
 The client and the agent are separated by an unreliable network and a stateless HTTP boundary. The client publishes input on the channel and your application code posts to the agent endpoint. The agent receives the POST, possibly minutes later, and needs to know exactly which work to do:
 
-- Which input event triggered the work, so the agent's [`Run.start`](/docs/ai-transport/api/javascript/core/agent-session#run-start) can wait for the exact event on the channel.
+- Which input event triggered the work, so the agent's [`AgentRun.start`](/docs/ai-transport/api/javascript/core/agent-session#run-start) can wait for the exact event on the channel.
 - Which channel, since the agent doesn't know the session's channel name except via the trigger.
 
 These two identifiers are the Invocation's payload (`inputEventId`, `sessionName`). They're carried in the HTTP POST body so the agent has them before the channel is observable. Everything else lives on the channel: run identity is resolved from the triggering input event's wire headers (the agent mints `runId` for a fresh run, or reads the existing `runId` off the input event for a continuation). The `invocationId` is minted by the agent per HTTP request.
@@ -28,12 +28,12 @@ An `InvocationData` is the wire shape: the JSON body in the POST.
 
 | Field | What it carries |
 | --- | --- |
-| `inputEventId` | The input event on the channel that triggered this invocation. The agent's `Run.start()` waits for the channel message carrying this `event-id` (rewind + live). |
+| `inputEventId` | The input event on the channel that triggered this invocation. The agent's `AgentRun.start()` awaits the channel message carrying this `event-id`; the run's input-event watcher matches it whether it arrives live or already sits in channel history. |
 | `sessionName` | The session's logical name, used as the Ably channel name. |
 
-The `Invocation` class is the runtime view of that data. The client side uses `ActiveRun.toInvocation()` to obtain one from a returned `ActiveRun`; the agent side uses `Invocation.fromJSON(data)` to construct one from the parsed POST body, then hands it to `session.createRun(invocation, runtime?)`. `createRun` mints the `invocationId` (one per HTTP request) and, for a fresh run, the `runId`; for a continuation the agent reads the existing `runId` off the triggering input event's wire headers. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe them.
+The `Invocation` class is the runtime view of that data. The client side uses `ClientRun.toInvocation()` to obtain one from a returned `ClientRun`; the agent side uses `Invocation.fromJSON(data)` to construct one from the parsed POST body, then hands it to `session.createRun(invocation, runtime?)`. `createRun` mints the `invocationId` (one per HTTP request) and, for a fresh run, the `runId`; for a continuation the agent reads the existing `runId` off the triggering input event's wire headers. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe them.
 
-End-to-end: the client publishes the input event on the channel and gets back an `ActiveRun`. The client knows `inputCodecMessageId` immediately, before the agent has minted the run; the `runId` resolves later, once the agent's `ai-run-start` event lands. The application POSTs `activeRun.toInvocation().toJSON()` to the agent endpoint. The agent rebuilds the Invocation, calls `createRun` (which mints `invocationId` and resolves `runId` either by minting for a fresh run or by reading the input event for a continuation), and `run.start()` waits for the matching input event to arrive on the channel via rewind and live. Output events the agent publishes carry the `run-id`, `invocation-id`, and `input-codec-message-id` headers; the client resolves `ActiveRun.runId` once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the original caller can observe the agent-minted identifiers directly.
+End-to-end: the client publishes the input event on the channel and gets back a `ClientRun`. The client knows `inputCodecMessageId` immediately, before the agent has minted the run; `clientRun.runId` is populated later, once the agent's `ai-run-start` event lands (await `clientRun.started`). The application POSTs `clientRun.toInvocation().toJSON()` to the agent endpoint. The agent rebuilds the Invocation, calls `createRun` (which mints `invocationId` and resolves `runId` either by minting for a fresh run or by reading the input event for a continuation, and arms the run's input-event watcher), and `run.start()` awaits the matching input event folding into the tree, whether it arrives live or already sits in channel history. Output events the agent publishes carry the `run-id`, `invocation-id`, and `input-codec-message-id` headers; the client reads `clientRun.runId` once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the original caller can observe the agent-minted identifiers directly.
 
 ## What the Invocation layer requires <a id="requires"/>
 
@@ -42,7 +42,7 @@ End-to-end: the client publishes the input event on the channel and gets back an
 | Stable identity | The triggering input event must be addressable from both sides. The client stamps `event-id` on the channel publish, and your code posts the same `inputEventId` in the body. If they diverged, the agent's lookup would fail. |
 | Deterministic generation | The client mints `inputEventId` and `codecMessageId` inside `view.send()` (and the other write methods). Defaults to `crypto.randomUUID()`; override via [`SendOptions`](/docs/ai-transport/api/javascript/core/client-session#view) for deterministic tests. The agent mints `runId` and `invocationId` per request; supply `RunRuntime.runId` / `RunRuntime.invocationId` to override in tests. |
 | Idempotency | The agent endpoint may receive the same Invocation more than once (network retry, queue redelivery). The agent must treat duplicate Invocations safely, typically by checking whether the input event has already produced a Run on the channel. |
-| Decoupled timing | The POST may arrive before, simultaneously with, or after the input event on the channel. The agent's `Run.start()` waits for the input event with rewind + live lookup, so the order doesn't matter. |
+| Decoupled timing | The POST may arrive before, simultaneously with, or after the input event on the channel. The agent's `AgentRun.start()` awaits the input event through the run's input-event watcher, which matches it whether it already sits in channel history or arrives live, so the order doesn't matter. |
 | Continuation support | A tool-result delivery or a regenerate produces a new Invocation; the client stamps the existing `run-id` on the new input event's wire headers when publishing. The agent's `createRun` reads that `run-id` from the input event instead of minting a fresh one, and the SDK treats it as a continuation. |
 
 ## Receive an Invocation <a id="receive"/>
@@ -69,7 +69,7 @@ export async function POST(req) {
 ```
 </Code>
 
-On the client, the [`view.send`](/docs/ai-transport/api/javascript/core/client-session#view) call generates the identifiers, stamps them on the channel publish, and returns the `ActiveRun`. Your application code (or the [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) wrapper) calls `activeRun.toInvocation().toJSON()` to build the POST body and sends it to the agent endpoint.
+On the client, the [`view.send`](/docs/ai-transport/api/javascript/core/client-session#view) call generates the identifiers, stamps them on the channel publish, and returns the `ClientRun`. Your application code (or the [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) wrapper) calls `clientRun.toInvocation().toJSON()` to build the POST body and sends it to the agent endpoint.
 
 ## Read next <a id="next"/>
 
diff --git a/src/pages/docs/ai-transport/concepts/runs.mdx b/src/pages/docs/ai-transport/concepts/runs.mdx
index 071273d1c5..af4e5c4d17 100644
--- a/src/pages/docs/ai-transport/concepts/runs.mdx
+++ b/src/pages/docs/ai-transport/concepts/runs.mdx
@@ -24,7 +24,7 @@ A Run has four invariants that the SDK enforces on every channel:
 - A unique `runId`.
 - A bracketing pair of lifecycle events on the channel: `ai-run-start` and `ai-run-end`.
 - An owner: the `clientId` of the Ably client that published `ai-run-start`.
-- A terminal `RunEndReason` once it ends: `'complete'`, `'cancelled'`, or `'error'`. (A Run that pauses awaiting input takes `RunInfo.status === 'suspended'` via `Run.suspend()`, which is non-terminal.)
+- A terminal `RunEndReason` once it ends: `'complete'`, `'cancelled'`, or `'error'`. (A Run that pauses awaiting input takes `RunInfo.status === 'suspended'` via `AgentRun.suspend()`, which is non-terminal.)
 
 Within those brackets, the Run owns a window of channel messages: the user input that triggered it, the agent's streamed outputs, any tool-call or tool-result messages. The conversation [Tree](/docs/ai-transport/concepts/conversation-tree) groups those messages into a `RunNode`; the [View](/docs/ai-transport/api/javascript/core/client-session#view) surfaces projection-free [`RunInfo`](/docs/ai-transport/api/javascript/core/client-session#view) snapshots for the UI.
 
@@ -37,7 +37,7 @@ A Run is triggered by an [`Invocation`](/docs/ai-transport/concepts/invocations)
 | Stable identity | The same `runId` must be readable to every participant: the client that started the Run, every other connected client, the agent process. Without it, cancellation has no target and observation has no scope. |
 | Lifecycle brackets | `ai-run-start`, `ai-run-suspend`, `ai-run-resume`, and `ai-run-end` mark the Run on the wire. A view filtering "active Runs" reads `RunInfo.status === 'active'`; `'suspended'` and the terminal `RunEndReason` values cover the other states. |
 | Cancel routing | A cancel message names a `runId`. The agent's [`Run.abortSignal`](/docs/ai-transport/api/javascript/core/agent-session#run) fires only for matching cancels, so unrelated Runs on the same session continue. |
-| Durable execution | An agent can restart its process mid-Run (serverless cold start, container redeploy). The Run's identity plus the channel's persistence let the new agent rehydrate via [`Run.loadConversation`](/docs/ai-transport/api/javascript/core/agent-session#load-conversation) and continue without the client noticing. |
+| Durable execution | An agent can restart its process mid-Run (serverless cold start, container redeploy). The Run's identity plus the channel's persistence let the new agent rehydrate by draining its leaf-pinned [`run.view`](/docs/ai-transport/api/javascript/core/agent-session#run) from channel history and continue without the client noticing. |
 | Multiple participants | Several clients may observe the same Run (multi-device, support handover). They all see the lifecycle events; they all hold the same `RunInfo`. |
 
 ## Understand the Run lifecycle <a id="lifecycle"/>
@@ -53,30 +53,41 @@ A Run progresses from start to terminal end. Along the way it can pause to wait
 
 A Run is the unit of cancellation. There is no user-facing cancel below the Run level. Internal failures (a stream dying, a model call retrying, a serverless cold start) fail the *execution attempt*, not the Run; the Run stays active and the SDK retries underneath.
 
+## Read a Run from either side <a id="read-model"/>
+
+Both sides of a Run expose the same read-model, so the same accessor means the same thing on the client and the agent. A client's `view.send()` returns a `ClientRun`; an agent's `createRun()` returns an `AgentRun`. Each carries:
+
+- `runId`: the Run's identifier. Known synchronously on the agent; on the client it is empty until the agent's run-start is observed (await `clientRun.started` first).
+- `status`: the lifecycle status, one of `'active'`, `'suspended'`, `'complete'`, `'cancelled'`, or `'error'`, read live off the [conversation tree](/docs/ai-transport/concepts/conversation-tree).
+- `error`: the terminal error, present exactly when `status` is `'error'`.
+- `messages`: the Run's whole turn, the triggering input message followed by its streamed output. This is the unit to persist; see [database hydration](/docs/ai-transport/features/database-hydration).
+
+Each side then adds its own verbs. The client's `ClientRun` adds `started` and `cancel()`; the agent's `AgentRun` adds `located` (resolves once the triggering input folds into the tree) and the lifecycle methods `start()`, `pipe()`, `suspend()`, and `end()`.
+
 ## Trigger a Run <a id="trigger"/>
 
-A minimal client-side send returns an `ActiveRun` that exposes the Run's identity and a per-Run cancel. The application then POSTs `activeRun.toInvocation().toJSON()` to its agent endpoint to wake the agent; see [Invocations](/docs/ai-transport/concepts/invocations).
+A minimal client-side send returns a `ClientRun` that exposes the Run's identity and a per-Run cancel. Each send introduces at most one new message and triggers exactly one Run. The application then POSTs `clientRun.toInvocation().toJSON()` to its agent endpoint to wake the agent; see [Invocations](/docs/ai-transport/concepts/invocations).
 
 <Code>
 ```javascript
-const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+const clientRun = await session.view.send(UIMessageCodec.createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
 }));
 
-// The agent assigns the runId on the server, so activeRun.runId is a
-// Promise. Await it to read the id.
-const runId = await activeRun.runId;
-console.log('Run started:', runId);
+// The agent mints the runId on the server, so clientRun.runId is empty until
+// the agent's run-start is observed. Await `started`, then read the id.
+await clientRun.started;
+console.log('Run started:', clientRun.runId);
 
-// Stop button: activeRun.cancel() works immediately, even before
-// the runId promise resolves.
-await activeRun.cancel();
+// Stop button: clientRun.cancel() works immediately, even before
+// the run-start has been observed.
+await clientRun.cancel();
 ```
 </Code>
 
-On the agent side, the symmetric primitive is [`AgentSession.createRun(invocation, runtime?)`](/docs/ai-transport/api/javascript/core/agent-session#create-run). The agent mints `runId` (for a fresh run) or reads the existing `runId` off the triggering input event (for a continuation), and stamps it on every event it publishes; the client observes it via `ActiveRun.runId`.
+On the agent side, the symmetric primitive is [`AgentSession.createRun(invocation, runtime?)`](/docs/ai-transport/api/javascript/core/agent-session#create-run). The agent mints `runId` (for a fresh run) or reads the existing `runId` off the triggering input event (for a continuation), and stamps it on every event it publishes; the client reads it from `clientRun.runId` once `clientRun.started` resolves.
 
 ## Run concurrent Runs <a id="concurrent"/>
 

From 50edad062dbc14dba5916a4f298427d63ab14fe1 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:31:32 +0100
Subject: [PATCH 04/15] AI Transport docs: sweep the core API reference for
 v0.4.0

client-session.mdx:
- View -> ClientView surface; branchSelection().select replaces
  selectSibling; loadOlder now resolves to the revealed page and loadUntil
  is documented; send/regenerate/edit return ClientRun and take one new
  message per send.
- Drop the removed ClientSessionOptions.messages seed; add historyPageSize.
- ActiveRun -> ClientRun; runId is synchronous (empty until run-start),
  awaited via started.

agent-session.mdx:
- Run -> AgentRun extending BaseRun (runId/status/error/messages); add the
  leaf-pinned run.view and located; rewrite start() around the input-event
  watcher (no more inputEventLookupTimeoutMs / InputEventNotFound 104010).
- Remove the already-removed addEvents/EventsNode, loadProjection, and
  loadConversation/LoadConversationOptions surfaces; rewrite conversation
  hydration to drain run.view.
- Replace the onError option with on('error'); historyPageSize replaces the
  input-event lookup/buffer/rewind options; close() is async.

AIT-1090
---
 .../api/javascript/core/agent-session.mdx     | 183 ++++++++----------
 .../api/javascript/core/client-session.mdx    |  43 ++--
 2 files changed, 104 insertions(+), 122 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
index d49a322788..4ffcd5ae80 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
@@ -7,7 +7,7 @@ redirect_from:
   - /docs/ai-transport/api/javascript/server-transport
 ---
 
-The `AgentSession` is the server-side counterpart to [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session). It subscribes to the channel for cancel signals and creates `Run` instances that publish lifecycle events, user messages, and streamed assistant output.
+The `AgentSession` is the server-side counterpart to [`ClientSession`](/docs/ai-transport/api/javascript/core/client-session). It subscribes to the channel for cancel signals and creates `AgentRun` instances that publish lifecycle events, user messages, and streamed assistant output.
 
 Construct one with `createAgentSession` from the core entry point. For Vercel `UIMessage` channels, use the pre-bound factory from [`@ably/ai-transport/vercel`](/docs/ai-transport/api/javascript/vercel/chat-transport) instead.
 
@@ -76,14 +76,13 @@ const session = createAgentSession({
 | channelName | required | The channel to publish to. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
 | codec | required | The codec used to encode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
 | channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects via [`object`](#properties). Omit to attach with the default mode set. The session requests the union, so extra modes never drop the modes AI Transport relies on. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `Ably.ChannelMode[]` |
+| historyPageSize | optional | Wire-message limit fetched per channel-history round trip, used by every `run.view` pagination on this session. Independent of `loadOlder`'s reveal `limit`: it tunes fetch cost, not reveal granularity. Defaults to 100. | Number |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
-| onError | optional | Called with non-fatal session-level errors not scoped to any run (cancel listener failures, channel continuity loss). | `(error: Ably.ErrorInfo) => void` |
-| inputEventLookupTimeoutMs | optional | How long `Run.start()` waits for the run's input event(s) to arrive on the channel before rejecting with `InputEventNotFound`. Defaults to 30000. | Number |
-| inputEventBufferLimit | optional | Maximum number of distinct input events that may be buffered while waiting for `Run.start()` to register a lookup listener. FIFO-evicted when exceeded. Defaults to 200. | Number |
-| rewindWindow | optional | Channel rewind applied when the agent attaches. Passed verbatim to Ably's `params.rewind`. Accepts duration strings (`"2m"`, `"30s"`) or message counts as strings (`"50"`). Defaults to `"2m"`. | String |
 
 </Table>
 
+Subscribe to non-fatal session errors with [`on('error')`](#on) rather than a constructor option.
+
 ### Returns <a id="constructor-returns"/>
 
 `AgentSession<TOutput, TProjection, TMessage>`. The session instance. Call [`connect()`](#connect) before [`createRun`](#create-run).
@@ -92,7 +91,7 @@ const session = createAgentSession({
 
 <MethodSignature>{`connect(): Promise<void>`}</MethodSignature>
 
-Subscribe to the cancel channel and implicitly attach. Idempotent: subsequent calls return the same promise. All `Run` methods (`start`, `addEvents`, `pipe`, `suspend`, `end`) throw `InvalidArgument` until `connect()` resolves.
+Subscribe to the channel and implicitly attach. The subscribe is unfiltered so channel-history-replayed input events fold into the tree, where each run's input-event watcher can match its trigger. Idempotent: subsequent calls return the same promise. All `AgentRun` methods (`start`, `pipe`, `suspend`, `end`) throw `InvalidArgument` until `connect()` has been called.
 
 <Code>
 ```javascript
@@ -106,9 +105,9 @@ await session.connect();
 
 ## Create a run <a id="create-run"/>
 
-<MethodSignature>{`createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): Run<TOutput, TProjection, TMessage>`}</MethodSignature>
+<MethodSignature>{`createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): AgentRun<TOutput, TProjection, TMessage>`}</MethodSignature>
 
-Create a new `Run` from an `Invocation`. Synchronous: no channel activity until [`Run.start`](#run-start) is called. The Run is registered for cancel routing immediately so early cancels fire the `abortSignal`.
+Create a new `AgentRun` from an `Invocation`. Returns synchronously and arms the run's input-event watcher (a passive pre-scan of the tree plus a listener for the trigger's arrival); it publishes nothing to the channel until [`AgentRun.start`](#run-start) is called. The run is registered for cancel routing immediately so early cancels fire the `abortSignal`.
 
 <Code>
 ```javascript
@@ -153,11 +152,11 @@ const run = session.createRun(invocation, { signal: req.signal });
 
 ### Returns <a id="create-run-returns"/>
 
-A `Run<TOutput, TProjection, TMessage>` handle for publishing lifecycle events, user messages, and streamed output. See [Run interface](#run) below.
+An `AgentRun<TOutput, TProjection, TMessage>` handle for publishing lifecycle events, user messages, and streamed output. See [AgentRun interface](#run) below.
 
-## Run <a id="run"/>
+## AgentRun <a id="run"/>
 
-The handle returned by [`createRun`](#create-run).
+The handle returned by [`createRun`](#create-run). It extends the shared `BaseRun` read-model (`runId`, `status`, `error`, `messages`) with the agent's lifecycle surface.
 
 ### Properties
 
@@ -165,19 +164,14 @@ The handle returned by [`createRun`](#create-run).
 
 | Property | Description | Type |
 | --- | --- | --- |
-| runId | The Run's unique identifier. | String |
+| runId | The Run's unique identifier. Known synchronously on the agent (it mints the id for a fresh run, or reads it off the triggering input event for a continuation). | String |
+| status | The Run's lifecycle status, read live off the tree. | `RunStatus` |
+| error | The terminal error, present exactly when `status` is `'error'`. | `Ably.ErrorInfo` or Undefined |
+| messages | This Run's whole turn: its triggering input message followed by its own streamed output, deduplicated by `codecMessageId`. The unit to persist. See [Hydrate the conversation](#conversation-hydration). | `TMessage[]` |
 | invocationId | The invocation id minted by the agent for this `createRun` call (one per HTTP request). Readable synchronously; the application returns it on the HTTP response. The agent stamps it on every event it publishes for this invocation. | String |
 | abortSignal | `AbortSignal` scoped to this Run. Fires when a cancel event arrives. | `AbortSignal` |
-| view | Read-only view of the conversation messages associated with this Run. | <Table id='RunView'/> |
-| messages | The conversation messages this Run should feed to the model. See [Conversation hydration](#conversation-hydration). | `TMessage[]` |
-
-</Table>
-
-<Table id='RunView' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| messages | Invocation input messages handed to this Run. No branch awareness today. | `MessageNode<TMessage>[]` |
+| view | Read-only, leaf-pinned `View<TMessage>` of this Run's branch, from its triggering input back to the conversation root. Drain it with `loadOlder()` for ancestor context to feed the model. Empty until the trigger folds into the tree. See [Hydrate the conversation](#conversation-hydration). | `View<TMessage>` |
+| located | Resolves when this Run's triggering input folds into the tree (live or via a `view.loadOlder()` page). [`start`](#run-start) awaits it internally; await it directly only to read the trigger before deciding how to start. | `Promise<void>` |
 
 </Table>
 
@@ -185,9 +179,9 @@ The handle returned by [`createRun`](#create-run).
 
 <MethodSignature>{`start(): Promise<void>`}</MethodSignature>
 
-Publish the `ai-run-start` event to the channel and wait for the Run's input event to arrive (rewind + live wait). Must be called before `pipe`, `addEvents`, `suspend`, or `end`.
+Await [`located`](#run) (the run's input-event watcher resolves the trigger, whether it arrives live or already sits in channel history), then read the trigger's wire headers and publish the opening lifecycle event (`ai-run-start`, or `ai-run-resume` for a continuation). Must be called before `pipe`, `suspend`, or `end`.
 
-Rejects with `InputEventNotFound` (code `104010`) if the input event for this invocation does not arrive within `inputEventLookupTimeoutMs`. Surface the rejection as a non-2xx response so the client's pending send fails.
+There is no built-in deadline: `start()` does not time out waiting for the trigger. It rejects only if the run is cancelled or the session is closed before the trigger folds in. Race it against your own timeout if you need one.
 
 ### Pipe the response stream <a id="pipe"/>
 
@@ -229,69 +223,6 @@ Pipe a `ReadableStream` of outputs through the encoder to the channel. Returns w
 
 </Table>
 
-### Add events to existing messages <a id="add-events"/>
-
-<MethodSignature>{`addEvents(nodes: EventsNode<TOutput>[]): Promise<void>`}</MethodSignature>
-
-Publish events targeting existing messages. Each node specifies a `codecMessageId` and the events to apply. Used for cross-Run updates such as tool result delivery after approval.
-
-#### Parameters <a id="add-events-params"/>
-
-<Table id='AddEventsParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| nodes | required | Events to apply, each tagged with the codec-message-id of the message to update. | <Table id='EventsNode'/> |
-
-</Table>
-
-<Table id='EventsNode' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| kind | Discriminator: `'event'`. | `'event'` |
-| codecMessageId | The codec-message-id of the existing message to update. | String |
-| events | Outputs to apply to the target message. | `TOutput[]` |
-
-</Table>
-
-### Load a Run's projection <a id="load-projection"/>
-
-<MethodSignature>{`loadProjection(): Promise<TProjection>`}</MethodSignature>
-
-Fetch every channel message bound to this Run and fold them through the codec into a single projection. Use this to reconstruct a single Run's full state (including client-published tool-output amends the agent did not observe live) when resuming a suspended Run before piping fresh output. The companion to [`loadConversation`](#load-conversation), which walks ancestors; `loadProjection` covers only the current Run.
-
-The caller extracts what they need via [`Codec.getMessages`](/docs/ai-transport/api/javascript/core/codec).
-
-#### Returns <a id="load-projection-returns"/>
-
-`Promise<TProjection>`. The codec projection produced by folding every event for this Run in serial order.
-
-### Load the full conversation <a id="load-conversation"/>
-
-<MethodSignature>{`loadConversation(options?: LoadConversationOptions): Promise<TMessage[]>`}</MethodSignature>
-
-Reconstruct the full multi-turn conversation by walking the ancestor Run chain and concatenating each Run's messages, oldest turn first. After this call, `Run.messages` returns the complete conversation, ready to pass to the LLM.
-
-#### Parameters <a id="load-conversation-params"/>
-
-<Table id='LoadConversationParameters'>
-
-| Parameter | Required | Description | Type |
-| --- | --- | --- | --- |
-| options | optional | History pagination tuning. | <Table id='LoadConversationOptions'/> |
-
-</Table>
-
-<Table id='LoadConversationOptions' hidden>
-
-| Property | Description | Type |
-| --- | --- | --- |
-| pageLimit | Wire messages per history page. Defaults to 200. | Number |
-| maxMessages | Maximum wire messages collected across all pages. Defaults to 2000. | Number |
-
-</Table>
-
 ### Suspend the run <a id="run-suspend"/>
 
 <MethodSignature>{`suspend(): Promise<void>`}</MethodSignature>
@@ -310,8 +241,8 @@ Publish the `ai-run-end` event to the channel terminally and clean up. `params`
 
 `RunEndParams` is discriminated on `reason`:
 
-- `{ reason: 'complete' | 'cancelled' }` — a non-error terminal reason; carries no `error`.
-- `{ reason: 'error', error? }` — the run ended in error; `error` is an optional `Ably.ErrorInfo` to surface to clients. Omit it to end in error without detail.
+- `{ reason: 'complete' | 'cancelled' }`: a non-error terminal reason that carries no `error`.
+- `{ reason: 'error', error? }`: the run ended in error. `error` is an optional `Ably.ErrorInfo` to surface to clients. Omit it to end in error without detail.
 
 <Table id='RunEndParams'>
 
@@ -322,11 +253,43 @@ Publish the `ai-run-end` event to the channel terminally and clean up. `params`
 
 </Table>
 
+## Subscribe to session errors <a id="on"/>
+
+<MethodSignature>{`on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void`}</MethodSignature>
+
+Subscribe to non-fatal session-level errors not scoped to any run: channel continuity loss (a re-attach with `resumed: false`, or `FAILED` / `SUSPENDED` / `DETACHED`), cancel-listener or attach failures, and any run-scoped error whose run supplied no `onError`. Returns an unsubscribe function. Once the session is closed this is a no-op.
+
+<Code>
+```javascript
+const unsubscribe = session.on('error', (error) => {
+  console.error('Session error:', error.code, error.message);
+});
+
+// later, when the listener is no longer needed
+unsubscribe();
+```
+</Code>
+
+### Parameters <a id="on-params"/>
+
+<Table id='OnParameters'>
+
+| Parameter | Required | Description | Type |
+| --- | --- | --- | --- |
+| event | required | The event to subscribe to. Currently only `'error'`. | `'error'` |
+| handler | required | Called with an [`ErrorInfo`](/docs/ai-transport/api/errors#errorinfo) for every non-fatal session error. | Function |
+
+</Table>
+
+### Returns <a id="on-returns"/>
+
+`() => void`. An unsubscribe function. Call it to remove the listener.
+
 ## Close the session <a id="close"/>
 
-<MethodSignature>{`close(): void`}</MethodSignature>
+<MethodSignature>{`close(): Promise<void>`}</MethodSignature>
 
-Unsubscribe from the channel and clear handlers. Local-state-only; does not end in-progress Runs. End each Run explicitly before closing the session.
+Cancel active runs, detach the channel the session attached, and clear handlers. Local-state-only for run lifecycle; it does not end in-progress Runs on the wire. End each Run explicitly before closing the session.
 
 ## Invocation <a id="invocation"/>
 
@@ -366,15 +329,28 @@ const invocation = Invocation.fromJSON(data);
 
 </Table>
 
-## Conversation hydration <a id="conversation-hydration"/>
+## Hydrate the conversation <a id="conversation-hydration"/>
+
+Two accessors expose conversation content, at different scopes:
 
-`Run.messages` returns different content depending on lifecycle stage:
+- `run.messages` is this Run's own turn: its triggering input plus its streamed output. This is the unit to persist, not the value to feed the model in a multi-turn conversation.
+- `run.view` is a read-only, leaf-pinned `View` of this Run's full branch, from its triggering input back to the conversation root. This is the value to feed the model.
 
-- Before [`start`](#run-start) resolves: empty array.
-- After `start`: the user-prompt messages looked up on the channel for this invocation.
-- After [`loadConversation`](#load-conversation): the full multi-turn conversation, with ancestor Run messages followed by the current Run's messages, oldest turn first.
+To rebuild the prior conversation for the model, drain `run.view` with `loadOlder()` (the sole history driver) for as much ancestor context as you want, then read `getMessages()`:
 
-Use [`loadConversation`](#load-conversation) before piping to the LLM in any conversation past the first turn.
+<Code>
+```javascript
+await run.start();
+
+// Drain the branch back to the root for full context.
+while (run.view.hasOlder()) {
+  await run.view.loadOlder();
+}
+const conversation = run.view.getMessages().map(({ message }) => message);
+```
+</Code>
+
+For database-backed hydration, page `run.view` back only to the newest stored message with [`loadUntil`](/docs/ai-transport/features/database-hydration) instead of draining to the root.
 
 ## RunEndReason <a id="run-end-reason"/>
 
@@ -384,7 +360,7 @@ A Run that pauses for external input (tool approval, human-in-the-loop) uses [`R
 
 ## Example <a id="example"/>
 
-An HTTP handler that sets up the session, creates a Run, loads the conversation, pipes the LLM stream, and ends the Run.
+An HTTP handler that sets up the session, creates a Run, rebuilds the conversation from `run.view`, pipes the LLM stream, and ends the Run.
 
 <Code>
 ```javascript
@@ -409,16 +385,21 @@ export async function POST(req: Request) {
 
   try {
     await run.start();
-    await run.loadConversation();
 
-    const llmStream = await callMyLLM(run.messages);
+    // Drain the run's branch back to the root for the model context.
+    while (run.view.hasOlder()) {
+      await run.view.loadOlder();
+    }
+    const conversation = run.view.getMessages().map(({ message }) => message);
+
+    const llmStream = await callMyLLM(conversation);
     const result = await run.pipe(llmStream);
     await run.end({ reason: result.reason });
   } catch (err) {
     await run.end({ reason: 'error' });
     throw err;
   } finally {
-    session.close();
+    await session.close();
   }
 
   return Response.json({ runId: run.runId, invocationId: run.invocationId });
diff --git a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
index d112bf3528..4da104e9ed 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
@@ -61,13 +61,13 @@ await session.connect();
 | runs | `() => RunInfo[]`. Visible Runs along the selected branch. | Function |
 | runOf | `(codecMessageId: string) => RunInfo \| undefined`. Run that owns the message. | Function |
 | run | `(runId: string) => RunInfo \| undefined`. Direct Run lookup by id. | Function |
-| branchSelection | `(codecMessageId: string) => BranchSelection`. Branch siblings at the anchor. | Function |
-| selectSibling | `(codecMessageId: string, index: number) => void`. Select a sibling at the anchor. | Function |
-| hasOlder | `() => boolean`. Whether older Runs can be loaded. | Function |
-| loadOlder | `(limit?: number) => Promise<void>`. Reveal older Runs. | Function |
-| send | `(events, options?) => Promise<ActiveRun>`. Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` to send a fresh user message. | Function |
-| regenerate | `(messageId, options?) => Promise<ActiveRun>`. Regenerate an assistant message. | Function |
-| edit | `(messageId, inputs, options?) => Promise<ActiveRun>`. Edit a user message. | Function |
+| branchSelection | `(codecMessageId: string) => BranchHandle`. The branch siblings at the anchor, plus a `select(index)` verb to switch between them. | Function |
+| hasOlder | `() => boolean`. Whether older messages can be revealed. | Function |
+| loadOlder | `(limit?: number) => Promise<CodecMessage<TMessage>[]>`. Reveal older messages, resolving to the revealed page (oldest-first); `[]` when nothing older was revealed. | Function |
+| loadUntil | `(predicate, signal?) => Promise<CodecMessage<TMessage>[]>`. Page older history back until `predicate` matches a message (the seam), then resolve to the messages newer than it. Drives database-backed hydration. | Function |
+| send | `(events, options?) => Promise<ClientRun<TMessage>>`. Send an input on the channel and fire a POST. At most one new message per send (it mints a fresh Run); the array form carries only wire-only inputs (tool results, approvals) for a continuation. Wrap a domain message via `codec.createUserMessage` to send a fresh user message. | Function |
+| regenerate | `(messageId, options?) => Promise<ClientRun<TMessage>>`. Regenerate an assistant message. | Function |
+| edit | `(messageId, inputs, options?) => Promise<ClientRun<TMessage>>`. Edit a user message. | Function |
 | on | `(event: 'update' \| 'ably-message' \| 'run', handler) => () => void`. Subscribe to view updates, raw Ably messages for visible nodes, or run lifecycle events. Returns an unsubscribe function. | Function |
 | close | `() => void`. Tear down the view. | Function |
 
@@ -104,8 +104,8 @@ const session = createClientSession({
 | client | required | The Ably Realtime client. The caller owns its lifecycle; `session.close()` does not close the client. The session's identity is read from this client's `auth.clientId` at publish time, stamped on the wire as the run-owner / input-owner id so other clients can attribute messages. A connection with no concrete clientId (anonymous, or a wildcard `*` token) publishes without one. | `Ably.Realtime` |
 | channelName | required | The channel to subscribe to and publish cancel signals on. The session owns this channel; do not also resolve it elsewhere with conflicting options. | String |
 | codec | required | The codec used to encode and decode events and messages. | `Codec<TInput, TOutput, TProjection, TMessage>` |
-| messages | optional | Initial messages to seed the conversation tree with. Forms a linear chain. | `TMessage[]` |
 | channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects via [`object`](#properties). Omit to attach with the default mode set. The session requests the union, so extra modes never drop the modes AI Transport relies on. See [LiveObjects State](/docs/ai-transport/features/liveobjects). | `Ably.ChannelMode[]` |
+| historyPageSize | optional | Wire-message limit fetched per channel-history round trip when paging older history through `view.loadOlder()`, shared by every view on the session. Independent of `loadOlder`'s reveal `limit`: it tunes fetch cost, not reveal granularity. Defaults to 100. | Number |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
 
 </Table>
@@ -134,7 +134,7 @@ await session.connect();
 
 ## Create an additional view <a id="create-view"/>
 
-<MethodSignature>{`createView(): View<TInput, TMessage>`}</MethodSignature>
+<MethodSignature>{`createView(): ClientView<TInput, TMessage>`}</MethodSignature>
 
 Create an additional view over the same conversation tree. Each view has independent branch selections and pagination state.
 
@@ -143,7 +143,7 @@ The caller owns the returned view's lifecycle: call its `close()` when it is no
 <Code>
 ```javascript
 const secondaryView = session.createView();
-secondaryView.selectSibling(messageId, 1);
+secondaryView.branchSelection(messageId).select(1);
 
 // the default view is unaffected
 session.view.branchSelection(messageId).index; // 0
@@ -152,7 +152,7 @@ session.view.branchSelection(messageId).index; // 0
 
 ### Returns <a id="create-view-returns"/>
 
-`View<TInput, TMessage>`. A new view with its own pagination window and branch selection state.
+`ClientView<TInput, TMessage>`. A new view with its own pagination window and branch selection state.
 
 ## Cancel a run <a id="cancel"/>
 
@@ -162,7 +162,7 @@ Publish a cancel signal for the specified Run. The agent receives the cancel thr
 
 <Code>
 ```javascript
-const activeRun = await session.view.send({
+const clientRun = await session.view.send({
   kind: 'user-message',
   message: {
     id: crypto.randomUUID(),
@@ -172,9 +172,9 @@ const activeRun = await session.view.send({
 });
 
 // later, cancel from the UI.
-// activeRun.cancel() works immediately, even before the runId
-// promise on activeRun has resolved.
-await activeRun.cancel();
+// clientRun.cancel() works immediately, even before the agent's
+// run-start has been observed (so clientRun.runId is still empty).
+await clientRun.cancel();
 
 // Or, when you already have a resolved runId (for example from a
 // RunInfo in view.runs()):
@@ -188,7 +188,7 @@ await activeRun.cancel();
 
 | Parameter | Required | Description | Type |
 | --- | --- | --- | --- |
-| runId | required | The Run to cancel. Typically obtained from `ActiveRun.runId` returned by a send. | String |
+| runId | required | The Run to cancel. Typically obtained from `ClientRun.runId` (after awaiting `clientRun.started`), or from a `RunInfo.runId` in `view.runs()`. | String |
 
 </Table>
 
@@ -275,7 +275,7 @@ session.view.on('update', () => {
   render(session.view.getMessages().map(({ message }) => message));
 });
 
-const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
+const clientRun = await session.view.send(UIMessageCodec.createUserMessage({
   id: crypto.randomUUID(),
   role: 'user',
   parts: [{ type: 'text', text: 'Plan a 3-day trip to Lisbon.' }],
@@ -285,12 +285,13 @@ const activeRun = await session.view.send(UIMessageCodec.createUserMessage({
 await fetch('/api/chat', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify(activeRun.toInvocation().toJSON()),
+  body: JSON.stringify(clientRun.toInvocation().toJSON()),
 });
 
-// The agent assigns the runId on the server, so activeRun.runId is a
-// Promise. Await it to read the id.
-const runId = await activeRun.runId;
+// The agent mints the runId on the server, so clientRun.runId is empty
+// until run-start is observed. Await `started`, then read it.
+await clientRun.started;
+const runId = clientRun.runId;
 
 await session.close();
 ably.close();

From 41345c7304fba1ca3204598d6dc7fd02d2b684a3 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:32:33 +0100
Subject: [PATCH 05/15] AI Transport docs: drop removed error code, unify error
 delivery

v0.4.0 removes ErrorCode.InputEventNotFound (104010): the input-event
watcher replaces the timed history-scan lookup, so there is no lookup
timeout to fail. Remove the 104010 row, and document non-fatal session
errors as delivered through session.on('error') on both the client and the
agent, replacing the removed AgentSessionOptions.onError option.

AIT-1090
---
 src/pages/docs/ai-transport/api/errors.mdx | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/errors.mdx b/src/pages/docs/ai-transport/api/errors.mdx
index a9b8c7ec58..8f13958b54 100644
--- a/src/pages/docs/ai-transport/api/errors.mdx
+++ b/src/pages/docs/ai-transport/api/errors.mdx
@@ -48,10 +48,9 @@ The `ErrorInfo` type is exported from `ably`. AI Transport surfaces it as the re
 | 104003 | RunLifecycleError        | 500         | A publish within a Run failed (lifecycle event, message, or codec event).                                                                                                                                                         | Check channel permissions and connection state. Surface the error to the calling HTTP handler so the client's pending send fails.                                 |
 | 104004 | SessionClosed            | 400         | An operation was attempted on a session that has already been closed.                                                                                                                                                             | Create a new session. Do not reuse a closed session.                                                                                                              |
 | 104005 | SessionSendFailed        | 500         | A send failed: either the core's channel publish failed, or the Vercel chat transport's agent-invocation POST failed (network error or non-2xx response).                                                                                                                                                   | Check the API endpoint URL, network connectivity, and authentication. Inspect the underlying error for details.                                                   |
-| 104006 | ChannelContinuityLost    | 500         | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events.                       | Surfaced via the session's `on('error')` and the agent session's `onError` option. End active Runs; subsequent operations can resume once the channel reattaches. |
+| 104006 | ChannelContinuityLost    | 500         | The Ably channel lost message continuity. The channel entered `FAILED`, `SUSPENDED`, or `DETACHED`, or re-attached with `resumed: false`. Active streams can no longer be guaranteed to receive all events.                       | Surfaced via the session's `on('error')` on both the client and the agent. End active Runs; subsequent operations can resume once the channel reattaches. |
 | 104007 | ChannelNotReady          | 400         | An operation was attempted but the channel is not in a usable state (not `ATTACHED` or `ATTACHING`).                                                                                                                              | Wait for the channel to attach before retrying, or inspect channel state and connection state for the underlying cause.                                           |
 | 104008 | StreamError              | 500         | An error occurred while piping a response stream to the channel. Either the source event stream threw (LLM provider rate limit, model error, network failure) or an underlying publish failed mid-stream.                         | Inspect `cause` for the provider error. End the Run with reason `'error'`. The error is also returned on `StreamResult.error` from `Run.pipe`.                    |
-| 104010 | InputEventNotFound       | 504         | The agent attached to the channel and waited for the input events the invocation points at (rewind + live wait) but `inputEventLookupTimeoutMs` lapsed without seeing them.                                                       | Surface the rejection from `Run.start()` as a non-2xx response so the client's pending send fails. The client retries with a fresh send.                          |
 
 ### Auth and channel errors <a id="platform"/>
 
@@ -87,7 +86,7 @@ session.on('error', (error) => {
 
 ## Example <a id="example"/>
 
-Handle session-level and run-level errors separately. The client subscribes to session errors. The agent uses the `onError` option on `AgentSessionOptions` for session-wide events and the run runtime's `onError` for per-Run failures.
+Handle session-level and run-level errors separately. Both the client and the agent subscribe to session errors with `session.on('error')`. The agent additionally uses the run runtime's `onError` for per-Run failures.
 
 <Code>
 ```javascript
@@ -102,17 +101,14 @@ session.on('error', (error) => {
 });
 
 // Agent side: handle session and run-level errors separately.
-const agentSession = createAgentSession({
-  client: ably,
-  channelName,
-  codec,
-  onError(error) {
-    console.error('Session error:', error);
-  },
-});
+const agentSession = createAgentSession({ client: ably, channelName, codec });
 
 await agentSession.connect();
 
+agentSession.on('error', (error) => {
+  console.error('Session error:', error);
+});
+
 const run = agentSession.createRun(invocation, {
   signal: req.signal,
   onError(error) {

From 7dd6e2ab64eb2a0cf17a4f155cc47513c18582ae Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:36:04 +0100
Subject: [PATCH 06/15] AI Transport docs: sweep the React core API reference
 for v0.4.0

- use-view.mdx / use-create-view.mdx: ViewHandle.loadOlder now resolves to
  the revealed page; branchSelection returns a BranchHandle whose select()
  replaces the removed selectSibling; send/regenerate/edit return ClientRun
  and take one new message per send; View -> ClientView; pagination counts
  codecMessages.
- providers.mdx: drop the removed ClientSessionOptions.messages seed prop;
  document channelModes and historyPageSize.

use-client-session.mdx is unchanged: its hook source did not change in
v0.4.0 and it already documents session.on('error').

AIT-1090
---
 .../ai-transport/api/react/core/providers.mdx |  3 +-
 .../api/react/core/use-create-view.mdx        | 21 ++++----
 .../ai-transport/api/react/core/use-view.mdx  | 53 ++++++++++---------
 3 files changed, 41 insertions(+), 36 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/react/core/providers.mdx b/src/pages/docs/ai-transport/api/react/core/providers.mdx
index 85b435b9c8..333312443f 100644
--- a/src/pages/docs/ai-transport/api/react/core/providers.mdx
+++ b/src/pages/docs/ai-transport/api/react/core/providers.mdx
@@ -50,7 +50,8 @@ The provider also renders an ably-js `<ChannelProvider>` for the session's chann
 | --- | --- | --- |
 | 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>` |
-| messages | Initial messages to seed the conversation tree with. | `TMessage[]` |
+| channelModes | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects. | `Ably.ChannelMode[]` |
+| historyPageSize | Wire-message limit fetched per channel-history round trip when paging older history, shared by every view on the session. Defaults to 100. | Number |
 | logger | Logger instance for diagnostic output. | `Logger` |
 | children | Descendant components that consume the session via hooks. | `ReactNode` |
 
diff --git a/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx b/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx
index 6efa1b1ebc..21ecb3ee91 100644
--- a/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx
+++ b/src/pages/docs/ai-transport/api/react/core/use-create-view.mdx
@@ -7,7 +7,7 @@ redirect_from:
   - /docs/ai-transport/api/react/use-create-view
 ---
 
-`useCreateView` creates a new [`View`](/docs/ai-transport/api/javascript/core/client-session) over the same conversation tree as the session's default view, then subscribes to it the same way [`useView`](/docs/ai-transport/api/react/core/use-view) does. Each created view has its own branch selections and pagination state. The view is closed automatically on unmount or when the session reference changes.
+`useCreateView` creates a new [`ClientView`](/docs/ai-transport/api/javascript/core/client-session#create-view) over the same conversation tree as the session's default view, then subscribes to it the same way [`useView`](/docs/ai-transport/api/react/core/use-view) does. Each created view has its own branch selections and pagination state. The view is closed automatically on unmount or when the session reference changes.
 
 Use this hook when you need two independent renderings of the same conversation, for example, a split-pane diff between two regenerate siblings, or a secondary panel that pages older history without affecting the main scroll position.
 
@@ -38,7 +38,7 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 | Parameter | Required | Description | Type |
 | --- | --- | --- | --- |
 | session | optional | A client session to create a view from. Defaults to the nearest provider. Pass `null` to defer creation. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
-| limit | optional | Maximum number of older Runs to reveal per page. When provided, auto-loads the first page on mount. | Number |
+| limit | optional | Number of older codecMessages to reveal per page. When provided, auto-loads the first page on mount. | Number |
 | skip | optional | When `true`, skip view creation and return an empty handle immediately. | Boolean |
 
 </Table>
@@ -52,18 +52,17 @@ Returns the same [`ViewHandle`](/docs/ai-transport/api/react/core/use-view#retur
 | Property | Description | Type |
 | --- | --- | --- |
 | messages | The visible messages along the selected branch, each paired with its `codecMessageId`. Read the domain object from each entry's `message` field. | `CodecMessage<TMessage>[]` |
-| hasOlder | Whether there are older Runs that can be revealed. | Boolean |
+| hasOlder | Whether there are older messages that can be revealed. | Boolean |
 | loading | Whether a page load is currently in progress. | Boolean |
 | loadError | Set when the most recent `loadOlder` call failed. | `Ably.ErrorInfo` or Undefined |
-| loadOlder | Reveal older Runs. | `() => Promise<void>` |
+| loadOlder | Reveal older messages, resolving to the revealed page (oldest-first); `[]` when nothing was revealed. | `() => Promise<CodecMessage<TMessage>[]>` |
 | runOf | Look up the `RunInfo` for the Run that owns a `codecMessageId`. | `(codecMessageId) => RunInfo \| undefined` |
 | run | Direct lookup by Run id. | `(runId) => RunInfo \| undefined` |
 | runs | Snapshot of the visible Runs along the selected branch, in chronological order. | `() => RunInfo[]` |
-| branchSelection | Resolve the `BranchSelection` bundle anchored at `codecMessageId`. | `(codecMessageId) => BranchSelection<TMessage>` |
-| selectSibling | Select a sibling at the branch point anchored at `codecMessageId`. | `(codecMessageId, index) => void` |
-| send | Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. | `(events, options?) => Promise<ActiveRun>` |
-| regenerate | Regenerate an assistant message, using this view's branch. | `(messageId, options?) => Promise<ActiveRun>` |
-| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ActiveRun>` |
+| branchSelection | Resolve the `BranchHandle` anchored at `codecMessageId`: the sibling state plus a `select(index)` verb. | `(codecMessageId) => BranchHandle<TMessage>` |
+| send | Send an input on the channel and fire a POST (at most one new message per send). Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. | `(events, options?) => Promise<ClientRun<TMessage>>` |
+| regenerate | Regenerate an assistant message, using this view's branch. | `(messageId, options?) => Promise<ClientRun<TMessage>>` |
+| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ClientRun<TMessage>>` |
 
 </Table>
 
@@ -89,14 +88,14 @@ function Compare({ messageId }: { messageId: string }) {
       <div>
         <BranchPicker
           selection={leftBranch}
-          onSelect={(i) => leftView.selectSibling(messageId, i)}
+          onSelect={(i) => leftBranch.select(i)}
         />
         <MessageList messages={leftView.messages} />
       </div>
       <div>
         <BranchPicker
           selection={rightBranch}
-          onSelect={(i) => rightView.selectSibling(messageId, i)}
+          onSelect={(i) => rightBranch.select(i)}
         />
         <MessageList messages={rightView.messages} />
       </div>
diff --git a/src/pages/docs/ai-transport/api/react/core/use-view.mdx b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
index 23ba8bf330..79bba446ce 100644
--- a/src/pages/docs/ai-transport/api/react/core/use-view.mdx
+++ b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
@@ -43,8 +43,8 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 | Parameter | Required | Description | Type |
 | --- | --- | --- | --- |
 | session | optional | A client session whose default view to subscribe to. Defaults to the nearest provider. | `ClientSession<TInput, TOutput, TProjection, TMessage>` |
-| view | optional | A specific view to subscribe to directly. Takes priority over `session`. | `View<TInput, TMessage>` |
-| limit | optional | Maximum number of older Runs to reveal per page. When provided, auto-loads the first page on mount. | Number |
+| view | optional | A specific view to subscribe to directly. Takes priority over `session`. | `ClientView<TInput, TMessage>` |
+| limit | optional | Number of older codecMessages to reveal per page (exactly `limit`, fewer only at the end of history). When provided, auto-loads the first page on mount. | Number |
 | skip | optional | When `true`, skip all subscriptions and return an empty handle immediately. | Boolean |
 
 </Table>
@@ -56,18 +56,17 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 | Property | Description | Type |
 | --- | --- | --- |
 | messages | The visible messages along the selected branch, each paired with its `codecMessageId`. Read the domain object from each entry's `message` field. | `CodecMessage<TMessage>[]` |
-| hasOlder | Whether there are older Runs that can be revealed via `loadOlder`. | Boolean |
+| hasOlder | Whether there are older messages that can be revealed via `loadOlder`. | Boolean |
 | loading | Whether a page load is currently in progress. | Boolean |
 | loadError | Set when the most recent `loadOlder` call failed. Cleared automatically on the next successful load. | `Ably.ErrorInfo` or Undefined |
-| loadOlder | Reveal older Runs. No-op if already loading. | `() => Promise<void>` |
+| loadOlder | Reveal older messages, resolving to the revealed page (oldest-first). Returns `[]` when nothing was revealed: already loading, no view resolved, history exhausted, or the load failed. | `() => Promise<CodecMessage<TMessage>[]>` |
 | runOf | Look up the `RunInfo` for the Run that owns the given `codecMessageId`. | <Table id='RunInfo'/> |
 | run | Direct lookup by Run id. | <Table id='RunInfo'/> |
 | runs | Snapshot of the visible Runs along the selected branch, in chronological order. Returns `[]` when the view isn't resolved. | `() => RunInfo[]` |
-| branchSelection | Resolve the `BranchSelection` bundle anchored at `codecMessageId`. Always returns a safe object. | <Table id='BranchSelection'/> |
-| selectSibling | Select a sibling at the branch point anchored at `codecMessageId`. | `(codecMessageId, index) => void` |
-| send | Send one or more `TInput`s on the channel and fire a POST. Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. Takes optional <Table id='SendOptions'/>. | `(events, options?) => Promise<ActiveRun>` |
-| regenerate | Regenerate an assistant message using this view's branch for history. | `(messageId, options?) => Promise<ActiveRun>` |
-| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ActiveRun>` |
+| branchSelection | Resolve the `BranchHandle` anchored at `codecMessageId`: the sibling state plus a `select(index)` verb to navigate it. Always returns a safe handle. | <Table id='BranchHandle'/> |
+| send | Send an input on the channel and fire a POST. At most one new message per send; the array form carries only wire-only inputs (tool results, approvals). Wrap a domain message via `codec.createUserMessage` (or build the `{ kind: 'user-message', message }` literal) to send a fresh user message. Takes optional <Table id='SendOptions'/>. | `(events, options?) => Promise<ClientRun<TMessage>>` |
+| regenerate | Regenerate an assistant message using this view's branch for history. | `(messageId, options?) => Promise<ClientRun<TMessage>>` |
+| edit | Edit a user message, forking from this view's branch. | `(messageId, inputs, options?) => Promise<ClientRun<TMessage>>` |
 
 </Table>
 
@@ -83,7 +82,7 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 
 </Table>
 
-<Table id='BranchSelection' hidden>
+<Table id='BranchHandle' hidden>
 
 | Property | Description | Type |
 | --- | --- | --- |
@@ -91,6 +90,7 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 | siblings | The selected sibling and any alternatives in tree-order. Always contains the currently rendered message for known ids. | `TMessage[]` |
 | index | Index of the selected sibling within `siblings`. `0` when there is no real branching. | Number |
 | selected | Convenience reference to `siblings[index]`. `undefined` only when `siblings` is empty. | `TMessage` or Undefined |
+| select | Select a sibling at this branch point. `index` is clamped to `[0, siblings.length - 1]`; a silent no-op when the anchor is not a branch anchor. | `(index: number) => void` |
 
 </Table>
 
@@ -105,11 +105,11 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 
 </Table>
 
-## Reveal older Runs <a id="load-older"/>
+## Reveal older messages <a id="load-older"/>
 
-<MethodSignature>{`loadOlder(): Promise<void>`}</MethodSignature>
+<MethodSignature>{`loadOlder(): Promise<CodecMessage<TMessage>[]>`}</MethodSignature>
 
-Load older messages into the view by revealing more Runs. When `limit` is set on the hook, the first page auto-loads on mount. Call `loadOlder` again to reveal more. The call is gated so concurrent invocations collapse to one in-flight request.
+Reveal older messages into the view, resolving to the revealed page (oldest-first). When `limit` is set on the hook, the first page auto-loads on mount. Call `loadOlder` again to reveal more. The call is gated so concurrent invocations collapse to one in-flight request; it returns `[]` when nothing was revealed (already loading, no view resolved, history exhausted, or the load failed).
 
 On failure, `loadError` is set. On the next successful load, `loadError` is cleared automatically.
 
@@ -127,33 +127,39 @@ Direct lookup by Run id. Symmetric with [`runOf`](#run-of) for callers that alre
 
 ## Resolve a branch selection <a id="branch-selection"/>
 
-<MethodSignature>{`branchSelection(codecMessageId: string): BranchSelection<TMessage>`}</MethodSignature>
+<MethodSignature>{`branchSelection(codecMessageId: string): BranchHandle<TMessage>`}</MethodSignature>
 
-Resolve the `BranchSelection` bundle anchored at `codecMessageId`. Always returns a safe object: for branch anchors with N siblings, `siblings` carries every sibling Run's view of the anchor slot; for non-anchor messages, `siblings` is `[thisMessage]` and `hasSiblings` is `false`.
+Resolve the `BranchHandle` anchored at `codecMessageId`: the sibling state plus a `select(index)` verb to navigate it. Always returns a safe handle: for branch anchors with N siblings, `siblings` carries every sibling Run's view of the anchor slot; for non-anchor messages, `siblings` is `[thisMessage]` and `hasSiblings` is `false`.
 
 ## Select a sibling <a id="select-sibling"/>
 
-<MethodSignature>{`selectSibling(codecMessageId: string, index: number): void`}</MethodSignature>
+Switch the visible sibling through the [`BranchHandle`](#branch-selection) the `branchSelection` call returns, rather than a separate hook method:
 
-Select a sibling at the branch point anchored at `codecMessageId`. `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when the message is not a branch anchor. Emits `'update'` on the underlying view when the visible output changes.
+<Code>
+```javascript
+view.branchSelection(codecMessageId).select(1);
+```
+</Code>
+
+`index` is clamped to `[0, siblings.length - 1]`. The call is a silent no-op when the message is not a branch anchor, and emits `'update'` on the underlying view when the visible output changes.
 
 ## Send inputs <a id="send"/>
 
-<MethodSignature>{`send(events: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+<MethodSignature>{`send(events: TInput | TInput[], options?: SendOptions): Promise<ClientRun<TMessage>>`}</MethodSignature>
 
-Send one or more `TInput`s on the channel and fire a POST. Each `TInput` carries its own routing metadata (`parent`, `target`, `codecMessageId`).
+Send an input on the channel and fire a POST. Each `TInput` carries its own routing metadata (`parent`, `target`, `codecMessageId`).
 
-To send a fresh user message, build a `UserMessage` input. Use the codec factory (`codec.createUserMessage(message)`) or build the literal directly: `{ kind: 'user-message', message }`. A send containing at least one `UserMessage` mints a fresh Run. A send containing only tool-resolution inputs (`tool-result`, `tool-result-error`, `tool-approval-response`) is a continuation; pair it with `options.runId` to extend a suspended Run.
+To send a fresh user message, build a `UserMessage` input. Use the codec factory (`codec.createUserMessage(message)`) or build the literal directly: `{ kind: 'user-message', message }`. A send introduces at most one new message: exactly one `UserMessage` for a fresh send (which mints a new Run), or none for a continuation. The array form exists only to carry the wire-only inputs that resolve a single assistant turn (`tool-result`, `tool-result-error`, `tool-approval-response`); pair it with `options.runId` to extend a suspended Run. Passing more than one new message rejects with `InvalidArgument`.
 
 ## Regenerate an assistant message <a id="regenerate"/>
 
-<MethodSignature>{`regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+<MethodSignature>{`regenerate(messageId: string, options?: SendOptions): Promise<ClientRun<TMessage>>`}</MethodSignature>
 
 Regenerate an assistant message. Creates a new Run that targets the message and threads under its parent user message. Both ids are computed automatically from this view's branch.
 
 ## Edit a user message <a id="edit"/>
 
-<MethodSignature>{`edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>`}</MethodSignature>
+<MethodSignature>{`edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ClientRun<TMessage>>`}</MethodSignature>
 
 Edit a user message. Creates a new Run that forks the target message with the replacement inputs. `forkOf`, `parent`, and history are computed automatically from this view's branch.
 
@@ -171,7 +177,6 @@ function Conversation() {
     hasOlder,
     loadOlder,
     branchSelection,
-    selectSibling,
     send,
     regenerate,
   } = useView({ limit: 30 });
@@ -187,7 +192,7 @@ function Conversation() {
             {branch.hasSiblings && (
               <BranchControls
                 selection={branch}
-                onSelect={(i) => selectSibling(codecMessageId, i)}
+                onSelect={(i) => branch.select(i)}
               />
             )}
             {message.role === 'assistant' && (

From 906bcb2f3f2a7531dbc70cf94eea79be05ac8274 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:38:47 +0100
Subject: [PATCH 07/15] AI Transport docs: sweep the Vercel API reference for
 v0.4.0

- chat-transport.mdx: drop the removed messages seed from the client
  options and the removed onError / inputEventLookupTimeoutMs /
  inputEventBufferLimit / rewindWindow from the agent options; add
  historyPageSize and channelModes; point session errors at on('error').
- chat-transport-provider.mdx: drop the removed messages seed prop; add
  historyPageSize.
- use-message-sync.mdx: document the new messages seed option that
  reconciles a useChat seed with the live channel.
- run-outcome.mdx: rebuild the model context by draining run.view instead
  of the removed loadConversation; await the now-async session.close().

AIT-1090
---
 .../api/javascript/vercel/chat-transport.mdx    | 11 ++++++-----
 .../api/javascript/vercel/run-outcome.mdx       | 17 +++++++++++------
 .../react/vercel/chat-transport-provider.mdx    |  2 +-
 .../api/react/vercel/use-message-sync.mdx       | 10 ++++++++++
 4 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
index e92ef56454..127ec63048 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/chat-transport.mdx
@@ -57,7 +57,8 @@ const session = createClientSession({
 | --- | --- | --- | --- |
 | client | required | The Ably Realtime client. The caller owns its lifecycle. The session's identity is read from this client's `auth.clientId` at publish time and stamped on everything it publishes. | `Ably.Realtime` |
 | channelName | required | The channel to subscribe to and publish cancel signals on. | String |
-| messages | optional | Initial messages to seed the conversation tree with. | `UIMessage[]` |
+| channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects. | `Ably.ChannelMode[]` |
+| historyPageSize | optional | Wire-message limit fetched per channel-history round trip when paging older history. Defaults to 100. | Number |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
 
 </Table>
@@ -97,14 +98,14 @@ const session = createAgentSession({
 | --- | --- | --- | --- |
 | client | required | The Ably Realtime client. The caller owns its lifecycle. | `Ably.Realtime` |
 | channelName | required | The channel to publish to. | String |
+| channelModes | optional | Extra channel modes to request on top of the modes AI Transport always needs. Pass `OBJECT_MODES` to use Ably LiveObjects. | `Ably.ChannelMode[]` |
+| historyPageSize | optional | Wire-message limit fetched per channel-history round trip, used by every `run.view` pagination on this session. Defaults to 100. | Number |
 | logger | optional | Logger instance for diagnostic output. | `Logger` |
-| onError | optional | Called with non-fatal session-level errors not scoped to any run. | `(error: ErrorInfo) => void` |
-| inputEventLookupTimeoutMs | optional | How long `Run.start()` waits for the input event to arrive. Defaults to 30000. | Number |
-| inputEventBufferLimit | optional | Max distinct input events that may be buffered while waiting for `Run.start()` to register a lookup listener. Defaults to 200. | Number |
-| rewindWindow | optional | Channel rewind applied when the agent attaches. Passed verbatim to Ably's `params.rewind`. Defaults to `"2m"`. | String |
 
 </Table>
 
+Subscribe to non-fatal session-level errors with [`session.on('error')`](/docs/ai-transport/api/javascript/core/agent-session#on) rather than a constructor option.
+
 ### Returns <a id="create-agent-session-returns"/>
 
 `AgentSession<VercelOutput, VercelProjection, UIMessage>`. An agent session whose codec is pre-bound to `UIMessageCodec`.
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
index 85d2f4ce88..8284050a37 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
@@ -65,9 +65,9 @@ The rejection guard matters: Vercel AI SDK v6 rejects `streamText().finishReason
 
 `Promise<VercelRunOutcome>`. A `VercelRunOutcome` is an object discriminated on `reason` with three arms:
 
-- `{ reason: 'suspend' }` — the LLM requested tools the SDK did not auto-execute; call [`Run.suspend`](/docs/ai-transport/api/javascript/core/agent-session#run-suspend) so a continuation Invocation can resume the Run.
-- `{ reason: 'complete' | 'cancelled' }` — the run terminated normally; pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
-- `{ reason: 'error', error }` — the run failed; `error` is an `Ably.ErrorInfo`. Pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
+- `{ reason: 'suspend' }`: the LLM requested tools the SDK did not auto-execute. Call [`Run.suspend`](/docs/ai-transport/api/javascript/core/agent-session#run-suspend) so a continuation Invocation can resume the Run.
+- `{ reason: 'complete' | 'cancelled' }`: the run terminated normally. Pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
+- `{ reason: 'error', error }`: the run failed. `error` is an `Ably.ErrorInfo`. Pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
 
 `error` is present only on the `'error'` arm. The non-`'suspend'` arms are assignable to [`RunEndParams`](/docs/ai-transport/api/javascript/core/agent-session#run-end-params), so after a `'suspend'` guard the whole object passes straight to `Run.end(outcome)`.
 
@@ -107,11 +107,16 @@ export async function POST(req: Request) {
 
   try {
     await run.start();
-    await run.loadConversation();
+
+    // Rebuild the prior conversation from run.view to feed the model.
+    while (run.view.hasOlder()) {
+      await run.view.loadOlder();
+    }
+    const conversation = run.view.getMessages().map(({ message }) => message);
 
     const result = streamText({
       model: openai('gpt-4'),
-      messages: run.messages,
+      messages: conversation,
       tools: myTools,
     });
 
@@ -124,7 +129,7 @@ export async function POST(req: Request) {
       await run.end(outcome);
     }
   } finally {
-    session.close();
+    await session.close();
   }
 
   return Response.json({ invocationId: run.invocationId });
diff --git a/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
index 4d83219edf..e4465dcd8a 100644
--- a/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
+++ b/src/pages/docs/ai-transport/api/react/vercel/chat-transport-provider.mdx
@@ -46,7 +46,7 @@ function App() {
 | credentials | Fetch credentials mode for the invocation POST. Set to `'include'` for cookie-based cross-origin auth. | `RequestCredentials` |
 | fetch | Custom fetch implementation for the invocation POST. Defaults to `globalThis.fetch`. | `typeof globalThis.fetch` |
 | chatOptions | Hooks for customising chat request construction (for example `prepareSendMessagesRequest`). Must be stable across renders; wrap in `useMemo` or define outside the component. A new object reference recreates the `ChatTransport`. | <Table id='ChatTransportOptions'/> |
-| messages | Initial messages to seed the conversation tree with. | `UIMessage[]` |
+| historyPageSize | Wire-message limit fetched per channel-history round trip when paging older history. Defaults to 100. | Number |
 | logger | Logger instance for diagnostic output. | `Logger` |
 | children | Descendant components that consume the chat transport via [`useChatTransport`](/docs/ai-transport/api/react/vercel/use-chat-transport). | `ReactNode` |
 
diff --git a/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx b/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx
index 487f204005..39032e5323 100644
--- a/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx
+++ b/src/pages/docs/ai-transport/api/react/vercel/use-message-sync.mdx
@@ -36,6 +36,7 @@ This hook must be used within a `ChatTransportProvider` (exported from `@ably/ai
 | Parameter | Required | Description | Type |
 | --- | --- | --- | --- |
 | setMessages | required | The `setMessages` updater function from `useChat()`. Called with an updater that returns the next overlay. | `(updater: (prev: UIMessage[]) => UIMessage[]) => void` |
+| messages | optional | The application's seeded conversation, typically `useChat()`'s `messages` where persisted history was supplied via `useChat({ messages })`. When non-empty, the hook reconciles it with the live channel: it takes the newest entry's `id` as the seam, pages the channel back to it, and composes stored history with the live tail with no duplicate. Omit it, or pass `[]`, for the full live channel history. See [database hydration](/docs/ai-transport/features/database-hydration). | `UIMessage[]` |
 | channelName | optional | Channel name of the `ChatTransportProvider` to observe. Omit to use the nearest provider. | String |
 | skip | optional | When `true`, skip all subscriptions. | Boolean |
 
@@ -60,6 +61,15 @@ Use `useMessageSync` whenever you mount a `ChatTransportProvider` and render mes
 
 If you render messages directly from [`useView`](/docs/ai-transport/api/react/core/use-view) instead of from `useChat`, you do not need `useMessageSync`; `useView` already reflects the view state.
 
+To seed the conversation from your own database, pass the loaded history as `messages`, both to `useChat` and to `useMessageSync`. The hook reconciles the seed with the live channel at the seam, so a reloaded conversation shows its stored history plus the live tail exactly once. See [database hydration](/docs/ai-transport/features/database-hydration).
+
+<Code>
+```javascript
+const { messages, setMessages } = useChat({ transport: chatTransport, messages: seed });
+useMessageSync({ messages: seed, setMessages });
+```
+</Code>
+
 ## Example <a id="example"/>
 
 A complete Vercel-React chat with sync wired in. A second browser tab pointing at the same `channelName` sees every message as soon as it arrives on the channel.

From 54dea48d7c7f71113be7c1acf2fdc9e915b14806 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:42:12 +0100
Subject: [PATCH 08/15] AI Transport docs: drain run.view in agent-route
 feature examples

v0.4.0 removes Run.loadConversation; the agent rebuilds model context by
draining its leaf-pinned run.view. Replace the loadConversation call inline
across the agent-route examples (concurrent-turns, chain-of-thought,
agent-presence, token-streaming, push-notifications, branching), feeding the
drained run.view.getMessages() to the model.

Also on these pages: ActiveRun -> ClientRun with synchronous runId awaited
via started (concurrent-turns), and branch navigation via the
branchSelection handle's select() rather than the removed selectSibling
(branching).

AIT-1090
---
 .../ai-transport/features/agent-presence.mdx  |  9 ++++--
 .../docs/ai-transport/features/branching.mdx  | 30 +++++++++++--------
 .../features/chain-of-thought.mdx             | 11 +++++--
 .../features/concurrent-turns.mdx             | 18 +++++++----
 .../features/push-notifications.mdx           | 11 +++++--
 .../ai-transport/features/token-streaming.mdx | 11 +++++--
 6 files changed, 61 insertions(+), 29 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/agent-presence.mdx b/src/pages/docs/ai-transport/features/agent-presence.mdx
index a6ecb79b5a..b9878aefad 100644
--- a/src/pages/docs/ai-transport/features/agent-presence.mdx
+++ b/src/pages/docs/ai-transport/features/agent-presence.mdx
@@ -33,11 +33,16 @@ app.post('/api/chat', async (req, res) => {
   await session.presence.enter({ status: 'thinking' });
 
   await run.start();
-  await run.loadConversation();
+
+  // Drain run.view for the prior conversation to feed the model.
+  while (run.view.hasOlder()) {
+    await run.view.loadOlder();
+  }
+  const conversation = run.view.getMessages().map(({ message }) => message);
 
   const result = streamText({
     model: openai('gpt-4o'),
-    messages: run.messages,
+    messages: conversation,
     abortSignal: run.abortSignal,
   });
 
diff --git a/src/pages/docs/ai-transport/features/branching.mdx b/src/pages/docs/ai-transport/features/branching.mdx
index 52087c7051..0701fae4ab 100644
--- a/src/pages/docs/ai-transport/features/branching.mdx
+++ b/src/pages/docs/ai-transport/features/branching.mdx
@@ -25,7 +25,7 @@ Every node on the channel carries `parent` and (optionally) `fork-of` or `msg-re
 
 Branches are message-anchored: the branch decision lives on a `codecMessageId`, not on a `runId`. UIs render navigation arrows next to the bubble: the user's prompt for edit forks, the assistant slot for regenerate groups.
 
-The View resolves the branch state on demand. Call `view.branchSelection(codecMessageId)` for any message and get back `{ hasSiblings, siblings, index, selected }`. Call `view.selectSibling(codecMessageId, index)` to switch.
+The View resolves the branch state on demand. Call `view.branchSelection(codecMessageId)` for any message and get back a handle: `{ hasSiblings, siblings, index, selected, select }`. Call the handle's `select(index)` to switch.
 
 ## Regenerate <a id="regenerate"/>
 
@@ -78,14 +78,15 @@ When a message has siblings, render arrows that switch between them. `branchSele
 <Code>
 ```javascript
 function BranchNav({ codecMessageId, view }) {
-  const { hasSiblings, siblings, index } = view.branchSelection(codecMessageId);
-  if (!hasSiblings) return null;
+  const branch = view.branchSelection(codecMessageId);
+  if (!branch.hasSiblings) return null;
+  const { siblings, index } = branch;
 
   return (
     <div>
-      <button onClick={() => view.selectSibling(codecMessageId, index - 1)} disabled={index === 0}>←</button>
+      <button onClick={() => branch.select(index - 1)} disabled={index === 0}>←</button>
       <span>{index + 1} of {siblings.length}</span>
-      <button onClick={() => view.selectSibling(codecMessageId, index + 1)} disabled={index === siblings.length - 1}>→</button>
+      <button onClick={() => branch.select(index + 1)} disabled={index === siblings.length - 1}>→</button>
     </div>
   );
 }
@@ -113,7 +114,7 @@ This is the pattern for comparison UIs where the user wants to see two regenerat
 
 ## Agent-side handling <a id="agent-side"/>
 
-The agent doesn't usually need bespoke branching logic. The Invocation arrives, `createRun` returns a Run with the right identity, and `loadConversation` walks the ancestor chain along the selected branch automatically:
+The agent doesn't usually need bespoke branching logic. The Invocation arrives, `createRun` returns a Run pinned to the right branch, and draining `run.view` walks the ancestor chain along the selected branch automatically:
 
 <Code>
 ```javascript
@@ -122,11 +123,16 @@ const run = session.createRun(invocation, { signal: req.signal });
 
 try {
   await run.start();
-  await run.loadConversation(); // walks ancestor chain along this branch
+
+  // Drain run.view along this branch back to the root.
+  while (run.view.hasOlder()) {
+    await run.view.loadOlder();
+  }
+  const conversation = run.view.getMessages().map(({ message }) => message);
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages: run.messages,
+    messages: conversation,
     abortSignal: run.abortSignal,
   });
 
@@ -136,12 +142,12 @@ try {
   await run.end({ reason: 'error' });
   throw err;
 } finally {
-  session.close();
+  await session.close();
 }
 ```
 </Code>
 
-`run.messages` after `loadConversation()` returns the complete branch (ancestor turns and the current user input) in order. Pass it straight to the LLM.
+`run.view` is pinned to this Run's branch, so draining it yields the complete branch (ancestor turns and the current user input) in order. Pass it straight to the LLM.
 
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
@@ -149,14 +155,14 @@ try {
 - Branch selection is per-view. Two devices on the same session can see different branches simultaneously; the tree is shared, the selection is per-view.
 - Deeply branched trees can have many siblings. A user can navigate forever; cap or hide branch navigation in your UI if your app has a preferred branch.
 - A regenerate against an edited prompt still works. The new branch attaches at the same anchor regardless of what siblings exist.
-- The visible branch recomputes when `selectSibling` is called. Avoid heavy work in the render path; updates are frequent during streaming.
+- The visible branch recomputes when a sibling is selected through the branch handle's `select`. Avoid heavy work in the render path; updates are frequent during streaming.
 - An optimistic edit is folded with the published edit. See [optimistic updates](/docs/ai-transport/features/optimistic-updates) for how the SDK reconciles the local insertion with the wire confirmation.
 
 ## FAQ <a id="faq"/>
 
 ### Does edit overwrite the original message?
 
-No. The original stays in the tree. A new sibling branch is created with the edited content. Users navigate between branches with `view.selectSibling()`.
+No. The original stays in the tree. A new sibling branch is created with the edited content. Users navigate between branches with the `view.branchSelection(codecMessageId)` handle's `select()`.
 
 ### How is regenerate different from sending a new prompt?
 
diff --git a/src/pages/docs/ai-transport/features/chain-of-thought.mdx b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
index d41e3a8d7c..a72c8620c4 100644
--- a/src/pages/docs/ai-transport/features/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
@@ -26,17 +26,22 @@ app.post('/api/chat', async (req, res) => {
   const run = session.createRun(invocation, { signal: req.signal });
 
   await run.start();
-  await run.loadConversation();
+
+  // Drain run.view for the prior conversation to feed the model.
+  while (run.view.hasOlder()) {
+    await run.view.loadOlder();
+  }
+  const conversation = run.view.getMessages().map(({ message }) => message);
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages: run.messages,
+    messages: conversation,
     abortSignal: run.abortSignal,
   });
 
   const { reason } = await run.pipe(result.toUIMessageStream());
   await run.end({ reason });
-  session.close();
+  await session.close();
   res.json({ ok: true });
 });
 ```
diff --git a/src/pages/docs/ai-transport/features/concurrent-turns.mdx b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
index a618447eda..21814ffb88 100644
--- a/src/pages/docs/ai-transport/features/concurrent-turns.mdx
+++ b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
@@ -45,17 +45,22 @@ app.post('/api/chat', async (req, res) => {
   const run = session.createRun(invocation, { signal: req.signal });
 
   await run.start();
-  await run.loadConversation();
+
+  // Drain run.view for the prior conversation to feed the model.
+  while (run.view.hasOlder()) {
+    await run.view.loadOlder();
+  }
+  const conversation = run.view.getMessages().map(({ message }) => message);
 
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
-    messages: run.messages,
+    messages: conversation,
     abortSignal: run.abortSignal,
   });
 
   const { reason } = await run.pipe(result.toUIMessageStream());
   await run.end({ reason });
-  session.close();
+  await session.close();
   res.json({ ok: true });
 });
 ```
@@ -105,7 +110,7 @@ See [cancellation](/docs/ai-transport/features/cancellation) for the full cancel
 
 ## Wait for runs to complete <a id="waiting-for-runs"/>
 
-Each `ActiveRun` exposes `runId: Promise<string>` (resolves with the agent-minted id once `ai-run-start` is observed). To wait for a Run to terminate, await the id and then subscribe to the session tree's `run` events:
+Each `ClientRun` exposes a synchronous `runId` (empty until `ai-run-start` is observed) and a `started` promise that resolves once it is. To wait for a Run to terminate, await `started`, read `runId`, then subscribe to the session tree's `run` events:
 
 <Code>
 ```javascript
@@ -125,7 +130,8 @@ const run1 = await view.send(UIMessageCodec.createUserMessage({
   role: 'user',
   parts: [{ type: 'text', text: 'Hello' }],
 }));
-const run1Id = await run1.runId;
+await run1.started;
+const run1Id = run1.runId;
 await whenRunEnds(session, run1Id);
 ```
 </Code>
@@ -215,7 +221,7 @@ There is no hard limit on the channel side. Practical limits come from your appl
 
 ### Does the client need to track run IDs? <a id="faq-track-ids"/>
 
-The session tracks Run identity internally. Hold onto the `ActiveRun` returned by `view.send()` only if you need to cancel it specifically or wait for it specifically.
+The session tracks Run identity internally. Hold onto the `ClientRun` returned by `view.send()` only if you need to cancel it specifically or wait for it specifically.
 
 ### How do I tell which run a message belongs to? <a id="faq-message-turn"/>
 
diff --git a/src/pages/docs/ai-transport/features/push-notifications.mdx b/src/pages/docs/ai-transport/features/push-notifications.mdx
index 221e3dbd54..445c365ce7 100644
--- a/src/pages/docs/ai-transport/features/push-notifications.mdx
+++ b/src/pages/docs/ai-transport/features/push-notifications.mdx
@@ -43,17 +43,22 @@ app.post('/api/chat', async (req, res) => {
   const run = session.createRun(invocation, { signal: req.signal })
 
   await run.start()
-  await run.loadConversation()
+
+  // Drain run.view for the prior conversation to feed the model.
+  while (run.view.hasOlder()) {
+    await run.view.loadOlder()
+  }
+  const conversation = run.view.getMessages().map(({ message }) => message)
 
   const result = streamText({
     model: openai('gpt-4o'),
-    messages: run.messages,
+    messages: conversation,
     abortSignal: run.abortSignal,
   })
 
   const { reason } = await run.pipe(result.toUIMessageStream())
   await run.end({ reason })
-  session.close()
+  await session.close()
 
   if (reason === 'complete') {
     // Publish a push-eligible event on a notification channel
diff --git a/src/pages/docs/ai-transport/features/token-streaming.mdx b/src/pages/docs/ai-transport/features/token-streaming.mdx
index b5c0e3dabb..efd9c86753 100644
--- a/src/pages/docs/ai-transport/features/token-streaming.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming.mdx
@@ -84,17 +84,22 @@ await session.connect();
 const run = session.createRun(invocation, { signal: req.signal });
 
 await run.start();
-await run.loadConversation();
+
+// Drain run.view for the prior conversation to feed the model.
+while (run.view.hasOlder()) {
+  await run.view.loadOlder();
+}
+const conversation = run.view.getMessages().map(({ message }) => message);
 
 const result = streamText({
   model: anthropic('claude-sonnet-4-20250514'),
-  messages: run.messages,
+  messages: conversation,
   abortSignal: run.abortSignal,
 });
 
 const { reason } = await run.pipe(result.toUIMessageStream());
 await run.end({ reason });
-session.close();
+await session.close();
 ```
 </Code>
 

From f7dcb7704ea09559e39a563f77409ba1f56a0070 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:45:31 +0100
Subject: [PATCH 09/15] AI Transport docs: align remaining feature pages with
 v0.4.0

- history.mdx: loadOlder now resolves to the revealed page (drop the
  Promise<void> claim and the FAQ that defended it); note historyPageSize;
  cross-link database hydration for longer-than-retention storage.
- multi-device.mdx: ActiveRun -> ClientRun (runId populated after started);
  link database hydration.
- interruption.mdx: ActiveRun -> ClientRun.

reconnection-and-recovery, optimistic-updates, and human-in-the-loop
already match v0.4.0 (they use session.on('error') and wire-only
tool-approval-response inputs), so they are unchanged.

AIT-1090
---
 src/pages/docs/ai-transport/features/history.mdx      | 9 +++++----
 src/pages/docs/ai-transport/features/interruption.mdx | 4 ++--
 src/pages/docs/ai-transport/features/multi-device.mdx | 3 ++-
 3 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/history.mdx b/src/pages/docs/ai-transport/features/history.mdx
index 88abdb0d7e..27f3ddae8a 100644
--- a/src/pages/docs/ai-transport/features/history.mdx
+++ b/src/pages/docs/ai-transport/features/history.mdx
@@ -21,7 +21,7 @@ const { messages, hasOlder, loadOlder } = useView({ limit: 30 });
 
 `useView` loads history using `view.loadOlder()` with the `untilAttach` parameter. `untilAttach` keeps history and the live subscription gapless: every message between the historical window and the latest live message is accounted for.
 
-`loadOlder()` returns `Promise<void>`. It expands the view window internally instead of returning a page; the view's `messages` array updates with the older messages.
+`loadOlder()` expands the view window and resolves to the page it revealed (the older messages, oldest-first). The view's `messages` array also updates with those messages, so you can either read the return value or re-render from `messages`. The fetch size per channel round trip is set by `historyPageSize` on the session options (default 100), independent of the `limit` you reveal per call.
 
 <Code>
 ```javascript
@@ -73,11 +73,11 @@ Not for AI Transport's own behaviour. The channel is the source of truth within
 
 ### How do I retain history longer than the channel keeps it? <a id="faq-retention"/>
 
-Persist completed turns to your own store as they end. AI Transport supports hydrating a session from an external store; the channel handles live and in-progress activity. See [sessions](/docs/ai-transport/concepts/sessions#persistence).
+Persist completed runs to your own store as they end, then reconcile that stored history with the live channel on reload. The channel handles live and in-progress activity. See [database hydration](/docs/ai-transport/features/database-hydration).
 
-### Why does `loadOlder()` return `Promise<void>` instead of the messages? <a id="faq-loadolder-shape"/>
+### What does `loadOlder()` return? <a id="faq-loadolder-shape"/>
 
-The view expands its internal window and emits an update. Components subscribed to `messages` re-render with the older messages. This keeps the view as the single source of truth.
+It resolves to the page of older messages it revealed, oldest-first, and `[]` when nothing was revealed (history exhausted or a load already in flight). The view's `messages` array updates in step, so you can drive a UI from either the return value or the `messages` re-render.
 
 ### Does history include cancelled turns? <a id="faq-cancelled"/>
 
@@ -92,3 +92,4 @@ Yes. Cancelled messages keep their partial content with a status of `cancelled`.
 - [Token streaming](/docs/ai-transport/features/token-streaming): how streamed responses are persisted and replayed from history.
 - [Reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery): how history loading fits into reconnection.
 - [Conversation branching](/docs/ai-transport/features/branching): how branches are created and navigated.
+- [Database hydration](/docs/ai-transport/features/database-hydration): retain conversations beyond channel retention by reconciling a stored seed with the live channel.
diff --git a/src/pages/docs/ai-transport/features/interruption.mdx b/src/pages/docs/ai-transport/features/interruption.mdx
index 99b8b81bb2..2594beb68c 100644
--- a/src/pages/docs/ai-transport/features/interruption.mdx
+++ b/src/pages/docs/ai-transport/features/interruption.mdx
@@ -67,7 +67,7 @@ function Chat() {
 
 ## Implement send-alongside <a id="send-alongside"/>
 
-Send a new message without cancelling. Both Runs stream concurrently; each `ActiveRun` carries its own `runId` and `cancel()`, and both Runs' outputs land on the same channel where they fold into the conversation tree by `runId`:
+Send a new message without cancelling. Both Runs stream concurrently; each `ClientRun` carries its own `runId` and `cancel()`, and both Runs' outputs land on the same channel where they fold into the conversation tree by `runId`:
 
 <Code>
 ```javascript
@@ -79,7 +79,7 @@ const followUp = await session.view.send(UIMessageCodec.createUserMessage({
 ```
 </Code>
 
-Cancel them independently with `session.cancel(specificRunId)` or `activeRun.cancel()`.
+Cancel them independently with `session.cancel(specificRunId)` or `clientRun.cancel()`.
 
 ## Drive the Stop / Send toggle <a id="stop-send-toggle"/>
 
diff --git a/src/pages/docs/ai-transport/features/multi-device.mdx b/src/pages/docs/ai-transport/features/multi-device.mdx
index 2d93044ede..42a63e7105 100644
--- a/src/pages/docs/ai-transport/features/multi-device.mdx
+++ b/src/pages/docs/ai-transport/features/multi-device.mdx
@@ -40,7 +40,7 @@ The client session separates Runs initiated by the current client from those by
 
 | Type | Origin | Handle |
 | --- | --- | --- |
-| Own Run | This client sent the HTTP POST that created the Run. | An `ActiveRun` returned from `view.send`, with `runId`, `inputCodecMessageId`, `cancel()`, and `toInvocation()`. |
+| Own Run | This client sent the HTTP POST that created the Run. | A `ClientRun` returned from `view.send`, with `runId` (populated after `started`), `inputCodecMessageId`, `cancel()`, and `toInvocation()`. |
 | Observer Run | Another client or agent created the Run. | Lifecycle events and folded outputs through the tree; no per-client handle. |
 
 Both types appear in the conversation tree and the UI. Folded outputs flow through the tree the same way regardless of origin; `RunInfo.clientId` on the view tells you which client started any given Run.
@@ -138,3 +138,4 @@ Yes. Each device enters presence with its own `clientId`. See [agent presence](/
 - [Reconnection and recovery](/docs/ai-transport/features/reconnection-and-recovery): each device reconnects independently.
 - [Cancellation](/docs/ai-transport/features/cancellation): cancel from any device.
 - [History and replay](/docs/ai-transport/features/history): late joiners load the full conversation.
+- [Database hydration](/docs/ai-transport/features/database-hydration): seed a device from your own store and reconcile it with the live channel.

From e43432de7060a0b0a85535b8060c06276dd01506 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:47:07 +0100
Subject: [PATCH 10/15] AI Transport docs: align framework pages with v0.4.0

- vercel-ai-sdk-core.mdx: rebuild the model context by draining run.view
  instead of the removed loadConversation; await the now-async
  session.close().
- vercel-ai-sdk-ui.mdx: note that useMessageSync's messages seed reconciles
  a database-loaded conversation with the live channel.

AIT-1090
---
 .../ai-transport/frameworks/vercel-ai-sdk-core.mdx    | 11 ++++++++---
 .../docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx |  2 +-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
index f5a7b2303a..933a9d0a91 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
@@ -79,11 +79,16 @@ export async function POST(req) {
 
   after(async () => {
     await run.start();
-    await run.loadConversation();
+
+    // Drain run.view for the prior conversation to feed the model.
+    while (run.view.hasOlder()) {
+      await run.view.loadOlder();
+    }
+    const conversation = run.view.getMessages().map(({ message }) => message);
 
     const result = streamText({
       model: anthropic('claude-sonnet-4-20250514'),
-      messages: await convertToModelMessages(run.messages),
+      messages: await convertToModelMessages(conversation),
       abortSignal: run.abortSignal,
     });
 
@@ -94,7 +99,7 @@ export async function POST(req) {
     } else {
       await run.end(outcome);
     }
-    session.close();
+    await session.close();
   });
 
   return Response.json({ runId: run.runId, invocationId: run.invocationId });
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
index 9d06816657..fdff32067f 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
@@ -61,7 +61,7 @@ The integration has four parts:
 
 1. The `UIMessageCodec` encodes Vercel's `UIMessageChunk` events as Ably messages. Every chunk type (`text-delta`, `tool-input`, `finish`, and others) maps to an Ably message with headers that track its metadata. The codec encodes on the server, decodes on the client, and reassembles chunks into complete `UIMessage` objects.
 2. `ChatTransportProvider` creates the underlying `ClientSession` and the `ChatTransport` adapter and makes both available through context. `useChatTransport` is a context reader that returns `{ session, chatTransport }`.
-3. `useMessageSync` subscribes to the transport's conversation tree and pushes updates into `useChat`'s `setMessages`. This is what brings multi-device sync and conversation branching into Vercel's local state without `useChat` natively supporting them.
+3. `useMessageSync` subscribes to the transport's conversation tree and pushes updates into `useChat`'s `setMessages`. This is what brings multi-device sync and conversation branching into Vercel's local state without `useChat` natively supporting them. Pass a `messages` seed to reconcile a conversation loaded from your own database with the live channel; see [database hydration](/docs/ai-transport/features/database-hydration).
 4. On the server, `run.pipe(result.toUIMessageStream())` pipes the model's output through the codec encoder to the Ably channel. The HTTP response returns status 200 with an empty body. Tokens reach every connected client through the channel, not through the HTTP response. See [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core) for the server-side detail.
 
 ## Scope and trade-offs <a id="scope"/>

From 346e13bc82efcf0b356b76b1e5526387200ab5a1 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:48:40 +0100
Subject: [PATCH 11/15] AI Transport docs: align getting-started guides with
 v0.4.0

- core-sdk.mdx / vercel-ai-sdk.mdx: rebuild the model context by draining
  run.view instead of the removed loadConversation; view.send returns a
  ClientRun (toInvocation via clientRun).
- core-sdk.mdx: drop selectSibling from the useView surface list and the
  branching pointer in favour of the branchSelection handle's select;
  ClientView naming.

authentication.mdx is unchanged: it only uses useClientSession, which did
not change in v0.4.0.

AIT-1090
---
 .../ai-transport/getting-started/core-sdk.mdx   | 17 +++++++++++------
 .../getting-started/vercel-ai-sdk.mdx           | 11 ++++++++---
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
index 6d11529c04..c092e71c24 100644
--- a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
@@ -77,12 +77,17 @@ export async function POST(req) {
   after(async () => {
     try {
       await run.start();
-      await run.loadConversation();
+
+      // Drain run.view for the prior conversation to feed the model.
+      while (run.view.hasOlder()) {
+        await run.view.loadOlder();
+      }
+      const conversation = run.view.getMessages().map(({ message }) => message);
 
       const result = streamText({
         model: anthropic('claude-sonnet-4-20250514'),
         system: 'You are a helpful assistant.',
-        messages: await convertToModelMessages(run.messages),
+        messages: await convertToModelMessages(conversation),
         abortSignal: run.abortSignal,
       });
 
@@ -229,18 +234,18 @@ Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the sam
 
 ## What is happening <a id="whats-happening"/>
 
-1. The user types a message. `view.send(...)` mints `inputEventId` and the message's `codecMessageId`, publishes the user input on the channel with those ids stamped under `extras.ai.transport`, and returns an `ActiveRun` carrying the `inputCodecMessageId` the client owns synchronously. The SDK does not POST to your agent endpoint itself.
-2. Your client code calls `activeRun.toInvocation().toJSON()` to get an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`), and POSTs it to your agent endpoint.
+1. The user types a message. `view.send(...)` mints `inputEventId` and the message's `codecMessageId`, publishes the user input on the channel with those ids stamped under `extras.ai.transport`, and returns a `ClientRun` carrying the `inputCodecMessageId` the client owns synchronously. The SDK does not POST to your agent endpoint itself.
+2. Your client code calls `clientRun.toInvocation().toJSON()` to get an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`), and POSTs it to your agent endpoint.
 3. The agent endpoint receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a `Run` from the Invocation. `session.createRun(invocation)` mints a fresh `runId` (for a fresh run) and a fresh `invocationId`; the agent returns both on the response so callers can observe them. `Run.start()` waits for the trigger input event on the channel (rewind + live).
 4. The agent streams the LLM response through `run.pipe(...)` to the channel. Every output carries `input-codec-message-id` so the client can correlate by an id it owned at send time.
 5. Every client subscribed to the channel receives the streamed messages in real time. `useView` re-renders as the visible Run's projection updates.
 6. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the SDK rehydrates the view automatically.
 
-`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. The hook exposes `messages`, `hasOlder`, `loading`, `loadError`, `loadOlder`, `runOf`, `run`, `runs`, `branchSelection`, `selectSibling`, `send`, `regenerate`, and `edit`. It is the reactive mirror of the [`View` interface](/docs/ai-transport/api/javascript/core/client-session#view).
+`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. The hook exposes `messages`, `hasOlder`, `loading`, `loadError`, `loadOlder`, `runOf`, `run`, `runs`, `branchSelection`, `send`, `regenerate`, and `edit`. Switch siblings through the `branchSelection` handle's `select`. It is the reactive mirror of the [`ClientView` interface](/docs/ai-transport/api/javascript/core/client-session#view).
 
 ## Explore next <a id="next"/>
 
-- [Branching, edit, and regenerate](/docs/ai-transport/features/branching): fork the conversation and navigate alternative branches with `view.regenerate`, `view.edit`, and `view.selectSibling`.
+- [Branching, edit, and regenerate](/docs/ai-transport/features/branching): fork the conversation and navigate alternative branches with `view.regenerate`, `view.edit`, and the `view.branchSelection` handle's `select`.
 - [History and replay](/docs/ai-transport/features/history): `useView` loads history on mount via the `limit` option.
 - [Cancellation](/docs/ai-transport/features/cancellation): the Stop button pattern and the agent-side `onCancel` authorisation hook.
 - [Concepts: Runs](/docs/ai-transport/concepts/runs): the SDK primitive each turn becomes.
diff --git a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
index 5156d0d703..e04229a923 100644
--- a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
@@ -82,12 +82,17 @@ export async function POST(req) {
   after(async () => {
     try {
       await run.start();
-      await run.loadConversation();
+
+      // Drain run.view for the prior conversation to feed the model.
+      while (run.view.hasOlder()) {
+        await run.view.loadOlder();
+      }
+      const conversation = run.view.getMessages().map(({ message }) => message);
 
       const result = streamText({
         model: anthropic('claude-sonnet-4-20250514'),
         system: 'You are a helpful assistant.',
-        messages: await convertToModelMessages(run.messages),
+        messages: await convertToModelMessages(conversation),
         abortSignal: run.abortSignal,
       });
 
@@ -224,7 +229,7 @@ Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the sam
 
 ## What is happening <a id="what-is-happening"/>
 
-1. `sendMessage({ text })` calls the `ChatTransport`'s `sendMessages`. Under the hood, the AI Transport client SDK mints `inputEventId` and the message's `codecMessageId`, stamps them on the channel publish under `extras.ai.transport`, and returns an `ActiveRun` carrying the synchronous `inputCodecMessageId`. The `ChatTransport` then calls `activeRun.toInvocation().toJSON()` and POSTs the resulting `InvocationData` body (`{ inputEventId, sessionName }`) to your agent endpoint.
+1. `sendMessage({ text })` calls the `ChatTransport`'s `sendMessages`. Under the hood, the AI Transport client SDK mints `inputEventId` and the message's `codecMessageId`, stamps them on the channel publish under `extras.ai.transport`, and returns a `ClientRun` carrying the synchronous `inputCodecMessageId`. The `ChatTransport` then calls `clientRun.toInvocation().toJSON()` and POSTs the resulting `InvocationData` body (`{ inputEventId, sessionName }`) to your agent endpoint.
 2. The agent route receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a Run. `session.createRun(invocation)` mints `runId` (for a fresh run) and `invocationId` (one per HTTP request); the agent stamps both on every event it publishes and returns them on the response. `run.start()` waits for the trigger input event on the channel (rewind plus live).
 3. The agent streams the LLM response through `run.pipe()` to the channel. Outputs carry `input-codec-message-id` so the client can correlate by an id it owned at send time.
 4. Every client subscribed to the channel decodes the streamed messages in real time. `useChat` re-renders as `UIMessage` parts accumulate.

From ce37603c669b34eeed09dc3b93fc5c66eae10987 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:51:28 +0100
Subject: [PATCH 12/15] AI Transport docs: align internals with the v0.4.0
 input-event watcher

- transport-patterns.mdx: replace the input-event lookup section (rewind +
  inputEventLookupTimeoutMs + inputEventBufferLimit + InputEventNotFound)
  with the input-event watcher armed by createRun and awaited via
  run.located; ActiveRun -> ClientRun with started.
- wire-protocol.mdx: AgentRun.start awaits run.located (no rewindWindow /
  lookup timeout / InputEventNotFound); ActiveRun.runId -> clientRun.runId
  populated after started.
- conversation-tree.mdx: branch navigation via the branchSelection handle's
  select (BranchSelection -> BranchHandle); ClientRun naming.

AIT-1090
---
 .../internals/conversation-tree.mdx           |  6 +--
 .../internals/transport-patterns.mdx          | 40 +++++++++----------
 .../ai-transport/internals/wire-protocol.mdx  | 12 +++---
 3 files changed, 28 insertions(+), 30 deletions(-)

diff --git a/src/pages/docs/ai-transport/internals/conversation-tree.mdx b/src/pages/docs/ai-transport/internals/conversation-tree.mdx
index a7a7a18aba..e67b27bee6 100644
--- a/src/pages/docs/ai-transport/internals/conversation-tree.mdx
+++ b/src/pages/docs/ai-transport/internals/conversation-tree.mdx
@@ -27,7 +27,7 @@ Input edits are sibling input nodes. `I2` and `I2'` share the same parent (`R1`'
 
 Regenerate siblings are sibling reply runs. `R1` and `R1'` share the same parent (`I1`'s `codecMessageId M1`), and `R1'.regeneratesCodecMessageId = M2` records the slot it replaces. Reply-run siblings group by shared parent; they carry no Run-level `forkOf`.
 
-Branch selection is message-anchored: the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)` and `selectSibling(codecMessageId, index)` so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run.
+Branch selection is message-anchored: the branch decision lives on a `codec-message-id`, not on a `runId`. The View exposes `branchSelection(codecMessageId)`, whose returned handle carries a `select(index)` verb, so a UI renders navigation arrows next to a bubble without knowing whether it is an input or a run.
 
 ## Why two node kinds <a id="why-two-node-kinds"/>
 
@@ -66,7 +66,7 @@ Every node in the tree is a `ConversationNode = InputNode | RunNode`. Narrow on
 
 ## Run identity is resolved on the channel <a id="run-identity"/>
 
-The Tree adopts run identity from the wire, not from the HTTP POST body. A fresh run begins when the client publishes an input event with no `run-id`; the agent's `createRun` mints a `run-id`, stamps it on `ai-run-start` and every output event, and the Tree creates a `RunNode` from the run-start. A continuation begins when the input event carries an existing `run-id` (the client knew it from `ActiveRun.runId` and stamped it on the publish); the agent reads that id from the input event's wire headers, reuses it instead of minting fresh, and publishes `ai-run-resume` so the Tree routes the resume to the existing `RunNode`.
+The Tree adopts run identity from the wire, not from the HTTP POST body. A fresh run begins when the client publishes an input event with no `run-id`; the agent's `createRun` mints a `run-id`, stamps it on `ai-run-start` and every output event, and the Tree creates a `RunNode` from the run-start. A continuation begins when the input event carries an existing `run-id` (the client knew it from `clientRun.runId` and stamped it on the publish); the agent reads that id from the input event's wire headers, reuses it instead of minting fresh, and publishes `ai-run-resume` so the Tree routes the resume to the existing `RunNode`.
 
 There is no `run-continue` header: the presence or absence of `run-id` on the input event is the entire signal.
 
@@ -86,7 +86,7 @@ Earlier versions of the SDK described a "winner / precedence" model on the Tree.
 
 The result is ordered oldest-first by serial. It is a single-element array when the node has no siblings, and an empty array when the key is unknown.
 
-The View consumes this to compute `branchSelection(codecMessageId)`, which returns a `BranchSelection<TMessage>` bundle (`hasSiblings`, `siblings`, `index`, `selected`). The View's per-instance `selections` map records the selected sibling at each anchor; `selectSibling(codecMessageId, index)` updates it and emits an `'update'` event.
+The View consumes this to compute `branchSelection(codecMessageId)`, which returns a `BranchHandle<TMessage>` (`hasSiblings`, `siblings`, `index`, `selected`, `select`). The View's per-instance `selections` map records the selected sibling at each anchor; the handle's `select(index)` updates it and emits an `'update'` event.
 
 ## Walk the tree <a id="walking-the-tree"/>
 
diff --git a/src/pages/docs/ai-transport/internals/transport-patterns.mdx b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
index c7bc8b215d..e3ef673a13 100644
--- a/src/pages/docs/ai-transport/internals/transport-patterns.mdx
+++ b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
@@ -31,7 +31,7 @@ Tree emits:  'update'      structural change (node insert / sort / lifecycle)
       │
       ▼
 View ── walks the selected branch, emits 'update' on visible changes
-ActiveRun ── runId Promise resolves on the matching ai-run-start
+ClientRun ── runId populated (started resolves) on the matching ai-run-start
 ```
 
 Outbound data flow on the agent:
@@ -58,50 +58,48 @@ Run.abortSignal ◄── cancel routing fires on matching ai-cancel
 
 The stream router lives on the client. It routes inbound channel events to the correct per-Run state, turning a flat channel subscription into per-Run projections that the View exposes as visible messages.
 
-The router keys on the triggering input's `codec-message-id`, the synchronous handle the client owns from send time (the agent has not minted the `runId` yet). When the client calls a write method on the View (`send`, `regenerate`, `edit`), the View mints the input's `codec-message-id`, publishes the input on the channel, and registers an optimistic input node in the Tree. The returned `ActiveRun` carries the synchronous `inputCodecMessageId`, the `inputEventId`, and a `runId: Promise<string>` that resolves when the agent's `ai-run-start` for this send lands.
+The router keys on the triggering input's `codec-message-id`, the synchronous handle the client owns from send time (the agent has not minted the `runId` yet). When the client calls a write method on the View (`send`, `regenerate`, `edit`), the View mints the input's `codec-message-id`, publishes the input on the channel, and registers an optimistic input node in the Tree. The returned `ClientRun` carries the synchronous `inputCodecMessageId`, the `inputEventId`, and a `started` promise that resolves (populating `runId`) when the agent's `ai-run-start` for this send lands.
 
 When inbound `ai-output` messages decode to `TOutput` events, the router folds them into the matching Run's per-Run projection by reading the output's `input-codec-message-id` header (the agent echoes the triggering input's id on every event it publishes). When `ai-run-end` arrives for the Run, the router marks the Run terminal. The View's `update` event fires; consumers re-read `getMessages()` / `runs()`.
 
 If the channel loses continuity (`ChannelContinuityLost`), the router surfaces the error via the session's `on('error', ...)` and active Runs are marked accordingly.
 
-## Input-event lookup <a id="input-event-lookup"/>
+## Input-event watcher <a id="input-event-lookup"/>
 
-The input-event lookup lives on the agent. When `Run.start()` is called, the agent attaches the channel with `rewind` and waits for the triggering `event-id` carried in the invocation body to arrive on the channel.
+The input-event watcher lives on the agent. `createRun` arms it: a passive pre-scan of the Tree plus a listener for the trigger's arrival. `AgentRun.start()` awaits `run.located`, which resolves when the triggering `event-id` carried in the invocation body folds into the Tree, whether it is already present or arrives live.
 
 The sequence:
 
 ```text
 1. Client publishes ai-input with event-id=E1 on the channel.
    Fresh send: no run-id on the input.
-   Continuation: existing run-id stamped on the input from ActiveRun.runId.
+   Continuation: existing run-id stamped on the input from clientRun.runId.
 2. Client POSTs InvocationData ({ inputEventId=E1, sessionName }) to the agent.
 3. Agent route receives the POST.
 4. Agent calls session.createRun(invocation, runtime). createRun mints the
-   invocationId and registers the run for cancel routing immediately so
-   early cancels fire.
-5. Agent calls run.start(). The session attaches the channel with the
-   configured rewindWindow and waits for E1 to arrive.
-6. Either:
-   - E1 is already on the channel (rewind) ──► resolves immediately.
-   - E1 arrives live within inputEventLookupTimeoutMs ──► resolves.
-   - inputEventLookupTimeoutMs lapses ──► rejects with InputEventNotFound.
-7. The input event tells the agent which run-id to use: it mints a fresh
+   invocationId, arms the input-event watcher (a passive Tree pre-scan plus a
+   listener), and registers the run for cancel routing so early cancels fire.
+5. Agent calls run.start(). It awaits run.located: the watcher matches E1
+   whether it is already folded into the Tree (a history page the agent paged
+   in, for example via run.view.loadOlder() on a cold start) or folds in live
+   after attach. There is no lookup timeout; located rejects only on cancel or
+   session close.
+6. The input event tells the agent which run-id to use: it mints a fresh
    run-id when the input event omits one, or reuses the run-id stamped on
    the input event for a continuation.
-8. run.start() resolves, the agent fetches conversation history and pipes
-   the LLM stream. The agent route returns { runId: run.runId,
-   invocationId: run.invocationId } on the HTTP response.
+7. run.start() resolves and publishes ai-run-start (or ai-run-resume). The
+   agent drains run.view for context and pipes the LLM stream. The agent route
+   returns { runId: run.runId, invocationId: run.invocationId } on the HTTP
+   response.
 ```
 
-The buffer that holds pre-`start` events is sized by `inputEventBufferLimit` (default 200 input events). When the buffer is full, the oldest input event is FIFO-evicted; the client whose input was dropped fails its lookup with `InputEventNotFound`.
-
-This is the mechanism that lets a serverless agent publish a Run reliably even when the channel publish and the HTTP POST race: the agent waits on the channel until the input event lands, then proceeds. Without it, an agent that attaches after the client published would never see the triggering event.
+This is the mechanism that lets a serverless agent publish a Run reliably even when the channel publish and the HTTP POST race: the watcher resolves the trigger from the Tree whether it arrived before or after the agent attached. Without it, an agent that attached after the client published would never see the triggering event.
 
 ## Cancel routing <a id="cancel-routing"/>
 
 Cancel routing connects client cancel signals to the correct agent-side Runs. The flow:
 
-1. The client calls `session.cancel(runId)` (when it has the resolved run id from `ActiveRun.runId`) or `activeRun.cancel()` (which keys on the triggering input's `codec-message-id`, the synchronous handle). The session publishes an `ai-cancel` message under `extras.ai.transport`, carrying whichever key the caller used.
+1. The client calls `session.cancel(runId)` (when it has the resolved run id from `clientRun.runId`, after `clientRun.started`) or `clientRun.cancel()` (which keys on the triggering input's `codec-message-id`, the synchronous handle). The session publishes an `ai-cancel` message under `extras.ai.transport`, carrying whichever key the caller used.
 2. The agent session receives the cancel message through its channel subscription.
 3. The agent matches the cancel against its registered Runs. If the cancel arrives before run-start (the client cancelled before the agent minted the run id), the agent buffers it and fires once its input-event lookup resolves the input to the run.
 4. The matched Run's `onCancel` hook (if configured) is invoked. If the hook returns `false`, the cancel is rejected silently and the Run continues.
diff --git a/src/pages/docs/ai-transport/internals/wire-protocol.mdx b/src/pages/docs/ai-transport/internals/wire-protocol.mdx
index 9fe71379c3..55beb660fb 100644
--- a/src/pages/docs/ai-transport/internals/wire-protocol.mdx
+++ b/src/pages/docs/ai-transport/internals/wire-protocol.mdx
@@ -51,7 +51,7 @@ Transport headers carry the routing and identity that the transport layer reads.
 
 | Header | Description |
 | --- | --- |
-| `run-id` | Run correlation. Minted by the agent inside `session.createRun(invocation)` for a fresh run, and stamped on every event the agent publishes. Continuation client publishes also carry it (the client knows the existing `run-id` from `ActiveRun.runId` and stamps it on the continuation input event); the agent reads it from the input event's wire headers to reuse the existing Run rather than minting a fresh one. Absent on the first `ai-input` of a fresh send. |
+| `run-id` | Run correlation. Minted by the agent inside `session.createRun(invocation)` for a fresh run, and stamped on every event the agent publishes. Continuation client publishes also carry it (the client knows the existing `run-id` from `clientRun.runId` and stamps it on the continuation input event); the agent reads it from the input event's wire headers to reuse the existing Run rather than minting a fresh one. Absent on the first `ai-input` of a fresh send. |
 | `invocation-id` | Per-HTTP-request identifier. Minted by the agent inside `session.createRun(invocation)` (one per HTTP request) and stamped on every event the agent publishes for that invocation (lifecycle + outputs). Not present on client `ai-input` events; the application returns it on the HTTP response so the caller can observe it. |
 | `event-id` | Per-event identifier on client publishes. The invocation body carries the triggering `event-id` so the agent's `Run.start()` knows which event to wait for. Distinct from `codec-message-id` so edits and retries that reuse the same `codec-message-id` still carry a fresh per-send identity. |
 | `codec-message-id` | Message identity in the conversation tree. Used for branch anchoring (edit forks at the user's `codec-message-id`, regenerate forks at the assistant's), for optimistic reconciliation, and for stream append targeting. |
@@ -160,15 +160,15 @@ Edit and regenerate forks are message-anchored: the new Run's `fork-of` (for an
 When a client sends, the SDK mints two identifiers on the publishing side:
 
 - `inputEventId`: one per published input event. The last event in the send becomes the trigger the agent waits on.
-- `codecMessageId`: identity for the new message in the conversation tree. Surfaced on the returned `ActiveRun` as `inputCodecMessageId` so the client can route the agent's outputs back to the input it owned at send time.
+- `codecMessageId`: identity for the new message in the conversation tree. Surfaced on the returned `ClientRun` as `inputCodecMessageId` so the client can route the agent's outputs back to the input it owned at send time.
 
-For continuations only, the client also stamps the existing `run-id` on the input event's wire headers (the client knows it from the previous `ActiveRun.runId`). Fresh sends omit `run-id` and leave the agent to mint it.
+For continuations only, the client also stamps the existing `run-id` on the input event's wire headers (the client knows it from the previous `clientRun.runId`). Fresh sends omit `run-id` and leave the agent to mint it.
 
-The SDK does not POST to the agent endpoint itself; the developer (or the bundled [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)) calls `activeRun.toInvocation().toJSON()` to obtain an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`) and POSTs it to the agent.
+The SDK does not POST to the agent endpoint itself; the developer (or the bundled [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport)) calls `clientRun.toInvocation().toJSON()` to obtain an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`) and POSTs it to the agent.
 
-On the agent side, `session.createRun(invocation)` mints the `invocationId` (one per HTTP request) and either mints a fresh `runId` (no `run-id` on the input event) or reads the existing `runId` off the triggering input event's wire headers (continuation). Both are stamped on every event the agent publishes for this invocation. `Run.start()` attaches the channel with rewind and waits for the trigger `event-id` carried in the invocation body to arrive (live or via rewind). The rewind window is configured by `rewindWindow` on `AgentSessionOptions`; the lookup timeout is `inputEventLookupTimeoutMs`. If the lookup lapses, `Run.start()` rejects with [`InputEventNotFound`](/docs/ai-transport/api/errors).
+On the agent side, `session.createRun(invocation)` mints the `invocationId` (one per HTTP request) and either mints a fresh `runId` (no `run-id` on the input event) or reads the existing `runId` off the triggering input event's wire headers (continuation). Both are stamped on every event the agent publishes for this invocation. `AgentRun.start()` awaits `run.located`: the run's input-event watcher matches the trigger `event-id` carried in the invocation body, whether it is already folded into the Tree (from channel history the agent paged in) or arrives live. There is no lookup timeout.
 
-The agent's outputs carry `input-codec-message-id` (the `codec-message-id` of the triggering input) under `extras.ai.transport`. The client uses this to correlate outputs back to the input it owned at send time, so `ActiveRun.runId` resolves once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe the agent-minted ids directly.
+The agent's outputs carry `input-codec-message-id` (the `codec-message-id` of the triggering input) under `extras.ai.transport`. The client uses this to correlate outputs back to the input it owned at send time, so `clientRun.runId` is populated once `ai-run-start` lands (await `clientRun.started`). The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe the agent-minted ids directly.
 
 This is the mechanism that lets a serverless agent publish a Run reliably even when the channel publish and the HTTP POST race: the agent waits on the channel until the input event lands, then proceeds.
 

From 86f1cdc04bfa3e146a19bafb0449b0a610e99e27 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 21:53:10 +0100
Subject: [PATCH 13/15] AI Transport docs: remove the removed Run.addEvents
 from tool calling

Run.addEvents and the EventsNode type were removed from the public API. A
late tool result is delivered as a tool-result input addressed to the
original message on a continuation (the pattern already shown above on the
page), not via a cross-run addEvents call. Drop the obsolete section and fix
the edge-case bullet that referenced it.

AIT-1090
---
 .../ai-transport/features/tool-calling.mdx    | 26 +------------------
 1 file changed, 1 insertion(+), 25 deletions(-)

diff --git a/src/pages/docs/ai-transport/features/tool-calling.mdx b/src/pages/docs/ai-transport/features/tool-calling.mdx
index f644d8285f..ae21e73fa8 100644
--- a/src/pages/docs/ai-transport/features/tool-calling.mdx
+++ b/src/pages/docs/ai-transport/features/tool-calling.mdx
@@ -122,30 +122,6 @@ if (pending) {
 
 The result is addressed to the suspended assistant message by `codecMessageId`. Reusing the original `runId` keeps the resume on the same run instead of starting a fresh one.
 
-## Cross-run events with addEvents <a id="add-events"/>
-
-The agent uses `Run.addEvents` to push events to a message owned by an earlier run. The common case is delivering a late tool result on a continuation run without starting a new assistant message:
-
-<Code>
-```javascript
-await run.addEvents([
-  {
-    kind: 'event',
-    codecMessageId: pendingAssistantCodecMessageId,
-    events: [
-      {
-        type: 'tool-output-available',
-        toolCallId,
-        output: { temperature: 22, conditions: 'sunny' },
-      },
-    ],
-  },
-]);
-```
-</Code>
-
-Events published through `addEvents` update the target message in the view. Because they target an existing message by its `codecMessageId`, late joiners and reconnecting clients see the correct state when the conversation replays from history.
-
 ## History persistence <a id="history"/>
 
 Tool invocations and results are part of the channel's message history. When a client reconnects or a late joiner loads the conversation, tool activity is replayed along with text messages. The view reconstructs tool state so the UI shows the correct status: pending, complete, or failed.
@@ -155,7 +131,7 @@ A user who starts a tool-assisted workflow on a laptop continues it on a phone w
 ## Edge cases and unhappy paths <a id="edge-cases"/>
 
 - A client-executed tool that the user denies (for example a geolocation permission prompt) leaves the tool call pending. Submit a failure with `codec.createToolResultError(codecMessageId, { toolCallId, message })` (or the literal `{ kind: 'tool-result-error', ... }`) to unblock the LLM, or end the turn explicitly.
-- A tool that takes longer than the agent's runtime budget runs past `run.end()`. The continuation run picks up the result through `addEvents` on the original message; do not start a new run just to deliver a late result.
+- A tool that takes longer than the agent's runtime budget should suspend the run rather than end it. When the result is ready, publish it as a `tool-result` input addressed to the original message on a continuation (the pattern shown above), which resumes the same run; do not start a new run just to deliver a late result.
 - A server-executed tool that does not honour `run.abortSignal` keeps running after a cancel. Wire the signal into your tool implementation.
 - Two clients submitting the same client-executed tool concurrently produce two continuation turns. Guard against double-submit at the application layer.
 - A failed tool call is delivered with an error result. The view exposes the failure; render it in place rather than silently retrying.

From 43ff9e1f80de65ad5e7fd2d4b3e49121e8e7ac2e Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Tue, 30 Jun 2026 22:04:42 +0100
Subject: [PATCH 14/15] AI Transport docs: address final docs-review-all
 findings

Link integrity:
- errors.mdx: Ably error codes link -> /docs/platform/errors/codes.
- chain-of-thought.mdx: codec link -> api/javascript/core/codec.
- vercel-ai-sdk-ui.mdx: Vercel API link -> the chat-transport page.
- repoint the anchorless client-session#view links to #properties
  (connections, invocations, runs, core-sdk, client-session).
- troubleshooting.mdx: branching#branch-navigation -> #navigate.
- run-outcome.mdx: reference the VercelRunOutcome table inline so it renders.

Code accuracy (SendOptions is { forkOf, parent, runId } only):
- use-view.mdx: remove the fabricated SendOptions.inputEventId row.
- invocations.mdx: drop the false "override inputEventId/codecMessageId via
  SendOptions" claim.
- transport-patterns.mdx / troubleshooting.mdx: run.end takes a RunEndParams
  object, so run.end({ reason }), not the positional run.end(reason).

AIT-1090
---
 src/pages/docs/ai-transport/api/errors.mdx             |  2 +-
 .../api/javascript/core/client-session.mdx             |  2 +-
 .../ai-transport/api/javascript/vercel/run-outcome.mdx |  2 +-
 .../docs/ai-transport/api/react/core/use-view.mdx      |  1 -
 src/pages/docs/ai-transport/concepts/connections.mdx   |  2 +-
 src/pages/docs/ai-transport/concepts/invocations.mdx   | 10 +++++-----
 src/pages/docs/ai-transport/concepts/runs.mdx          |  6 +++---
 .../docs/ai-transport/features/chain-of-thought.mdx    |  2 +-
 .../docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx  |  2 +-
 .../docs/ai-transport/getting-started/core-sdk.mdx     |  2 +-
 .../docs/ai-transport/internals/transport-patterns.mdx |  2 +-
 src/pages/docs/ai-transport/troubleshooting.mdx        |  4 ++--
 12 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/errors.mdx b/src/pages/docs/ai-transport/api/errors.mdx
index 8f13958b54..7fe4009de1 100644
--- a/src/pages/docs/ai-transport/api/errors.mdx
+++ b/src/pages/docs/ai-transport/api/errors.mdx
@@ -64,7 +64,7 @@ Auth and channel errors come from the Ably platform, not AI Transport. The most
 | 90000 | Internal channel error. | Retry the operation. If the error persists, contact support. |
 | 93002 | `Can only update/delete/append messages on channels with mutableMessages enabled`. The namespace lacks the `mutableMessages` rule, so AI Transport cannot append stream tokens. This is the most common AI Transport setup failure. | Enable the **Message annotations, updates, deletes, and appends** rule on the namespace. See [Configure the channel rule](/docs/ai-transport/getting-started/channel-rules). |
 
-The full Ably error code list lives at [Ably error codes](/docs/sdks/error-codes).
+The full Ably error code list lives at [Ably error codes](/docs/platform/errors/codes).
 
 ## Match an ErrorInfo against a code <a id="error-info-is"/>
 
diff --git a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
index 4da104e9ed..f0536cefb1 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/client-session.mdx
@@ -120,7 +120,7 @@ const session = createClientSession({
 
 Subscribe to the channel and implicitly attach. Idempotent: subsequent calls return the same promise.
 
-All write methods on [`view`](/docs/ai-transport/api/javascript/core/client-session#view) and [`cancel`](#cancel) throw `InvalidArgument` until `connect()` resolves.
+All write methods on [`view`](/docs/ai-transport/api/javascript/core/client-session#properties) and [`cancel`](#cancel) throw `InvalidArgument` until `connect()` resolves.
 
 <Code>
 ```javascript
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
index 8284050a37..f596861f03 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
@@ -69,7 +69,7 @@ The rejection guard matters: Vercel AI SDK v6 rejects `streamText().finishReason
 - `{ reason: 'complete' | 'cancelled' }`: the run terminated normally. Pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
 - `{ reason: 'error', error }`: the run failed. `error` is an `Ably.ErrorInfo`. Pass the outcome to [`Run.end`](/docs/ai-transport/api/javascript/core/agent-session#run-end).
 
-`error` is present only on the `'error'` arm. The non-`'suspend'` arms are assignable to [`RunEndParams`](/docs/ai-transport/api/javascript/core/agent-session#run-end-params), so after a `'suspend'` guard the whole object passes straight to `Run.end(outcome)`.
+`error` is present only on the `'error'` arm. The non-`'suspend'` arms are assignable to [`RunEndParams`](/docs/ai-transport/api/javascript/core/agent-session#run-end-params), so after a `'suspend'` guard the whole object passes straight to `Run.end(outcome)`. <Table id='VercelRunOutcome'/>
 
 <Table id='VercelRunOutcome' hidden>
 
diff --git a/src/pages/docs/ai-transport/api/react/core/use-view.mdx b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
index 79bba446ce..8f17b461e1 100644
--- a/src/pages/docs/ai-transport/api/react/core/use-view.mdx
+++ b/src/pages/docs/ai-transport/api/react/core/use-view.mdx
@@ -101,7 +101,6 @@ This hook must be used within a [`ClientSessionProvider`](/docs/ai-transport/api
 | forkOf | The codec-message-id of the message this send replaces (fork). | String |
 | parent | The codec-message-id of the predecessor in the conversation thread. Auto-computed when omitted. | String |
 | runId | Reuse an existing `runId` (for example to resume a suspended run). | String |
-| inputEventId | Override the `inputEventId` for this send. Defaults to `crypto.randomUUID()`. | String |
 
 </Table>
 
diff --git a/src/pages/docs/ai-transport/concepts/connections.mdx b/src/pages/docs/ai-transport/concepts/connections.mdx
index d68ecbc06c..a9c10ef8c4 100644
--- a/src/pages/docs/ai-transport/concepts/connections.mdx
+++ b/src/pages/docs/ai-transport/concepts/connections.mdx
@@ -50,7 +50,7 @@ A connection moves through four stages. Construct it with `createClientSession`
 Several `ClientSession` instances can be open against the same session simultaneously. Each one independently:
 
 - Materialises the tree from the channel (the same tree, on the wire).
-- Selects its own branch via the [`view.branchSelection`](/docs/ai-transport/api/javascript/core/client-session#view) handle's `select` method.
+- Selects its own branch via the [`view.branchSelection`](/docs/ai-transport/api/javascript/core/client-session#properties) handle's `select` method.
 - Holds its own pagination window over older messages.
 
 What they share is the channel-backed state. A message one client publishes lands on every other client's tree via the channel subscription. A cancel one client publishes is observed by the agent (and by every other client) through their own subscriptions.
diff --git a/src/pages/docs/ai-transport/concepts/invocations.mdx b/src/pages/docs/ai-transport/concepts/invocations.mdx
index e35f233ea5..3019c81989 100644
--- a/src/pages/docs/ai-transport/concepts/invocations.mdx
+++ b/src/pages/docs/ai-transport/concepts/invocations.mdx
@@ -28,21 +28,21 @@ An `InvocationData` is the wire shape: the JSON body in the POST.
 
 | Field | What it carries |
 | --- | --- |
-| `inputEventId` | The input event on the channel that triggered this invocation. The agent's `AgentRun.start()` awaits the channel message carrying this `event-id`; the run's input-event watcher matches it whether it arrives live or already sits in channel history. |
+| `inputEventId` | The input event on the channel that triggered this invocation. The agent's `AgentRun.start()` waits until the channel message carrying this `event-id` has been observed, whether it arrives live or is paged in from channel history. |
 | `sessionName` | The session's logical name, used as the Ably channel name. |
 
 The `Invocation` class is the runtime view of that data. The client side uses `ClientRun.toInvocation()` to obtain one from a returned `ClientRun`; the agent side uses `Invocation.fromJSON(data)` to construct one from the parsed POST body, then hands it to `session.createRun(invocation, runtime?)`. `createRun` mints the `invocationId` (one per HTTP request) and, for a fresh run, the `runId`; for a continuation the agent reads the existing `runId` off the triggering input event's wire headers. The application returns `run.runId` and `run.invocationId` on the HTTP response so the caller can observe them.
 
-End-to-end: the client publishes the input event on the channel and gets back a `ClientRun`. The client knows `inputCodecMessageId` immediately, before the agent has minted the run; `clientRun.runId` is populated later, once the agent's `ai-run-start` event lands (await `clientRun.started`). The application POSTs `clientRun.toInvocation().toJSON()` to the agent endpoint. The agent rebuilds the Invocation, calls `createRun` (which mints `invocationId` and resolves `runId` either by minting for a fresh run or by reading the input event for a continuation, and arms the run's input-event watcher), and `run.start()` awaits the matching input event folding into the tree, whether it arrives live or already sits in channel history. Output events the agent publishes carry the `run-id`, `invocation-id`, and `input-codec-message-id` headers; the client reads `clientRun.runId` once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the original caller can observe the agent-minted identifiers directly.
+End-to-end: the client publishes the input event on the channel and gets back a `ClientRun`. The client knows `inputCodecMessageId` immediately, before the agent has minted the run; `clientRun.runId` is populated later, once the agent's `ai-run-start` event lands (await `clientRun.started`). The application POSTs `clientRun.toInvocation().toJSON()` to the agent endpoint. The agent rebuilds the Invocation, calls `createRun` (which mints `invocationId` and resolves `runId` either by minting for a fresh run or by reading the input event for a continuation), and `run.start()` waits until the matching input event has been observed on the channel, whether it arrives live or is paged in from channel history. Output events the agent publishes carry the `run-id`, `invocation-id`, and `input-codec-message-id` headers; the client reads `clientRun.runId` once `ai-run-start` lands. The application returns `run.runId` and `run.invocationId` on the HTTP response so the original caller can observe the agent-minted identifiers directly.
 
 ## What the Invocation layer requires <a id="requires"/>
 
 | Property | Why it matters |
 | --- | --- |
 | Stable identity | The triggering input event must be addressable from both sides. The client stamps `event-id` on the channel publish, and your code posts the same `inputEventId` in the body. If they diverged, the agent's lookup would fail. |
-| Deterministic generation | The client mints `inputEventId` and `codecMessageId` inside `view.send()` (and the other write methods). Defaults to `crypto.randomUUID()`; override via [`SendOptions`](/docs/ai-transport/api/javascript/core/client-session#view) for deterministic tests. The agent mints `runId` and `invocationId` per request; supply `RunRuntime.runId` / `RunRuntime.invocationId` to override in tests. |
+| Deterministic generation | The client mints `inputEventId` and `codecMessageId` inside `view.send()` (and the other write methods), each defaulting to `crypto.randomUUID()`. The agent mints `runId` and `invocationId` per request; supply `RunRuntime.runId` / `RunRuntime.invocationId` to override them in tests. |
 | Idempotency | The agent endpoint may receive the same Invocation more than once (network retry, queue redelivery). The agent must treat duplicate Invocations safely, typically by checking whether the input event has already produced a Run on the channel. |
-| Decoupled timing | The POST may arrive before, simultaneously with, or after the input event on the channel. The agent's `AgentRun.start()` awaits the input event through the run's input-event watcher, which matches it whether it already sits in channel history or arrives live, so the order doesn't matter. |
+| Decoupled timing | The POST may arrive before, simultaneously with, or after the input event on the channel. The agent's `AgentRun.start()` waits until the input event has been observed, whether it is paged in from channel history or arrives live, so the order doesn't matter. |
 | Continuation support | A tool-result delivery or a regenerate produces a new Invocation; the client stamps the existing `run-id` on the new input event's wire headers when publishing. The agent's `createRun` reads that `run-id` from the input event instead of minting a fresh one, and the SDK treats it as a continuation. |
 
 ## Receive an Invocation <a id="receive"/>
@@ -69,7 +69,7 @@ export async function POST(req) {
 ```
 </Code>
 
-On the client, the [`view.send`](/docs/ai-transport/api/javascript/core/client-session#view) call generates the identifiers, stamps them on the channel publish, and returns the `ClientRun`. Your application code (or the [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) wrapper) calls `clientRun.toInvocation().toJSON()` to build the POST body and sends it to the agent endpoint.
+On the client, the [`view.send`](/docs/ai-transport/api/javascript/core/client-session#properties) call generates the identifiers, stamps them on the channel publish, and returns the `ClientRun`. Your application code (or the [Vercel `ChatTransport`](/docs/ai-transport/api/javascript/vercel/chat-transport) wrapper) calls `clientRun.toInvocation().toJSON()` to build the POST body and sends it to the agent endpoint.
 
 ## Read next <a id="next"/>
 
diff --git a/src/pages/docs/ai-transport/concepts/runs.mdx b/src/pages/docs/ai-transport/concepts/runs.mdx
index af4e5c4d17..77032ae209 100644
--- a/src/pages/docs/ai-transport/concepts/runs.mdx
+++ b/src/pages/docs/ai-transport/concepts/runs.mdx
@@ -26,7 +26,7 @@ A Run has four invariants that the SDK enforces on every channel:
 - An owner: the `clientId` of the Ably client that published `ai-run-start`.
 - A terminal `RunEndReason` once it ends: `'complete'`, `'cancelled'`, or `'error'`. (A Run that pauses awaiting input takes `RunInfo.status === 'suspended'` via `AgentRun.suspend()`, which is non-terminal.)
 
-Within those brackets, the Run owns a window of channel messages: the user input that triggered it, the agent's streamed outputs, any tool-call or tool-result messages. The conversation [Tree](/docs/ai-transport/concepts/conversation-tree) groups those messages into a `RunNode`; the [View](/docs/ai-transport/api/javascript/core/client-session#view) surfaces projection-free [`RunInfo`](/docs/ai-transport/api/javascript/core/client-session#view) snapshots for the UI.
+Within those brackets, the Run owns a window of channel messages: the user input that triggered it, the agent's streamed outputs, any tool-call or tool-result messages. The conversation [Tree](/docs/ai-transport/concepts/conversation-tree) groups those messages into a `RunNode`; the [View](/docs/ai-transport/api/javascript/core/client-session#properties) surfaces projection-free [`RunInfo`](/docs/ai-transport/api/javascript/core/client-session#properties) snapshots for the UI.
 
 A Run is triggered by an [`Invocation`](/docs/ai-transport/concepts/invocations): the trigger the client posts to the agent endpoint that says "create or continue a Run with these identifiers." The Invocation is a separate concept because the same Run can be re-triggered (a tool result, a regenerate request); each trigger is one Invocation.
 
@@ -60,9 +60,9 @@ Both sides of a Run expose the same read-model, so the same accessor means the s
 - `runId`: the Run's identifier. Known synchronously on the agent; on the client it is empty until the agent's run-start is observed (await `clientRun.started` first).
 - `status`: the lifecycle status, one of `'active'`, `'suspended'`, `'complete'`, `'cancelled'`, or `'error'`, read live off the [conversation tree](/docs/ai-transport/concepts/conversation-tree).
 - `error`: the terminal error, present exactly when `status` is `'error'`.
-- `messages`: the Run's whole turn, the triggering input message followed by its streamed output. This is the unit to persist; see [database hydration](/docs/ai-transport/features/database-hydration).
+- `messages`: all of the Run's messages, its triggering input followed by its streamed output (across any suspend and resume). This is the unit to persist; see [database hydration](/docs/ai-transport/features/database-hydration).
 
-Each side then adds its own verbs. The client's `ClientRun` adds `started` and `cancel()`; the agent's `AgentRun` adds `located` (resolves once the triggering input folds into the tree) and the lifecycle methods `start()`, `pipe()`, `suspend()`, and `end()`.
+Each side then adds its own verbs. The client's `ClientRun` adds `started` and `cancel()`; the agent's `AgentRun` adds `located` (resolves once the triggering input has been observed on the channel) and the lifecycle methods `start()`, `pipe()`, `suspend()`, and `end()`.
 
 ## Trigger a Run <a id="trigger"/>
 
diff --git a/src/pages/docs/ai-transport/features/chain-of-thought.mdx b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
index a72c8620c4..059967b469 100644
--- a/src/pages/docs/ai-transport/features/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
@@ -109,4 +109,4 @@ The `node.message.parts` array stays available after the turn ends. Hide or coll
 
 - [Token streaming](/docs/ai-transport/features/token-streaming): how text tokens are streamed and accumulated.
 - [Tool calling](/docs/ai-transport/features/tool-calling): another multi-part stream type within a turn.
-- [Codec API](/docs/ai-transport/api/javascript/codec): reference for the codec that multiplexes reasoning and text streams.
+- [Codec API](/docs/ai-transport/api/javascript/core/codec): reference for the codec that multiplexes reasoning and text streams.
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
index fdff32067f..e86d1a8bf4 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
@@ -74,5 +74,5 @@ If you need direct access to the conversation tree (branch navigation, split-pan
 
 - [Get started with Vercel AI SDK](/docs/ai-transport/getting-started/vercel-ai-sdk): build a working app.
 - [Vercel AI SDK Core](/docs/ai-transport/frameworks/vercel-ai-sdk-core): the server-side integration that pairs with this page.
-- [Vercel integration API reference](/docs/ai-transport/api/javascript/vercel): the full API surface for the Vercel integration.
+- [Vercel integration API reference](/docs/ai-transport/api/javascript/vercel/chat-transport): the full API surface for the Vercel integration.
 - [Conversation branching](/docs/ai-transport/features/branching): one of the capabilities `useMessageSync` brings to `useChat`.
diff --git a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
index c092e71c24..b1a1732a5d 100644
--- a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
@@ -241,7 +241,7 @@ Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the sam
 5. Every client subscribed to the channel receives the streamed messages in real time. `useView` re-renders as the visible Run's projection updates.
 6. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the SDK rehydrates the view automatically.
 
-`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. The hook exposes `messages`, `hasOlder`, `loading`, `loadError`, `loadOlder`, `runOf`, `run`, `runs`, `branchSelection`, `send`, `regenerate`, and `edit`. Switch siblings through the `branchSelection` handle's `select`. It is the reactive mirror of the [`ClientView` interface](/docs/ai-transport/api/javascript/core/client-session#view).
+`useView` subscribes to the conversation tree and returns the visible messages along the currently selected branch. The hook exposes `messages`, `hasOlder`, `loading`, `loadError`, `loadOlder`, `runOf`, `run`, `runs`, `branchSelection`, `send`, `regenerate`, and `edit`. Switch siblings through the `branchSelection` handle's `select`. It is the reactive mirror of the [`ClientView` interface](/docs/ai-transport/api/javascript/core/client-session#properties).
 
 ## Explore next <a id="next"/>
 
diff --git a/src/pages/docs/ai-transport/internals/transport-patterns.mdx b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
index e3ef673a13..d5174881d5 100644
--- a/src/pages/docs/ai-transport/internals/transport-patterns.mdx
+++ b/src/pages/docs/ai-transport/internals/transport-patterns.mdx
@@ -119,7 +119,7 @@ Responsibilities:
 - Abort handling: if `run.abortSignal` fires, `pipe` cancels the reader and calls `encoder.cancel()`. This stops the LLM stream and publishes a final `updateMessage` with `status: 'cancelled'`.
 - Completion: when the stream ends naturally, `pipe` calls `encoder.close()` to flush any buffered appends and finalise the last stream.
 
-`pipe` returns a `StreamResult` with a `reason` field (`'complete'`, `'cancelled'`, or `'error'`) and an optional `error`. The caller passes the `reason` to `Run.end(reason)`. For runs that should pause awaiting input rather than end, use `Run.suspend()` instead of `Run.end(...)`.
+`pipe` returns a `StreamResult` with a `reason` field (`'complete'`, `'cancelled'`, or `'error'`) and an optional `error`. The caller passes the reason to `run.end({ reason })`. For runs that should pause awaiting input rather than end, use `run.suspend()` instead of `run.end(...)`.
 
 ## Channel continuity <a id="channel-continuity"/>
 
diff --git a/src/pages/docs/ai-transport/troubleshooting.mdx b/src/pages/docs/ai-transport/troubleshooting.mdx
index 520891431f..3f985548e0 100644
--- a/src/pages/docs/ai-transport/troubleshooting.mdx
+++ b/src/pages/docs/ai-transport/troubleshooting.mdx
@@ -65,7 +65,7 @@ In both cases the cause is the same: the channel namespace is not configured to
 
 **Confirm:**
 
-- Check the server logs around the affected Run. Did `run.end(reason)` execute? If the route handler threw between `run.pipe` and `run.end`, the Run never closes.
+- Check the server logs around the affected Run. Did `run.end({ reason })` execute? If the route handler threw between `run.pipe` and `run.end`, the Run never closes.
 - Inspect the channel in the Ably dashboard. The `ai-run-end` lifecycle message should appear after the streamed message's close event. If it is missing, the encoder did not publish it.
 
 **Fix:**
@@ -144,7 +144,7 @@ This is intentional. Branch selection is a per-view, per-device choice. Each dev
 **Fix:**
 
 - If branch selection should be shared (for example, a co-pilot where both devices must agree), synchronise the chosen leaf through your own application state, or by sending a message on the channel that the other client can react to and change its selections.
-- See [conversation branching](/docs/ai-transport/features/branching#branch-navigation) for how branch selection works.
+- See [conversation branching](/docs/ai-transport/features/branching#navigate) for how branch selection works.
 
 ## Reconnect loop <a id="reconnect-loop"/>
 

From ce248e538b7b4cd72c008f22ea116c008becc271 Mon Sep 17 00:00:00 2001
From: Mike Christensen <mike.christensen@ably.com>
Date: Wed, 1 Jul 2026 08:21:42 +0100
Subject: [PATCH 15/15] AI Transport docs: drain run.view before run.start()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

run.start() awaits run.located, and on a cold start the triggering input
only folds into the tree once the caller pages run.view — so draining after
start() can hang. Reorder every agent example to drain (loadOlder loop) and
build the conversation before calling run.start(), matching the SDK's own
v0.4.0 docs (streaming.md, database-hydration.md) and the AgentRun.start
contract. Affects agent-session, run-outcome, the agent-route feature pages,
both frameworks pages, and both getting-started guides. database-hydration
already used the correct loadUntil-then-start order.

Also: chain-of-thought used "turn" for the Run lifecycle unit (abort signal,
stream multiplexing, post-completion) inconsistently with the rest of the
page — align to "Run". Fix "client-side React hooks" casing on the Vercel
AI SDK UI page.

AIT-1090
---
 .../api/javascript/core/agent-session.mdx     | 34 +++++++++++--------
 .../api/javascript/vercel/run-outcome.mdx     |  7 ++--
 .../ai-transport/features/agent-presence.mdx  |  7 ++--
 .../docs/ai-transport/features/branching.mdx  |  7 ++--
 .../features/chain-of-thought.mdx             | 19 ++++++-----
 .../features/concurrent-turns.mdx             |  7 ++--
 .../features/push-notifications.mdx           |  7 ++--
 .../ai-transport/features/token-streaming.mdx |  7 ++--
 .../frameworks/vercel-ai-sdk-core.mdx         |  7 ++--
 .../frameworks/vercel-ai-sdk-ui.mdx           |  2 +-
 .../ai-transport/getting-started/core-sdk.mdx |  9 ++---
 .../getting-started/vercel-ai-sdk.mdx         |  9 ++---
 12 files changed, 68 insertions(+), 54 deletions(-)

diff --git a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
index 4ffcd5ae80..0a77dd367d 100644
--- a/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx
@@ -91,7 +91,7 @@ Subscribe to non-fatal session errors with [`on('error')`](#on) rather than a co
 
 <MethodSignature>{`connect(): Promise<void>`}</MethodSignature>
 
-Subscribe to the channel and implicitly attach. The subscribe is unfiltered so channel-history-replayed input events fold into the tree, where each run's input-event watcher can match its trigger. Idempotent: subsequent calls return the same promise. All `AgentRun` methods (`start`, `pipe`, `suspend`, `end`) throw `InvalidArgument` until `connect()` has been called.
+Attaches and subscribes to the channel backing the session. Idempotent: subsequent calls return the same promise. All `AgentRun` methods (`start`, `pipe`, `suspend`, `end`) throw `InvalidArgument` until `connect()` has been called.
 
 <Code>
 ```javascript
@@ -107,7 +107,7 @@ await session.connect();
 
 <MethodSignature>{`createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): AgentRun<TOutput, TProjection, TMessage>`}</MethodSignature>
 
-Create a new `AgentRun` from an `Invocation`. Returns synchronously and arms the run's input-event watcher (a passive pre-scan of the tree plus a listener for the trigger's arrival); it publishes nothing to the channel until [`AgentRun.start`](#run-start) is called. The run is registered for cancel routing immediately so early cancels fire the `abortSignal`.
+Create a new `AgentRun` for the input event named in the `Invocation`. Returns synchronously and publishes nothing to the channel until [`AgentRun.start`](#run-start) is called. The run is registered for cancel routing immediately so early cancels fire the `abortSignal`.
 
 <Code>
 ```javascript
@@ -167,11 +167,11 @@ The handle returned by [`createRun`](#create-run). It extends the shared `BaseRu
 | runId | The Run's unique identifier. Known synchronously on the agent (it mints the id for a fresh run, or reads it off the triggering input event for a continuation). | String |
 | status | The Run's lifecycle status, read live off the tree. | `RunStatus` |
 | error | The terminal error, present exactly when `status` is `'error'`. | `Ably.ErrorInfo` or Undefined |
-| messages | This Run's whole turn: its triggering input message followed by its own streamed output, deduplicated by `codecMessageId`. The unit to persist. See [Hydrate the conversation](#conversation-hydration). | `TMessage[]` |
+| messages | All of this Run's messages: its triggering input followed by its streamed output (across any suspend and resume), deduplicated by `codecMessageId`. The unit to persist. See [Hydrate the conversation](#conversation-hydration). | `TMessage[]` |
 | invocationId | The invocation id minted by the agent for this `createRun` call (one per HTTP request). Readable synchronously; the application returns it on the HTTP response. The agent stamps it on every event it publishes for this invocation. | String |
 | abortSignal | `AbortSignal` scoped to this Run. Fires when a cancel event arrives. | `AbortSignal` |
-| view | Read-only, leaf-pinned `View<TMessage>` of this Run's branch, from its triggering input back to the conversation root. Drain it with `loadOlder()` for ancestor context to feed the model. Empty until the trigger folds into the tree. See [Hydrate the conversation](#conversation-hydration). | `View<TMessage>` |
-| located | Resolves when this Run's triggering input folds into the tree (live or via a `view.loadOlder()` page). [`start`](#run-start) awaits it internally; await it directly only to read the trigger before deciding how to start. | `Promise<void>` |
+| view | A read-only `View<TMessage>` of the conversation branch this Run belongs to, from its triggering input back to the conversation root. Use it to reconstruct the conversation to feed the model. See [Hydrate the conversation](#conversation-hydration). | `View<TMessage>` |
+| located | Resolves once the Run's triggering input (named in its invocation) has been observed on the channel, whether through the live subscription or by paging history with `view.loadOlder()`. [`start`](#run-start) awaits it internally; await it directly only to read the trigger before deciding how to start. | `Promise<void>` |
 
 </Table>
 
@@ -179,9 +179,9 @@ The handle returned by [`createRun`](#create-run). It extends the shared `BaseRu
 
 <MethodSignature>{`start(): Promise<void>`}</MethodSignature>
 
-Await [`located`](#run) (the run's input-event watcher resolves the trigger, whether it arrives live or already sits in channel history), then read the trigger's wire headers and publish the opening lifecycle event (`ai-run-start`, or `ai-run-resume` for a continuation). Must be called before `pipe`, `suspend`, or `end`.
+Wait until the Run's triggering input has been observed on the channel (see [`located`](#run)), then publish the opening lifecycle event (`ai-run-start`, or `ai-run-resume` for a continuation). Must be called before `pipe`, `suspend`, or `end`.
 
-There is no built-in deadline: `start()` does not time out waiting for the trigger. It rejects only if the run is cancelled or the session is closed before the trigger folds in. Race it against your own timeout if you need one.
+There is no built-in deadline: `start()` does not time out waiting for the trigger. It rejects only if the run is cancelled or the session is closed before the trigger is observed. Race it against your own timeout if you need one.
 
 ### Pipe the response stream <a id="pipe"/>
 
@@ -333,20 +333,23 @@ const invocation = Invocation.fromJSON(data);
 
 Two accessors expose conversation content, at different scopes:
 
-- `run.messages` is this Run's own turn: its triggering input plus its streamed output. This is the unit to persist, not the value to feed the model in a multi-turn conversation.
+- `run.messages` is all of this Run's own messages: its triggering input plus its streamed output (across any suspend and resume). This is the unit to persist, not the value to feed the model in a multi-turn conversation.
 - `run.view` is a read-only, leaf-pinned `View` of this Run's full branch, from its triggering input back to the conversation root. This is the value to feed the model.
 
-To rebuild the prior conversation for the model, drain `run.view` with `loadOlder()` (the sole history driver) for as much ancestor context as you want, then read `getMessages()`:
+`run.view` includes an ancestor turn only once its run has completed. An ancestor that is still active, suspended, cancelled, or errored is omitted, along with the input it replied to, so a dangling tool call from a concurrent or interrupted turn can't invalidate the prompt. The current run is always included, and an omitted ancestor reappears once it completes.
+
+To rebuild the prior conversation for the model, drain `run.view` with `loadOlder()` for as much ancestor context as you want, then read `getMessages()`:
 
 <Code>
 ```javascript
-await run.start();
-
-// Drain the branch back to the root for full context.
+// Rebuild the conversation from run.view before run.start(): draining pages in
+// this run's triggering input (otherwise run.start() awaits it arriving live).
 while (run.view.hasOlder()) {
   await run.view.loadOlder();
 }
 const conversation = run.view.getMessages().map(({ message }) => message);
+
+await run.start();
 ```
 </Code>
 
@@ -384,14 +387,15 @@ export async function POST(req: Request) {
   const run = session.createRun(invocation, { signal: req.signal });
 
   try {
-    await run.start();
-
-    // Drain the run's branch back to the root for the model context.
+    // Rebuild the conversation from run.view before run.start(): draining pages
+    // in this run's triggering input (otherwise run.start() awaits it live).
     while (run.view.hasOlder()) {
       await run.view.loadOlder();
     }
     const conversation = run.view.getMessages().map(({ message }) => message);
 
+    await run.start();
+
     const llmStream = await callMyLLM(conversation);
     const result = await run.pipe(llmStream);
     await run.end({ reason: result.reason });
diff --git a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
index f596861f03..5d7bd5d4b5 100644
--- a/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
+++ b/src/pages/docs/ai-transport/api/javascript/vercel/run-outcome.mdx
@@ -106,14 +106,15 @@ export async function POST(req: Request) {
   const run = session.createRun(invocation, { signal: req.signal });
 
   try {
-    await run.start();
-
-    // Rebuild the prior conversation from run.view to feed the model.
+    // Rebuild the conversation from run.view before run.start(): draining pages
+    // in this run's triggering input (otherwise run.start() awaits it live).
     while (run.view.hasOlder()) {
       await run.view.loadOlder();
     }
     const conversation = run.view.getMessages().map(({ message }) => message);
 
+    await run.start();
+
     const result = streamText({
       model: openai('gpt-4'),
       messages: conversation,
diff --git a/src/pages/docs/ai-transport/features/agent-presence.mdx b/src/pages/docs/ai-transport/features/agent-presence.mdx
index b9878aefad..771211ab1e 100644
--- a/src/pages/docs/ai-transport/features/agent-presence.mdx
+++ b/src/pages/docs/ai-transport/features/agent-presence.mdx
@@ -32,14 +32,15 @@ app.post('/api/chat', async (req, res) => {
   // Enter presence so every connected client sees what the agent is doing.
   await session.presence.enter({ status: 'thinking' });
 
-  await run.start();
-
-  // Drain run.view for the prior conversation to feed the model.
+  // Rebuild the conversation from run.view before run.start(): draining pages in
+  // this run's triggering input (otherwise run.start() awaits it arriving live).
   while (run.view.hasOlder()) {
     await run.view.loadOlder();
   }
   const conversation = run.view.getMessages().map(({ message }) => message);
 
+  await run.start();
+
   const result = streamText({
     model: openai('gpt-4o'),
     messages: conversation,
diff --git a/src/pages/docs/ai-transport/features/branching.mdx b/src/pages/docs/ai-transport/features/branching.mdx
index 0701fae4ab..f86dce5151 100644
--- a/src/pages/docs/ai-transport/features/branching.mdx
+++ b/src/pages/docs/ai-transport/features/branching.mdx
@@ -122,14 +122,15 @@ const invocation = Invocation.fromJSON(await req.json());
 const run = session.createRun(invocation, { signal: req.signal });
 
 try {
-  await run.start();
-
-  // Drain run.view along this branch back to the root.
+  // Rebuild the conversation from run.view before run.start(): draining pages in
+  // this run's triggering input (otherwise run.start() awaits it arriving live).
   while (run.view.hasOlder()) {
     await run.view.loadOlder();
   }
   const conversation = run.view.getMessages().map(({ message }) => message);
 
+  await run.start();
+
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
     messages: conversation,
diff --git a/src/pages/docs/ai-transport/features/chain-of-thought.mdx b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
index 059967b469..78d627f54a 100644
--- a/src/pages/docs/ai-transport/features/chain-of-thought.mdx
+++ b/src/pages/docs/ai-transport/features/chain-of-thought.mdx
@@ -2,12 +2,12 @@
 title: "Chain of thought"
 meta_description: "Stream reasoning and thinking content alongside responses with Ably AI Transport. Display chain-of-thought in real time."
 meta_keywords: "chain of thought, reasoning, thinking, AI Transport, Ably, streaming reasoning"
-intro: "Your users see the agent's reasoning as it streams, side by side with the response. AI Transport multiplexes reasoning and text streams within the same turn."
+intro: "Your users see the agent's reasoning as it streams, side by side with the response. AI Transport multiplexes reasoning and text streams within the same Run."
 redirect_from:
   - /docs/ai-transport/messaging/chain-of-thought
 ---
 
-Chain of thought streams reasoning content alongside the main response text. The codec supports multiple stream types within a single turn. Text and reasoning are delivered as separate streams that render independently in the UI.
+Chain of thought streams reasoning content alongside the main response text. The codec supports multiple stream types within a single Run. Text and reasoning are delivered as separate streams that render independently in the UI.
 
 ![Diagram showing reasoning and response tokens streaming as parallel parts within the same Run](../../../../images/content/diagrams/ait-chain-of-thought.png)
 
@@ -25,14 +25,15 @@ app.post('/api/chat', async (req, res) => {
   await session.connect();
   const run = session.createRun(invocation, { signal: req.signal });
 
-  await run.start();
-
-  // Drain run.view for the prior conversation to feed the model.
+  // Rebuild the conversation from run.view before run.start(): draining pages in
+  // this run's triggering input (otherwise run.start() awaits it arriving live).
   while (run.view.hasOlder()) {
     await run.view.loadOlder();
   }
   const conversation = run.view.getMessages().map(({ message }) => message);
 
+  await run.start();
+
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
     messages: conversation,
@@ -95,18 +96,18 @@ Yes. Reasoning is a separate part type. Filter it out at the render layer. The c
 
 ### Does cancelling cut off reasoning too? <a id="faq-cancel"/>
 
-Yes. Both the reasoning and text streams share the turn's abort signal.
+Yes. Both the reasoning and text streams share the Run's abort signal.
 
 ### Are reasoning tokens charged the same as text? <a id="faq-pricing"/>
 
 Yes. The channel does not distinguish between part types for billing. The cost depends on the published message count after rollup.
 
-### How do I render reasoning differently after the turn finishes? <a id="faq-post-render"/>
+### How do I render reasoning differently after the Run finishes? <a id="faq-post-render"/>
 
-The `node.message.parts` array stays available after the turn ends. Hide or collapse reasoning when the streaming flag flips to false.
+The `node.message.parts` array stays available after the Run ends. Hide or collapse reasoning when the streaming flag flips to false.
 
 ## Related features <a id="related"/>
 
 - [Token streaming](/docs/ai-transport/features/token-streaming): how text tokens are streamed and accumulated.
-- [Tool calling](/docs/ai-transport/features/tool-calling): another multi-part stream type within a turn.
+- [Tool calling](/docs/ai-transport/features/tool-calling): another multi-part stream type within a Run.
 - [Codec API](/docs/ai-transport/api/javascript/core/codec): reference for the codec that multiplexes reasoning and text streams.
diff --git a/src/pages/docs/ai-transport/features/concurrent-turns.mdx b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
index 21814ffb88..a642eef77a 100644
--- a/src/pages/docs/ai-transport/features/concurrent-turns.mdx
+++ b/src/pages/docs/ai-transport/features/concurrent-turns.mdx
@@ -44,14 +44,15 @@ app.post('/api/chat', async (req, res) => {
   await session.connect();
   const run = session.createRun(invocation, { signal: req.signal });
 
-  await run.start();
-
-  // Drain run.view for the prior conversation to feed the model.
+  // Rebuild the conversation from run.view before run.start(): draining pages in
+  // this run's triggering input (otherwise run.start() awaits it arriving live).
   while (run.view.hasOlder()) {
     await run.view.loadOlder();
   }
   const conversation = run.view.getMessages().map(({ message }) => message);
 
+  await run.start();
+
   const result = streamText({
     model: anthropic('claude-sonnet-4-20250514'),
     messages: conversation,
diff --git a/src/pages/docs/ai-transport/features/push-notifications.mdx b/src/pages/docs/ai-transport/features/push-notifications.mdx
index 445c365ce7..95846dc347 100644
--- a/src/pages/docs/ai-transport/features/push-notifications.mdx
+++ b/src/pages/docs/ai-transport/features/push-notifications.mdx
@@ -42,14 +42,15 @@ app.post('/api/chat', async (req, res) => {
   await session.connect()
   const run = session.createRun(invocation, { signal: req.signal })
 
-  await run.start()
-
-  // Drain run.view for the prior conversation to feed the model.
+  // Rebuild the conversation from run.view before run.start(): draining pages in
+  // this run's triggering input (otherwise run.start() awaits it arriving live).
   while (run.view.hasOlder()) {
     await run.view.loadOlder()
   }
   const conversation = run.view.getMessages().map(({ message }) => message)
 
+  await run.start()
+
   const result = streamText({
     model: openai('gpt-4o'),
     messages: conversation,
diff --git a/src/pages/docs/ai-transport/features/token-streaming.mdx b/src/pages/docs/ai-transport/features/token-streaming.mdx
index efd9c86753..85dcbe4e8e 100644
--- a/src/pages/docs/ai-transport/features/token-streaming.mdx
+++ b/src/pages/docs/ai-transport/features/token-streaming.mdx
@@ -83,14 +83,15 @@ const session = createAgentSession({ client: ably, channelName: invocation.sessi
 await session.connect();
 const run = session.createRun(invocation, { signal: req.signal });
 
-await run.start();
-
-// Drain run.view for the prior conversation to feed the model.
+// Rebuild the conversation from run.view before run.start(): draining pages in
+// this run's triggering input (otherwise run.start() awaits it arriving live).
 while (run.view.hasOlder()) {
   await run.view.loadOlder();
 }
 const conversation = run.view.getMessages().map(({ message }) => message);
 
+await run.start();
+
 const result = streamText({
   model: anthropic('claude-sonnet-4-20250514'),
   messages: conversation,
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
index 933a9d0a91..5fe54f17e5 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-core.mdx
@@ -78,14 +78,15 @@ export async function POST(req) {
   const run = session.createRun(invocation, { signal: req.signal });
 
   after(async () => {
-    await run.start();
-
-    // Drain run.view for the prior conversation to feed the model.
+    // Rebuild the conversation from run.view before run.start(): draining pages
+    // in this run's triggering input (otherwise run.start() awaits it live).
     while (run.view.hasOlder()) {
       await run.view.loadOlder();
     }
     const conversation = run.view.getMessages().map(({ message }) => message);
 
+    await run.start();
+
     const result = streamText({
       model: anthropic('claude-sonnet-4-20250514'),
       messages: await convertToModelMessages(conversation),
diff --git a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
index e86d1a8bf4..138e207682 100644
--- a/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
+++ b/src/pages/docs/ai-transport/frameworks/vercel-ai-sdk-ui.mdx
@@ -2,7 +2,7 @@
 title: "Vercel AI SDK UI"
 meta_description: "How Ably AI Transport integrates with Vercel AI SDK UI (@ai-sdk/react) to add durable sessions and multi-device sync to useChat."
 meta_keywords: "AI Transport, Vercel AI SDK UI, useChat, ChatTransport, durable sessions, React, multi-device"
-intro: "Vercel AI SDK UI gives you client side react hooks like useChat for building chat interfaces. AI Transport plugs into useChat as a ChatTransport, so the same UI gets durable sessions, multi-device sync, and bidirectional control."
+intro: "Vercel AI SDK UI gives you client-side React hooks like useChat for building chat interfaces. AI Transport plugs into useChat as a ChatTransport, so the same UI gets durable sessions, multi-device sync, and bidirectional control."
 redirect_from:
   - /docs/ai-transport/framework-guides/vercel-ai-sdk
 ---
diff --git a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
index b1a1732a5d..ec1ba78388 100644
--- a/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/core-sdk.mdx
@@ -76,14 +76,15 @@ export async function POST(req) {
 
   after(async () => {
     try {
-      await run.start();
-
-      // Drain run.view for the prior conversation to feed the model.
+      // Rebuild the conversation from run.view before run.start(): draining pages
+      // in this run's triggering input (otherwise run.start() awaits it live).
       while (run.view.hasOlder()) {
         await run.view.loadOlder();
       }
       const conversation = run.view.getMessages().map(({ message }) => message);
 
+      await run.start();
+
       const result = streamText({
         model: anthropic('claude-sonnet-4-20250514'),
         system: 'You are a helpful assistant.',
@@ -236,7 +237,7 @@ Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the sam
 
 1. The user types a message. `view.send(...)` mints `inputEventId` and the message's `codecMessageId`, publishes the user input on the channel with those ids stamped under `extras.ai.transport`, and returns a `ClientRun` carrying the `inputCodecMessageId` the client owns synchronously. The SDK does not POST to your agent endpoint itself.
 2. Your client code calls `clientRun.toInvocation().toJSON()` to get an [`InvocationData`](/docs/ai-transport/concepts/invocations) body (`{ inputEventId, sessionName }`), and POSTs it to your agent endpoint.
-3. The agent endpoint receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a `Run` from the Invocation. `session.createRun(invocation)` mints a fresh `runId` (for a fresh run) and a fresh `invocationId`; the agent returns both on the response so callers can observe them. `Run.start()` waits for the trigger input event on the channel (rewind + live).
+3. The agent endpoint receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a `Run` from the Invocation. `session.createRun(invocation)` mints a fresh `runId` (for a fresh run) and a fresh `invocationId`; the agent returns both on the response so callers can observe them. `run.start()` waits until the trigger input event has been observed on the channel, whether paged in from history (as the drain above does) or arriving live.
 4. The agent streams the LLM response through `run.pipe(...)` to the channel. Every output carries `input-codec-message-id` so the client can correlate by an id it owned at send time.
 5. Every client subscribed to the channel receives the streamed messages in real time. `useView` re-renders as the visible Run's projection updates.
 6. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the SDK rehydrates the view automatically.
diff --git a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
index e04229a923..570453725d 100644
--- a/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
+++ b/src/pages/docs/ai-transport/getting-started/vercel-ai-sdk.mdx
@@ -81,14 +81,15 @@ export async function POST(req) {
 
   after(async () => {
     try {
-      await run.start();
-
-      // Drain run.view for the prior conversation to feed the model.
+      // Rebuild the conversation from run.view before run.start(): draining pages
+      // in this run's triggering input (otherwise run.start() awaits it live).
       while (run.view.hasOlder()) {
         await run.view.loadOlder();
       }
       const conversation = run.view.getMessages().map(({ message }) => message);
 
+      await run.start();
+
       const result = streamText({
         model: anthropic('claude-sonnet-4-20250514'),
         system: 'You are a helpful assistant.',
@@ -230,7 +231,7 @@ Run `npm run dev` and open `http://localhost:3000`. Open a second tab to the sam
 ## What is happening <a id="what-is-happening"/>
 
 1. `sendMessage({ text })` calls the `ChatTransport`'s `sendMessages`. Under the hood, the AI Transport client SDK mints `inputEventId` and the message's `codecMessageId`, stamps them on the channel publish under `extras.ai.transport`, and returns a `ClientRun` carrying the synchronous `inputCodecMessageId`. The `ChatTransport` then calls `clientRun.toInvocation().toJSON()` and POSTs the resulting `InvocationData` body (`{ inputEventId, sessionName }`) to your agent endpoint.
-2. The agent route receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a Run. `session.createRun(invocation)` mints `runId` (for a fresh run) and `invocationId` (one per HTTP request); the agent stamps both on every event it publishes and returns them on the response. `run.start()` waits for the trigger input event on the channel (rewind plus live).
+2. The agent route receives the POST, calls `Invocation.fromJSON`, creates an `AgentSession`, and starts a Run. `session.createRun(invocation)` mints `runId` (for a fresh run) and `invocationId` (one per HTTP request); the agent stamps both on every event it publishes and returns them on the response. `run.start()` waits until the trigger input event has been observed on the channel, whether paged in from history (as the drain above does) or arriving live.
 3. The agent streams the LLM response through `run.pipe()` to the channel. Outputs carry `input-codec-message-id` so the client can correlate by an id it owned at send time.
 4. Every client subscribed to the channel decodes the streamed messages in real time. `useChat` re-renders as `UIMessage` parts accumulate.
 5. If a client disconnects mid-stream, Ably resumes the subscription from the last serial on reconnect; the session rehydrates without losing tokens.