@convex-dev/agent 0.6.0 → 0.6.2

package/dist/react/useStreamingUIMessages.js

@@ -0,0 +1,92 @@
+"use client";
+import { useMemo, useState, useEffect } from "react";
+import {} from "ai";
+import {} from "../UIMessages.js";
+import { blankUIMessage, getParts, updateFromUIMessageChunks, deriveUIMessagesFromTextStreamParts, } from "../deltas.js";
+import { useDeltaStreams } from "./useDeltaStreams.js";
+// Polyfill structuredClone to support readUIMessageStream on ReactNative
+if (!("structuredClone" in globalThis)) {
+    void import("@ungap/structured-clone").then(({ default: structuredClone }) => (globalThis.structuredClone = structuredClone));
+}
+/**
+ * A hook that fetches streaming messages from a thread and converts them to UIMessages
+ * using AI SDK's readUIMessageStream.
+ * This ONLY returns streaming UIMessages. To get both full and streaming messages,
+ * use `useUIMessages`.
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts, streamArgs }` and
+ * return a `streams` object returned from `agent.syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @returns The streaming UIMessages.
+ */
+export function useStreamingUIMessages(query, args, options) {
+    const [messageState, setMessageState] = useState({});
+    const streams = useDeltaStreams(query, args, options);
+    const threadId = args === "skip" ? undefined : args.threadId;
+    useEffect(() => {
+        if (!streams)
+            return;
+        // return if there are no new deltas beyond the cursors
+        let noNewDeltas = true;
+        for (const stream of streams) {
+            const lastDelta = stream.deltas.at(-1);
+            const cursor = messageState[stream.streamMessage.streamId]?.cursor;
+            if (!cursor) {
+                noNewDeltas = false;
+                break;
+            }
+            if (lastDelta && lastDelta.start >= cursor) {
+                noNewDeltas = false;
+                break;
+            }
+        }
+        if (noNewDeltas) {
+            return;
+        }
+        const abortController = new AbortController();
+        void (async () => {
+            const newMessageState = Object.fromEntries(await Promise.all(streams.map(async ({ deltas, streamMessage }) => {
+                const { parts, cursor } = getParts(deltas, 0);
+                if (streamMessage.format === "UIMessageChunk") {
+                    // Unfortunately this can't handle resuming from a UIMessage and
+                    // adding more chunks, so we re-create it from scratch each time.
+                    const uiMessage = await updateFromUIMessageChunks(blankUIMessage(streamMessage, threadId), parts);
+                    return [
+                        streamMessage.streamId,
+                        {
+                            uiMessage,
+                            cursor,
+                        },
+                    ];
+                }
+                else {
+                    const [uiMessages] = deriveUIMessagesFromTextStreamParts(threadId, [streamMessage], [], deltas);
+                    return [
+                        streamMessage.streamId,
+                        {
+                            uiMessage: uiMessages[0],
+                            cursor,
+                        },
+                    ];
+                }
+            })));
+            if (abortController.signal.aborted)
+                return;
+            setMessageState(newMessageState);
+        })();
+        return () => {
+            abortController.abort();
+        };
+    }, [messageState, streams, threadId]);
+    return useMemo(() => {
+        if (!streams)
+            return undefined;
+        return streams
+            .map(({ streamMessage }) => messageState[streamMessage.streamId]?.uiMessage)
+            .filter((uiMessage) => uiMessage !== undefined);
+    }, [messageState, streams]);
+}
+//# sourceMappingURL=useStreamingUIMessages.js.map

package/dist/react/useStreamingUIMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStreamingUIMessages.js","sourceRoot":"","sources":["../../src/react/useStreamingUIMessages.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AACb,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,EAAuD,MAAM,IAAI,CAAC;AAEzE,OAAO,EAAkB,MAAM,kBAAkB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,QAAQ,EACR,yBAAyB,EACzB,mCAAmC,GACpC,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,yEAAyE;AACzE,IAAI,CAAC,CAAC,iBAAiB,IAAI,UAAU,CAAC,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,yBAAgC,CAAC,CAAC,IAAI,CAChD,CAAC,EAAE,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,CAC/B,CAAC,UAAU,CAAC,eAAe,GAAG,eAAe,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAMpC,KAAY,EACZ,IAAqC,EACrC,OAGC;IAGD,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAQ9C,EAAE,CAAC,CAAC;IAEN,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAE7D,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,uDAAuD;QACvD,IAAI,WAAW,GAAG,IAAI,CAAC;QACvB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACvC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;YACnE,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,WAAW,GAAG,KAAK,CAAC;gBACpB,MAAM;YACR,CAAC;YACD,IAAI,SAAS,IAAI,SAAS,CAAC,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3C,WAAW,GAAG,KAAK,CAAC;gBACpB,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO;QACT,CAAC;QACD,MAAM,eAAe,GAAG,IAAI,eAAe,EAAE,CAAC;QAC9C,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,eAAe,GAMjB,MAAM,CAAC,WAAW,CACpB,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE;gBAC9C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAiB,MAAM,EAAE,CAAC,CAAC,CAAC;gBAC9D,IAAI,aAAa,CAAC,MAAM,KAAK,gBAAgB,EAAE,CAAC;oBAC9C,gEAAgE;oBAChE,iEAAiE;oBACjE,MAAM,SAAS,GAAG,MAAM,yBAAyB,CAC/C,cAAc,CAAC,aAAa,EAAE,QAAQ,CAAC,EACvC,KAAK,CACN,CAAC;oBACF,OAAO;wBACL,aAAa,CAAC,QAAQ;wBACtB;4BACE,SAAS;4BACT,MAAM;yBACP;qBACF,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,CAAC,UAAU,CAAC,GAAG,mCAAmC,CACtD,QAAQ,EACR,CAAC,aAAa,CAAC,EACf,EAAE,EACF,MAAM,CACP,CAAC;oBACF,OAAO;wBACL,aAAa,CAAC,QAAQ;wBACtB;4BACE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;4BACxB,MAAM;yBACP;qBACF,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CACH,CACF,CAAC;YACF,IAAI,eAAe,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC3C,eAAe,CAAC,eAAe,CAAC,CAAC;QACnC,CAAC,CAAC,EAAE,CAAC;QACL,OAAO,GAAG,EAAE;YACV,eAAe,CAAC,KAAK,EAAE,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEtC,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAC/B,OAAO,OAAO;aACX,GAAG,CACF,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,SAAS,CACvE;aACA,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC;IACpD,CAAC,EAAE,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;AAC9B,CAAC"}

package/dist/react/useThreadMessages.d.ts

@@ -0,0 +1,104 @@
+import { type BetterOmit, type ErrorMessage, type Expand } from "convex-helpers";
+import { type UsePaginatedQueryResult } from "convex/react";
+import type { FunctionArgs, FunctionReference, PaginationOptions, PaginationResult } from "convex/server";
+import type { SyncStreamsReturnValue } from "../client/types.js";
+import type { Message, MessageDoc, MessageStatus, StreamArgs } from "../validators.js";
+import type { StreamQueryArgs, StreamQuery } from "./types.js";
+export type MessageDocLike = {
+    order: number;
+    stepOrder: number;
+    status: MessageStatus | "streaming";
+    message?: Message;
+};
+export type ThreadMessagesQuery<Args = unknown, M extends MessageDocLike = MessageDocLike> = FunctionReference<"query", "public", {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    /**
+     * If { stream: true } is passed, it will also query for stream deltas.
+     * In order for this to work, the query must take as an argument streamArgs.
+     */
+    streamArgs?: StreamArgs;
+} & Args, PaginationResult<M> & {
+    streams?: SyncStreamsReturnValue;
+}>;
+export type ThreadMessagesArgs<Query extends ThreadMessagesQuery<unknown, MessageDocLike>> = Query extends ThreadMessagesQuery<unknown, MessageDocLike> ? Expand<BetterOmit<FunctionArgs<Query>, "paginationOpts" | "streamArgs">> : never;
+export type ThreadMessagesResult<Query extends ThreadMessagesQuery<unknown, MessageDocLike>> = Query extends ThreadMessagesQuery<unknown, infer M> ? M : never;
+/**
+ * A hook that fetches messages from a thread.
+ *
+ * This hook is a wrapper around `usePaginatedQuery` and `useStreamingThreadMessages`.
+ * It will fetch both full messages and streaming messages, and merge them together.
+ *
+ * The query must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects that extend `MessageDoc`.
+ *
+ * For streaming, it should look like this:
+ * ```ts
+ * export const listThreadMessages = query({
+ *   args: {
+ *     threadId: v.string(),
+ *     paginationOpts: paginationOptsValidator,
+ *     streamArgs: vStreamArgs,
+ *     ... other arguments you want
+ *   },
+ *   handler: async (ctx, args) => {
+ *     // await authorizeThreadAccess(ctx, threadId);
+ *     // NOTE: listMessages returns MessageDocs, not UIMessages.
+ *     const paginated = await listMessages(ctx, components.agent, args);
+ *     const streams = await syncStreams(ctx, components.agent, args);
+ *     // Here you could filter out / modify the documents & stream deltas.
+ *     return { ...paginated, streams };
+ *   },
+ * });
+ * ```
+ *
+ * Then the hook can be used like this:
+ * ```ts
+ * const { results, status, loadMore } = useThreadMessages(
+ *   api.myModule.listThreadMessages,
+ *   { threadId },
+ *   { initialNumItems: 10, stream: true }
+ * );
+ * ```
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects that extend `MessageDoc`.
+ * To support streaming, it must also take in `streamArgs: vStreamArgs` and
+ * return a `streams` object returned from `agent.syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @param options The options for the query. Similar to usePaginatedQuery.
+ * To enable streaming, pass `stream: true`.
+ * @returns The messages. If stream is true, it will return a list of messages
+ *   that includes both full messages and streaming messages.
+ */
+export declare function useThreadMessages<Query extends ThreadMessagesQuery<any, any>>(query: Query, args: ThreadMessagesArgs<Query> | "skip", options: {
+    initialNumItems: number;
+    stream?: Query extends StreamQuery ? boolean : ErrorMessage<"To enable streaming, your query must take in streamArgs: vStreamArgs and return a streams object returned from syncStreams. See docs.">;
+}): UsePaginatedQueryResult<ThreadMessagesResult<Query> & {
+    streaming: boolean;
+    key: string;
+}>;
+/**
+ * @deprecated FYI `useStreamingUIMessages` is likely better for you.
+ * A hook that fetches streaming messages from a thread.
+ * This ONLY returns streaming messages. To get both, use `useThreadMessages`.
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts, streamArgs }` and
+ * return a `streams` object returned from `agent.syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @returns The streaming messages.
+ */
+export declare function useStreamingThreadMessages<Query extends StreamQuery<any>>(query: Query, args: (StreamQueryArgs<Query> & {
+    /** @deprecated Pass startOrder to the next argument (third argument). */
+    startOrder?: number;
+}) | "skip", options?: {
+    startOrder?: number;
+    skipStreamIds?: string[];
+}): Array<MessageDoc> | undefined;
+//# sourceMappingURL=useThreadMessages.d.ts.map

package/dist/react/useThreadMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThreadMessages.d.ts","sourceRoot":"","sources":["../../src/react/useThreadMessages.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAGjE,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,aAAa,EACb,UAAU,EACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG/D,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAC7B,IAAI,GAAG,OAAO,EACd,CAAC,SAAS,cAAc,GAAG,cAAc,IACvC,iBAAiB,CACnB,OAAO,EACP,QAAQ,EACR;IACE,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,iBAAiB,CAAC;IAClC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,EACR,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,sBAAsB,CAAA;CAAE,CAC3D,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAC5B,KAAK,SAAS,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,IAE1D,KAAK,SAAS,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,GACtD,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,YAAY,CAAC,CAAC,GACxE,KAAK,CAAC;AAEZ,MAAM,MAAM,oBAAoB,CAC9B,KAAK,SAAS,mBAAmB,CAAC,OAAO,EAAE,cAAc,CAAC,IACxD,KAAK,SAAS,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,SAAS,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,EAC3E,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,kBAAkB,CAAC,KAAK,CAAC,GAAG,MAAM,EACxC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,KAAK,SAAS,WAAW,GAC9B,OAAO,GACP,YAAY,CAAC,uIAAuI,CAAC,CAAC;CAC3J,GACA,uBAAuB,CACxB,oBAAoB,CAAC,KAAK,CAAC,GAAG;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAClE,CA4EA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,SAAS,WAAW,CAAC,GAAG,CAAC,EACvE,KAAK,EAAE,KAAK,EACZ,IAAI,EACA,CAAC,eAAe,CAAC,KAAK,CAAC,GAAG;IACxB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,GACF,MAAM,EACV,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,GACA,KAAK,CAAC,UAAU,CAAC,GAAG,SAAS,CA6B/B"}

package/dist/react/useThreadMessages.js

@@ -0,0 +1,148 @@
+"use client";
+import { omit, } from "convex-helpers";
+import { usePaginatedQuery } from "convex-helpers/react";
+import {} from "convex/react";
+import { useMemo, useState, useEffect, useRef } from "react";
+import { sorted } from "../shared.js";
+import { fromUIMessages } from "../UIMessages.js";
+import { useStreamingUIMessages } from "./useStreamingUIMessages.js";
+/**
+ * A hook that fetches messages from a thread.
+ *
+ * This hook is a wrapper around `usePaginatedQuery` and `useStreamingThreadMessages`.
+ * It will fetch both full messages and streaming messages, and merge them together.
+ *
+ * The query must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects that extend `MessageDoc`.
+ *
+ * For streaming, it should look like this:
+ * ```ts
+ * export const listThreadMessages = query({
+ *   args: {
+ *     threadId: v.string(),
+ *     paginationOpts: paginationOptsValidator,
+ *     streamArgs: vStreamArgs,
+ *     ... other arguments you want
+ *   },
+ *   handler: async (ctx, args) => {
+ *     // await authorizeThreadAccess(ctx, threadId);
+ *     // NOTE: listMessages returns MessageDocs, not UIMessages.
+ *     const paginated = await listMessages(ctx, components.agent, args);
+ *     const streams = await syncStreams(ctx, components.agent, args);
+ *     // Here you could filter out / modify the documents & stream deltas.
+ *     return { ...paginated, streams };
+ *   },
+ * });
+ * ```
+ *
+ * Then the hook can be used like this:
+ * ```ts
+ * const { results, status, loadMore } = useThreadMessages(
+ *   api.myModule.listThreadMessages,
+ *   { threadId },
+ *   { initialNumItems: 10, stream: true }
+ * );
+ * ```
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects that extend `MessageDoc`.
+ * To support streaming, it must also take in `streamArgs: vStreamArgs` and
+ * return a `streams` object returned from `agent.syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @param options The options for the query. Similar to usePaginatedQuery.
+ * To enable streaming, pass `stream: true`.
+ * @returns The messages. If stream is true, it will return a list of messages
+ *   that includes both full messages and streaming messages.
+ */
+export function useThreadMessages(query, args, options) {
+    // These are full messages
+    const paginated = usePaginatedQuery(query, args, { initialNumItems: options.initialNumItems });
+    let startOrder = paginated.results.at(-1)?.order ?? 0;
+    for (let i = paginated.results.length - 1; i >= 0; i--) {
+        const m = paginated.results[i];
+        if (!m.streaming && m.status === "pending") {
+            // round down to the nearest 10 for some cache benefits
+            startOrder = m.order - (m.order % 10);
+            break;
+        }
+    }
+    // These are streaming messages that will not include full messages.
+    const streamMessages = useStreamingThreadMessages(query, !options.stream ||
+        args === "skip" ||
+        paginated.status === "LoadingFirstPage"
+        ? "skip"
+        : { ...args, paginationOpts: { cursor: null, numItems: 0 } }, { startOrder });
+    const threadId = args === "skip" ? undefined : args.threadId;
+    const merged = useMemo(() => {
+        const streamListMessages = streamMessages?.map((m) => ({
+            ...m,
+            streaming: !m.status || m.status === "pending",
+        })) ?? [];
+        return {
+            ...paginated,
+            results: sorted(paginated.results
+                .map((m) => ({ ...m, streaming: false }))
+                // Note: this is intentionally after paginated results.
+                .concat(streamListMessages)).reduce((msgs, msg) => {
+                msg.key = `${threadId}-${msg.order}-${msg.stepOrder}`;
+                const last = msgs.at(-1);
+                if (!last) {
+                    return [msg];
+                }
+                if (last.order !== msg.order || last.stepOrder !== msg.stepOrder) {
+                    return [...msgs, msg];
+                }
+                if (last.status === "pending" &&
+                    (msg.streaming || msg.status !== "pending")) {
+                    // Let's prefer a streaming or finalized message over a pending
+                    // one.
+                    return [...msgs.slice(0, -1), msg];
+                }
+                // skip the new one if the previous one (listed) was finalized
+                return msgs;
+            }, []),
+        };
+    }, [paginated, streamMessages, threadId]);
+    return merged;
+}
+/**
+ * @deprecated FYI `useStreamingUIMessages` is likely better for you.
+ * A hook that fetches streaming messages from a thread.
+ * This ONLY returns streaming messages. To get both, use `useThreadMessages`.
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts, streamArgs }` and
+ * return a `streams` object returned from `agent.syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @returns The streaming messages.
+ */
+export function useStreamingThreadMessages(query, args, options) {
+    const queryArgs = args === "skip"
+        ? args
+        : omit(args, ["startOrder"]);
+    const startOrder = args === "skip" ? undefined : (args.startOrder ?? undefined);
+    const queryOptions = { startOrder, ...options };
+    const uiMessages = useStreamingUIMessages(query, queryArgs, queryOptions);
+    const [messages, setMessages] = useState();
+    const generationRef = useRef(0);
+    useEffect(() => {
+        if (args === "skip" || !uiMessages) {
+            setMessages(undefined);
+            return;
+        }
+        const currentGeneration = ++generationRef.current;
+        (async () => {
+            const nested = await Promise.all(uiMessages.map((m) => fromUIMessages([m], { threadId: args.threadId })));
+            if (generationRef.current === currentGeneration) {
+                setMessages(nested.flat());
+            }
+        })();
+    }, [uiMessages, args === "skip" ? undefined : args.threadId]);
+    return messages;
+}
+//# sourceMappingURL=useThreadMessages.js.map

package/dist/react/useThreadMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useThreadMessages.js","sourceRoot":"","sources":["../../src/react/useThreadMessages.ts"],"names":[],"mappings":"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"}

package/dist/react/useUIMessages.d.ts

@@ -0,0 +1,96 @@
+import { type BetterOmit, type ErrorMessage, type Expand } from "convex-helpers";
+import { type UsePaginatedQueryResult } from "convex/react";
+import type { FunctionArgs, FunctionReference, PaginationOptions, PaginationResult } from "convex/server";
+import type { SyncStreamsReturnValue } from "../client/types.js";
+import type { StreamArgs } from "../validators.js";
+import type { StreamQuery } from "./types.js";
+import { type UIMessage, type UIStatus } from "../UIMessages.js";
+export type UIMessageLike = {
+    order: number;
+    stepOrder: number;
+    status: UIStatus;
+    parts: UIMessage["parts"];
+    role: UIMessage["role"];
+};
+export type UIMessagesQuery<Args = unknown, M extends UIMessageLike = UIMessageLike> = FunctionReference<"query", "public", {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    /**
+     * If { stream: true } is passed, it will also query for stream deltas.
+     * In order for this to work, the query must take as an argument streamArgs.
+     */
+    streamArgs?: StreamArgs;
+} & Args, PaginationResult<M> & {
+    streams?: SyncStreamsReturnValue;
+}>;
+export type UIMessagesQueryArgs<Query extends UIMessagesQuery<unknown, UIMessageLike>> = Query extends UIMessagesQuery<unknown, UIMessageLike> ? Expand<BetterOmit<FunctionArgs<Query>, "paginationOpts" | "streamArgs">> : never;
+export type UIMessagesQueryResult<Query extends UIMessagesQuery<unknown, UIMessageLike>> = Query extends UIMessagesQuery<unknown, infer M> ? M : never;
+/**
+ * A hook that fetches UIMessages from a thread.
+ *
+ * It's similar to useThreadMessages, for endpoints that return UIMessages.
+ * The streaming messages are materialized as UIMessages. The rest are passed
+ * through from the query.
+ *
+ * This hook is a wrapper around `usePaginatedQuery` and `useStreamingUIMessages`.
+ * It will fetch both full messages and streaming messages, and merge them together.
+ *
+ * The query must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects similar to UIMessage:
+ *
+ * For streaming, it should look like this:
+ * ```ts
+ * export const listThreadMessages = query({
+ *   args: {
+ *     threadId: v.string(),
+ *     paginationOpts: paginationOptsValidator,
+ *     streamArgs: vStreamArgs,
+ *     ... other arguments you want
+ *   },
+ *   handler: async (ctx, args) => {
+ *     // await authorizeThreadAccess(ctx, threadId);
+ *     // NOTE: listUIMessages returns UIMessages, not MessageDocs.
+ *     const paginated = await listUIMessages(ctx, components.agent, args);
+ *     const streams = await syncStreams(ctx, components.agent, args);
+ *     // Here you could filter out / modify the documents & stream deltas.
+ *     return { ...paginated, streams };
+ *   },
+ * });
+ * ```
+ *
+ * Then the hook can be used like this:
+ * ```ts
+ * const { results, status, loadMore } = useUIMessages(
+ *   api.myModule.listThreadMessages,
+ *   { threadId },
+ *   { initialNumItems: 10, stream: true }
+ * );
+ * ```
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects similar to UIMessage:
+ * Required fields: (role, parts, status, order, stepOrder).
+ * To support streaming, it must also take in `streamArgs: vStreamArgs` and
+ * return a `streams` object returned from `syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @param options The options for the query. Similar to usePaginatedQuery.
+ * To enable streaming, pass `stream: true`.
+ * @returns The messages. If stream is true, it will return a list of messages
+ *   that includes both full messages and streaming messages.
+ *   The streaming messages are materialized as UIMessages. The rest are passed
+ *   through from the query.
+ */
+export declare function useUIMessages<Query extends UIMessagesQuery<any, any>>(query: Query, args: UIMessagesQueryArgs<Query> | "skip", options: {
+    initialNumItems: number;
+    stream?: Query extends StreamQuery ? boolean : ErrorMessage<"To enable streaming, your query must take in streamArgs: vStreamArgs and return a streams object returned from syncStreams. See docs.">;
+    skipStreamIds?: string[];
+}): UsePaginatedQueryResult<UIMessagesQueryResult<Query>>;
+export declare function dedupeMessages<M extends {
+    order: number;
+    stepOrder: number;
+    status: UIStatus;
+}>(messages: M[], streamMessages: M[]): M[];
+//# sourceMappingURL=useUIMessages.d.ts.map

package/dist/react/useUIMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUIMessages.d.ts","sourceRoot":"","sources":["../../src/react/useUIMessages.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EACL,KAAK,SAAS,EACd,KAAK,QAAQ,EAEd,MAAM,kBAAkB,CAAC;AAI1B,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,eAAe,CACzB,IAAI,GAAG,OAAO,EACd,CAAC,SAAS,aAAa,GAAG,aAAa,IACrC,iBAAiB,CACnB,OAAO,EACP,QAAQ,EACR;IACE,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,iBAAiB,CAAC;IAClC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,EACR,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,sBAAsB,CAAA;CAAE,CAC3D,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAC7B,KAAK,SAAS,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,IAErD,KAAK,SAAS,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,GACjD,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,YAAY,CAAC,CAAC,GACxE,KAAK,CAAC;AAEZ,MAAM,MAAM,qBAAqB,CAC/B,KAAK,SAAS,eAAe,CAAC,OAAO,EAAE,aAAa,CAAC,IACnD,KAAK,SAAS,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,aAAa,CAAC,KAAK,SAAS,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EACnE,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,mBAAmB,CAAC,KAAK,CAAC,GAAG,MAAM,EACzC,OAAO,EAAE;IACP,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,KAAK,SAAS,WAAW,GAC9B,OAAO,GACP,YAAY,CAAC,uIAAuI,CAAC,CAAC;IAC1J,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,GACA,uBAAuB,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAgCvD;AAED,wBAAgB,cAAc,CAC5B,CAAC,SAAS;IACR,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC;CAClB,EACD,QAAQ,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAoBzC"}

package/dist/react/useUIMessages.js

@@ -0,0 +1,108 @@
+"use client";
+import {} from "convex-helpers";
+import { usePaginatedQuery } from "convex-helpers/react";
+import {} from "convex/react";
+import { useMemo } from "react";
+import { combineUIMessages, } from "../UIMessages.js";
+import { sorted } from "../shared.js";
+import { useStreamingUIMessages } from "./useStreamingUIMessages.js";
+/**
+ * A hook that fetches UIMessages from a thread.
+ *
+ * It's similar to useThreadMessages, for endpoints that return UIMessages.
+ * The streaming messages are materialized as UIMessages. The rest are passed
+ * through from the query.
+ *
+ * This hook is a wrapper around `usePaginatedQuery` and `useStreamingUIMessages`.
+ * It will fetch both full messages and streaming messages, and merge them together.
+ *
+ * The query must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects similar to UIMessage:
+ *
+ * For streaming, it should look like this:
+ * ```ts
+ * export const listThreadMessages = query({
+ *   args: {
+ *     threadId: v.string(),
+ *     paginationOpts: paginationOptsValidator,
+ *     streamArgs: vStreamArgs,
+ *     ... other arguments you want
+ *   },
+ *   handler: async (ctx, args) => {
+ *     // await authorizeThreadAccess(ctx, threadId);
+ *     // NOTE: listUIMessages returns UIMessages, not MessageDocs.
+ *     const paginated = await listUIMessages(ctx, components.agent, args);
+ *     const streams = await syncStreams(ctx, components.agent, args);
+ *     // Here you could filter out / modify the documents & stream deltas.
+ *     return { ...paginated, streams };
+ *   },
+ * });
+ * ```
+ *
+ * Then the hook can be used like this:
+ * ```ts
+ * const { results, status, loadMore } = useUIMessages(
+ *   api.myModule.listThreadMessages,
+ *   { threadId },
+ *   { initialNumItems: 10, stream: true }
+ * );
+ * ```
+ *
+ * @param query The query to use to fetch messages.
+ * It must take as arguments `{ threadId, paginationOpts }` and return a
+ * pagination result of objects similar to UIMessage:
+ * Required fields: (role, parts, status, order, stepOrder).
+ * To support streaming, it must also take in `streamArgs: vStreamArgs` and
+ * return a `streams` object returned from `syncStreams`.
+ * @param args The arguments to pass to the query other than `paginationOpts`
+ * and `streamArgs`. So `{ threadId }` at minimum, plus any other arguments that
+ * you want to pass to the query.
+ * @param options The options for the query. Similar to usePaginatedQuery.
+ * To enable streaming, pass `stream: true`.
+ * @returns The messages. If stream is true, it will return a list of messages
+ *   that includes both full messages and streaming messages.
+ *   The streaming messages are materialized as UIMessages. The rest are passed
+ *   through from the query.
+ */
+export function useUIMessages(query, args, options) {
+    // These are full messages
+    const paginated = usePaginatedQuery(query, args, { initialNumItems: options.initialNumItems });
+    const startOrder = paginated.results.length
+        ? Math.min(...paginated.results.map((m) => m.order))
+        : 0;
+    // These are streaming messages that will not include full messages.
+    const streamMessages = useStreamingUIMessages(query, !options.stream ||
+        args === "skip" ||
+        paginated.status === "LoadingFirstPage"
+        ? "skip"
+        : { ...args, paginationOpts: { cursor: null, numItems: 0 } }, { startOrder, skipStreamIds: options.skipStreamIds });
+    const merged = useMemo(() => {
+        // Messages may have been split by pagination. Re-combine them here.
+        const combined = combineUIMessages(sorted(paginated.results));
+        return {
+            ...paginated,
+            results: dedupeMessages(combined, streamMessages ?? []),
+        };
+    }, [paginated, streamMessages]);
+    return merged;
+}
+export function dedupeMessages(messages, streamMessages) {
+    return sorted(messages.concat(streamMessages)).reduce((msgs, msg) => {
+        const last = msgs.at(-1);
+        if (!last) {
+            return [msg];
+        }
+        if (last.order !== msg.order || last.stepOrder !== msg.stepOrder) {
+            return [...msgs, msg];
+        }
+        if ((last.status === "pending" || last.status === "streaming") &&
+            msg.status !== "pending") {
+            // Let's prefer a streaming or finalized message over a pending
+            // one.
+            return [...msgs.slice(0, -1), msg];
+        }
+        // skip the new one if the previous one (listed) was finalized
+        return msgs;
+    }, []);
+}
+//# sourceMappingURL=useUIMessages.js.map

package/dist/react/useUIMessages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUIMessages.js","sourceRoot":"","sources":["../../src/react/useUIMessages.ts"],"names":[],"mappings":"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"}

package/dist/shared.d.ts

@@ -0,0 +1,26 @@
+import type { FilePart, ImagePart, ReasoningPart, ToolCallPart, ToolResultPart, ToolApprovalRequest } from "@ai-sdk/provider-utils";
+import type { ModelMessage, TextPart, UIDataTypes, UIMessagePart, UITools } from "ai";
+import type { Message, MessageContentParts } from "./validators.js";
+export declare const DEFAULT_RECENT_MESSAGES = 100;
+export declare function isTool(message: Message | ModelMessage): boolean;
+export declare function extractText(message: Message | ModelMessage): string | undefined;
+export declare function joinText(parts: (UIMessagePart<UIDataTypes, UITools> | TextPart | ImagePart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart | MessageContentParts | ToolApprovalRequest)[]): string;
+export declare function extractReasoning(message: Message | ModelMessage): string | undefined;
+export declare const DEFAULT_MESSAGE_RANGE: {
+    before: number;
+    after: number;
+};
+export declare function sorted<T extends {
+    order: number;
+    stepOrder: number;
+}>(messages: T[], order?: "asc" | "desc"): T[];
+export type ModelOrMetadata = string | ({
+    provider: string;
+} & ({
+    modelId: string;
+} | {
+    model: string;
+}));
+export declare function getModelName(embeddingModel: ModelOrMetadata): string;
+export declare function getProviderName(embeddingModel: ModelOrMetadata): string;
+//# sourceMappingURL=shared.d.ts.map

package/dist/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../src/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,aAAa,EACb,YAAY,EACZ,cAAc,EACd,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,aAAa,EACb,OAAO,EACR,MAAM,IAAI,CAAC;AACZ,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEpE,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,WAOrD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,sBAkB1D;AAED,wBAAgB,QAAQ,CACtB,KAAK,EAAE,CACH,aAAa,CAAC,WAAW,EAAE,OAAO,CAAC,GACnC,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,aAAa,GACb,YAAY,GACZ,cAAc,GACd,mBAAmB,GACnB,mBAAmB,CACtB,EAAE,UAOJ;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,sBAQ/D;AAED,eAAO,MAAM,qBAAqB;;;CAA0B,CAAC;AAE7D,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACnE,QAAQ,EAAE,CAAC,EAAE,EACb,KAAK,GAAE,KAAK,GAAG,MAAc,GAC5B,CAAC,EAAE,CAML;AAED,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAEvE,wBAAgB,YAAY,CAAC,cAAc,EAAE,eAAe,GAAG,MAAM,CAUpE;AAED,wBAAgB,eAAe,CAAC,cAAc,EAAE,eAAe,GAAG,MAAM,CAKvE"}