AI Transport docs: drain run.view before run.start()

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

Author: mschristensen

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,21 +167,21 @@ 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>
 
 ### Start the run <a id="run-start"/>
 
 <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 });

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,

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,

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,

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.

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,

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,

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,

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),

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
 ---