@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Assemble `useUIMessages` and `useThreadMessages` results by order across pages and streams (#193)
+- `useUIMessages` accepts `MessageDoc` pages from `listMessages` (#193)
+- Bound the context order-completion query by bytes (#193)
+- Require `convex@^1.32.0`, the first version with `maximumBytesRead` (#193)
+
 ## 0.7.5
 
 - Allow tool approvals to be handled atomically and more robust (#367)
 
@@ -24,29 +24,34 @@ example.
 ```ts
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
-import { listUIMessages } from "@convex-dev/agent";
+import { listMessages } from "@convex-dev/agent";
 import { components } from "./_generated/api";
 
 export const listThreadMessages = query({
   args: { threadId: v.string(), paginationOpts: paginationOptsValidator },
   handler: async (ctx, args) => {
     await authorizeThreadAccess(ctx, threadId);
 
-    const paginated = await listUIMessages(ctx, components.agent, args);
+    const paginated = await listMessages(ctx, components.agent, args);
 
     // Here you could filter out / modify the documents
     return paginated;
   },
 });
 ```
 
-Note: Above we used `listUIMessages`, which returns UIMessages, specifically the
-Agent extension that includes some extra fields like order, status, etc.
+Note: Above we used `listMessages`, which returns MessageDocs: one per stored
+message, with fields like order, stepOrder and status. The React hooks below
+take this query and assemble the documents into UIMessages on the client.
 UIMessages combine multiple MessageDocs into a single UIMessage when there are
 multiple tool calls followed by an assistant message, making it easy to build
 UIs that work with the various "parts" on the UIMessage.
 
-If you want to get MessageDocs, you can use `listMessages` instead.
+If you need UIMessages on the server, `listUIMessages` converts each page
+separately. Returning those pages to `useUIMessages` is still supported but
+legacy: a page boundary can fall inside one UIMessage, and a tool approval
+response whose tool call is on another page is lost. Return MessageDocs from
+`listMessages` instead.
 
 ## Showing messages in React
 
@@ -56,8 +61,14 @@ non-streaming example.
 
 ### `useUIMessages` hook
 
-The crux is to use the `useUIMessages` hook. For streaming, pass in
-`stream: true` to the hook.
+The crux is to use the `useUIMessages` hook with the query above. For streaming,
+pass in `stream: true` to the hook.
+
+Pagination can end a page partway through one UIMessage. The hook loads the
+rest of the oldest message before it settles (reporting `LoadingMore`), so
+`results` always start at a whole message, and may hold more rows than
+`initialNumItems`. Rows of older messages read along the way are shown on the
+next `loadMore`.
 
 ```tsx
 import { api } from "../convex/_generated/api";
@@ -80,7 +91,7 @@ function MyComponent({ threadId }: { threadId: string }) {
 ```
 
 Note: If you want to work with MessageDocs instead of UIMessages, you can use
-the older `useThreadMessages` hook instead. However, working with UIMessages
+the older `useThreadMessages` hook with the same query. However, working with UIMessages
 enables richer streaming capabilities, such as status on whether the agent is
 actively reasoning.
 
 
@@ -68,7 +68,7 @@ stream deltas. This is very similar to
 ```ts
 import { paginationOptsValidator } from "convex/server";
 // highlight-next-line
-import { vStreamArgs, listUIMessages, syncStreams } from "@convex-dev/agent";
+import { vStreamArgs, listMessages, syncStreams } from "@convex-dev/agent";
 import { components } from "./_generated/api";
 
 export const listThreadMessages = query({
@@ -83,7 +83,7 @@ export const listThreadMessages = query({
     await authorizeThreadAccess(ctx, threadId);
 
     // Fetches the regular non-streaming messages.
-    const paginated = await listUIMessages(ctx, components.agent, args);
+    const paginated = await listMessages(ctx, components.agent, args);
 
     // highlight-next-line
     const streams = await syncStreams(ctx, components.agent, args);
@@ -274,6 +274,8 @@ export const listStreams = query({
       // By default syncStreams only returns streaming messages. However, if
       // your messages aren't saved in the same transaction as the streaming
       // ends, you might want to include them here to avoid UI flashes.
+      // useUIMessages and useThreadMessages show a finished or aborted stream
+      // only where its order has no saved message at or after its start.
       includeStatuses: ["streaming", "aborted", "finished"],
     });
     return { streams };
 
@@ -154,7 +154,9 @@ const messages = await listMessages(ctx, components.agent, {
 });
 ```
 
-Or for the UIMessage type (easier for rendering UIs):
+Or for the UIMessage type (each page is converted on its own, so a UIMessage can
+be cut at a page boundary; for React, return MessageDocs and use
+`useUIMessages`):
 
 ```ts
 import { listUIMessages } from "@convex-dev/agent";
 
@@ -177,7 +177,10 @@ histories where tool calls lack results.
 ## Client-side flow
 
 On the client, use `useUIMessages` to detect pending approvals and show
-Approve/Deny buttons. Tool parts with `state === "approval-requested"` are
+Approve/Deny buttons. Its query should return MessageDocs from `listMessages`
+(see [retrieving messages](./messages.mdx#retrieving-messages)): with pages of
+`listUIMessages`, an approval response on a different page from its tool call
+is lost. Tool parts with `state === "approval-requested"` are
 waiting for a decision.
 
 ```tsx
 
@@ -8,7 +8,7 @@
 // 5. AI SDK automatically handles the approval: executes tool (if approved)
 //    or creates execution-denied result (if denied), then continues generation
 import { paginationOptsValidator } from "convex/server";
-import { listUIMessages, syncStreams, vStreamArgs } from "@convex-dev/agent";
+import { listMessages, syncStreams, vStreamArgs } from "@convex-dev/agent";
 import { components, internal } from "../_generated/api";
 import { internalAction, mutation, query } from "../_generated/server";
 import { v } from "convex/values";
@@ -135,7 +135,7 @@ export const listThreadMessages = query({
       threadId,
       streamArgs,
     });
-    const paginated = await listUIMessages(ctx, components.agent, args);
+    const paginated = await listMessages(ctx, components.agent, args);
     return { ...paginated, streams };
   },
 });
@@ -3,7 +3,7 @@ import {
   saveMessage,
   syncStreams,
   vStreamArgs,
-  listUIMessages,
+  listMessages,
 } from "@convex-dev/agent";
 import {
   action,
@@ -168,7 +168,7 @@ export const getMessages = query({
     streamArgs: vStreamArgs,
   },
   handler: async (ctx, args) => {
-    const messages = await listUIMessages(ctx, components.agent, {
+    const messages = await listMessages(ctx, components.agent, {
       threadId: args.threadId,
       paginationOpts: args.paginationOpts,
     });
 
@@ -2,7 +2,7 @@
 import { paginationOptsValidator } from "convex/server";
 import {
   createThread,
-  listUIMessages,
+  listMessages,
   syncStreams,
   vStreamArgs,
 } from "@convex-dev/agent";
@@ -99,7 +99,9 @@ export const listThreadMessages = query({
     // Here you could filter out / modify the stream of deltas / filter out
     // deltas.
 
-    const paginated = await listUIMessages(ctx, components.agent, args);
+    // MessageDocs, which useUIMessages assembles into UIMessages across
+    // pages and streams.
+    const paginated = await listMessages(ctx, components.agent, args);
 
     // Here you could filter out metadata that you don't want from any optional
     // fields on the messages.
 
@@ -48,8 +48,7 @@ function Story({ threadId, reset }: { threadId: string; reset: () => void }) {
     { threadId },
     { initialNumItems: 10, stream: true },
   );
-  // If you don't want to use UIMessages, you can use this hook:
-  // (note: you'll need to return MessageDoc from listThreadMessages)
+  // If you want the MessageDocs themselves, use this hook with the same query:
   /*
   const { results } = useThreadMessages(
     api.chat.streaming.listThreadMessages,