transport: replace MessageWithHeaders with ConversationNode

Eliminate the lossy MessageWithHeaders projection in favour of the
richer ConversationNode type on both read and write paths.

Read path: getMessagesWithHeaders() is replaced by getNodes(), which
returns ConversationNode[] directly from the conversation tree instead
of stripping fields into {message, headers?}.

Write path: Turn.addMessages() now accepts ConversationNode[] instead
of MessageWithHeaders[]. The server uses typed node fields (msgId,
parentId, forkOf) directly rather than generating UUIDs and overriding
via raw header strings. AddMessageOptions is simplified to just
clientId.

Consumers get typed msgId, parentId, forkOf, and non-optional headers
instead of digging into raw header strings — this also eliminates the
! non-null assertion that was in the demo code.

Tests add coverage for node parentId/forkOf flowing through server
transport headers.

Author: mschristensen

README.md

@@ -89,13 +89,13 @@ import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
 import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { ConversationNode } from '@ably/ai-transport';
 
 interface ChatRequestBody {
   turnId: string;
   clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
+  messages: ConversationNode<UIMessage>[];
+  history?: ConversationNode<UIMessage>[];
   id: string;
   forkOf?: string;
   parent?: string | null;

demo/vercel/react/use-chat/src/app/api/chat/route.ts

@@ -12,14 +12,14 @@ import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
 import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { ConversationNode } from '@ably/ai-transport';
 
 /** Shape of the POST body sent by the client transport. */
 interface ChatRequestBody {
   turnId: string;
   clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
+  messages: ConversationNode<UIMessage>[];
+  history?: ConversationNode<UIMessage>[];
   id: string;
   forkOf?: string;
   parent?: string | null;

demo/vercel/react/use-chat/src/app/chat.tsx

@@ -40,7 +40,7 @@ export function Chat({ chatId, clientId, historyLimit }: { chatId: string; clien
       <div className="flex flex-1 flex-col">
         <Header clientId={clientId} />
         <MessageList
-          messagesWithHeaders={transport.getMessagesWithHeaders()}
+          nodes={transport.getNodes()}
           hasNext={history.hasNext}
           loading={history.loading}
           onNext={() => history.next()}

demo/vercel/react/use-chat/src/app/components/message-list.tsx

@@ -2,30 +2,30 @@
 
 import { useRef, useEffect } from 'react';
 import type { UIMessage } from 'ai';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { ConversationNode } from '@ably/ai-transport';
 import { MessageBubble } from './message-bubble';
 
 interface MessageListProps {
-  messagesWithHeaders: MessageWithHeaders<UIMessage>[];
+  nodes: ConversationNode<UIMessage>[];
   hasNext: boolean;
   loading: boolean;
   onNext: () => void;
   onRegenerate: (messageId: string) => void;
 }
 
-export function MessageList({ messagesWithHeaders, hasNext, loading, onNext, onRegenerate }: MessageListProps) {
+export function MessageList({ nodes, hasNext, loading, onNext, onRegenerate }: MessageListProps) {
   const endRef = useRef<HTMLDivElement>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
   const prevLastIdRef = useRef<string | undefined>(undefined);
 
   useEffect(() => {
     const lastId =
-      messagesWithHeaders.length > 0 ? messagesWithHeaders[messagesWithHeaders.length - 1].message.id : undefined;
+      nodes.length > 0 ? nodes[nodes.length - 1].message.id : undefined;
     if (lastId && lastId !== prevLastIdRef.current) {
       prevLastIdRef.current = lastId;
       endRef.current?.scrollIntoView({ behavior: 'smooth' });
     }
-  }, [messagesWithHeaders]);
+  }, [nodes]);
 
   const handleScroll = () => {
     const el = scrollRef.current;
@@ -53,10 +53,10 @@ export function MessageList({ messagesWithHeaders, hasNext, loading, onNext, onR
         </div>
       )}
       {loading && <div className="text-center text-xs text-zinc-600 animate-pulse">Loading history...</div>}
-      {messagesWithHeaders.length === 0 && !loading && (
+      {nodes.length === 0 && !loading && (
         <p className="text-sm text-zinc-600 text-center mt-20">Send a message to start chatting.</p>
       )}
-      {messagesWithHeaders.map(({ message, headers }) => (
+      {nodes.map(({ message, headers }) => (
         <MessageBubble
           key={message.id}
           message={message}

demo/vercel/react/use-client-transport/src/app/api/chat/route.ts

@@ -12,14 +12,14 @@ import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
 import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { ConversationNode } from '@ably/ai-transport';
 
 /** Shape of the POST body sent by the client transport. */
 interface ChatRequestBody {
   turnId: string;
   clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
+  messages: ConversationNode<UIMessage>[];
+  history?: ConversationNode<UIMessage>[];
   id: string;
   forkOf?: string;
   parent?: string | null;

demo/vercel/react/use-client-transport/src/app/components/chat.tsx

@@ -51,7 +51,6 @@ export function Chat({ chatId, clientId, historyLimit }: ChatProps) {
       <div className="flex flex-1 flex-col">
         <Header clientId={clientId} />
         <MessageList
-          messagesWithHeaders={transport.getMessagesWithHeaders()}
           tree={tree}
           hasNext={history.hasNext}
           loading={history.loading}

demo/vercel/react/use-client-transport/src/app/components/message-list.tsx

@@ -2,12 +2,10 @@
 
 import { useRef, useEffect } from 'react';
 import type { UIMessage } from 'ai';
-import type { MessageWithHeaders } from '@ably/ai-transport';
 import type { ConversationTreeHandle } from '@ably/ai-transport/react';
 import { MessageBubble } from './message-bubble';
 
 interface MessageListProps {
-  messagesWithHeaders: MessageWithHeaders<UIMessage>[];
   tree: ConversationTreeHandle<UIMessage>;
   hasNext: boolean;
   loading: boolean;
@@ -17,7 +15,6 @@ interface MessageListProps {
 }
 
 export function MessageList({
-  messagesWithHeaders,
   tree,
   hasNext,
   loading,
@@ -29,15 +26,17 @@ export function MessageList({
   const scrollRef = useRef<HTMLDivElement>(null);
   const prevLastIdRef = useRef<string | undefined>(undefined);
 
+  const { nodes } = tree;
+
   // Auto-scroll to bottom only when the last message changes
   useEffect(() => {
     const lastId =
-      messagesWithHeaders.length > 0 ? messagesWithHeaders[messagesWithHeaders.length - 1].message.id : undefined;
+      nodes.length > 0 ? nodes[nodes.length - 1].message.id : undefined;
     if (lastId && lastId !== prevLastIdRef.current) {
       prevLastIdRef.current = lastId;
       endRef.current?.scrollIntoView({ behavior: 'smooth' });
     }
-  }, [messagesWithHeaders]);
+  }, [nodes]);
 
   const handleScroll = () => {
     const el = scrollRef.current;
@@ -65,25 +64,22 @@ export function MessageList({
         </div>
       )}
       {loading && <div className="text-center text-xs text-zinc-600 animate-pulse">Loading history...</div>}
-      {messagesWithHeaders.length === 0 && !loading && (
+      {nodes.length === 0 && !loading && (
         <p className="text-sm text-zinc-600 text-center mt-20">Send a message to start chatting.</p>
       )}
-      {messagesWithHeaders.map(({ message, headers }) => {
-        const msgId = headers!['x-ably-msg-id'];
-        return (
-          <MessageBubble
-            key={message.id}
-            message={message}
-            headers={headers}
-            hasSiblings={tree.hasSiblings(msgId)}
-            siblings={tree.getSiblings(msgId)}
-            selectedIndex={tree.getSelectedIndex(msgId)}
-            onSelectSibling={(index) => tree.selectSibling(msgId, index)}
-            onRegenerate={message.role === 'assistant' ? () => onRegenerate(msgId) : undefined}
-            onEdit={message.role === 'user' ? (text) => onEdit(msgId, text) : undefined}
-          />
-        );
-      })}
+      {nodes.map((node) => (
+        <MessageBubble
+          key={node.message.id}
+          message={node.message}
+          headers={node.headers}
+          hasSiblings={tree.hasSiblings(node.msgId)}
+          siblings={tree.getSiblings(node.msgId)}
+          selectedIndex={tree.getSelectedIndex(node.msgId)}
+          onSelectSibling={(index) => tree.selectSibling(node.msgId, index)}
+          onRegenerate={node.message.role === 'assistant' ? () => onRegenerate(node.msgId) : undefined}
+          onEdit={node.message.role === 'user' ? (text) => onEdit(node.msgId, text) : undefined}
+        />
+      ))}
       <div ref={endRef} />
     </div>
   );

docs/features/branching.md

@@ -74,10 +74,9 @@ const tree = useConversationTree(transport);
 // tree.getSelectedIndex(nodeId) - which sibling is currently selected
 // tree.selectSibling(nodeId, index) - switch to a different sibling
 //
-// nodeId is the x-ably-msg-id for each message - iterate getMessagesWithHeaders()
-// to get messages paired with their headers:
-//   transport.getMessagesWithHeaders().map(({ message: msg, headers }) => {
-//     const nodeId = headers?.['x-ably-msg-id'] ?? msg.id;
+// nodeId is the msgId on each ConversationNode — iterate getNodes():
+//   transport.getNodes().map((node) => {
+//     const nodeId = node.msgId;
 //   });
 ```
 

docs/get-started/vercel-use-chat.md

@@ -94,13 +94,13 @@ import type { UIMessage } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import Ably from 'ably';
 import { createServerTransport } from '@ably/ai-transport/vercel';
-import type { MessageWithHeaders } from '@ably/ai-transport';
+import type { ConversationNode } from '@ably/ai-transport';
 
 interface ChatRequestBody {
   turnId: string;
   clientId: string;
-  messages: MessageWithHeaders<UIMessage>[];
-  history?: MessageWithHeaders<UIMessage>[];
+  messages: ConversationNode<UIMessage>[];
+  history?: ConversationNode<UIMessage>[];
   id: string;
   forkOf?: string;
   parent?: string | null;

docs/get-started/vercel-use-client-transport.md

@@ -29,12 +29,6 @@ import { UIMessageCodec } from '@ably/ai-transport/vercel';
 import type { UIMessage } from 'ai';
 import { useState } from 'react';
 
-// Resolve the x-ably-msg-id for a message. Tree methods and regenerate/edit
-// use x-ably-msg-id as the key, not UIMessage.id.
-function treeMsgId(headers: Record<string, string> | undefined, msg: UIMessage): string {
-  return headers?.['x-ably-msg-id'] ?? msg.id;
-}
-
 function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string }) {
   const { channel } = useChannel({ channelName: chatId });
   const [input, setInput] = useState('');
@@ -58,7 +52,7 @@ function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string })
 
   const isStreaming = activeTurns.size > 0;
 
-  const messagesWithHeaders = transport.getMessagesWithHeaders();
+  const nodes = transport.getNodes();
 
   const handleSend = () => {
     const text = input.trim();
@@ -83,32 +77,29 @@ function ChatInner({ chatId, clientId }: { chatId: string; clientId?: string })
         </button>
       )}
 
-      {/* Message list with headers for tree navigation */}
-      {messagesWithHeaders.map(({ message: msg, headers }) => {
-        const nodeId = treeMsgId(headers, msg);
-        return (
-          <div key={msg.id}>
-            <strong>{msg.role}:</strong>
-            {msg.parts.map((part, i) => (
-              part.type === 'text' ? <span key={i}>{part.text}</span> : null
-            ))}
-
-            {/* Branch navigation */}
-            {tree.hasSiblings(nodeId) && (
-              <span>
-                {tree.getSelectedIndex(nodeId) + 1} / {tree.getSiblings(nodeId).length}
-                <button onClick={() => tree.selectSibling(nodeId, tree.getSelectedIndex(nodeId) - 1)}>prev</button>
-                <button onClick={() => tree.selectSibling(nodeId, tree.getSelectedIndex(nodeId) + 1)}>next</button>
-              </span>
-            )}
-
-            {/* Regenerate assistant messages */}
-            {msg.role === 'assistant' && (
-              <button onClick={() => regenerate(nodeId)}>Regenerate</button>
-            )}
-          </div>
-        );
-      })}
+      {/* Message list — each node has a typed msgId for tree navigation */}
+      {nodes.map((node) => (
+        <div key={node.message.id}>
+          <strong>{node.message.role}:</strong>
+          {node.message.parts.map((part, i) => (
+            part.type === 'text' ? <span key={i}>{part.text}</span> : null
+          ))}
+
+          {/* Branch navigation */}
+          {tree.hasSiblings(node.msgId) && (
+            <span>
+              {tree.getSelectedIndex(node.msgId) + 1} / {tree.getSiblings(node.msgId).length}
+              <button onClick={() => tree.selectSibling(node.msgId, tree.getSelectedIndex(node.msgId) - 1)}>prev</button>
+              <button onClick={() => tree.selectSibling(node.msgId, tree.getSelectedIndex(node.msgId) + 1)}>next</button>
+            </span>
+          )}
+
+          {/* Regenerate assistant messages */}
+          {node.message.role === 'assistant' && (
+            <button onClick={() => regenerate(node.msgId)}>Regenerate</button>
+          )}
+        </div>
+      ))}
 
       {/* Input */}
       <form onSubmit={(e) => { e.preventDefault(); handleSend(); }}>