@convex-dev/agent 0.5.0-alpha.1 → 0.6.0-alpha.1

package/dist/react/useDeltaStreams.js

@@ -0,0 +1,106 @@
+"use client";
+import { sorted } from "../shared.js";
+import { useQuery } from "convex/react";
+import { useState } from "react";
+import { assert } from "convex-helpers";
+export function useDeltaStreams(query, args, options) {
+    // We hold onto and modify state directly to avoid re-running unnecessarily.
+    const [state] = useState({
+        startOrder: options?.startOrder ?? 0,
+        deltaStreams: undefined,
+        threadId: args === "skip" ? undefined : args.threadId,
+    });
+    const [cursors, setCursors] = useState({});
+    if (args !== "skip" && state.threadId !== args.threadId) {
+        state.threadId = args.threadId;
+        state.deltaStreams = undefined;
+        state.startOrder = options?.startOrder ?? 0;
+        setCursors({});
+    }
+    if (state.deltaStreams?.length ||
+        (options?.startOrder && options.startOrder < state.startOrder)) {
+        const cacheFriendlyStartOrder = options?.startOrder
+            ? // round down to the nearest 10 for some cache benefits
+                options.startOrder - (options.startOrder % 10)
+            : 0;
+        if (cacheFriendlyStartOrder !== state.startOrder) {
+            state.startOrder = cacheFriendlyStartOrder;
+        }
+    }
+    // Get all the active streams
+    const streamList = useQuery(query, args === "skip"
+        ? args
+        : {
+            ...args,
+            streamArgs: {
+                kind: "list",
+                startOrder: state.startOrder,
+            },
+        });
+    const streamMessages = args === "skip"
+        ? undefined
+        : !streamList
+            ? state.deltaStreams?.map(({ streamMessage }) => streamMessage)
+            : sorted(streamList.streams.messages.filter(({ streamId, order }) => !options?.skipStreamIds?.includes(streamId) &&
+                (!options?.startOrder || order >= options.startOrder)));
+    // When no active streams remain, clear the stale state so we stop
+    // returning old streaming UIMessages.
+    if (streamMessages !== undefined && streamMessages.length === 0) {
+        state.deltaStreams = undefined;
+    }
+    // Get the deltas for all the active streams, if any.
+    const cursorQuery = useQuery(query, args === "skip" || !streamMessages?.length
+        ? "skip"
+        : {
+            ...args,
+            streamArgs: {
+                kind: "deltas",
+                cursors: streamMessages.map(({ streamId }) => ({
+                    streamId,
+                    cursor: cursors[streamId] ?? 0,
+                })),
+            },
+        });
+    const newDeltas = cursorQuery?.streams.deltas;
+    if (newDeltas?.length && streamMessages) {
+        const newDeltasByStreamId = new Map();
+        for (const delta of newDeltas) {
+            const oldCursor = cursors[delta.streamId];
+            if (oldCursor && delta.start < oldCursor)
+                continue;
+            const existing = newDeltasByStreamId.get(delta.streamId);
+            if (existing) {
+                const previousEnd = existing.at(-1).end;
+                assert(previousEnd === delta.start, `Gap found in deltas for ${delta.streamId} jumping to ${delta.start} from ${previousEnd}`);
+                existing.push(delta);
+            }
+            else {
+                assert(!oldCursor || oldCursor === delta.start, `Gap found - first delta after ${oldCursor} is ${delta.start} for stream ${delta.streamId}`);
+                newDeltasByStreamId.set(delta.streamId, [delta]);
+            }
+        }
+        const newCursors = {};
+        for (const { streamId } of streamMessages) {
+            const cursor = newDeltasByStreamId.get(streamId)?.at(-1)?.end ?? cursors[streamId];
+            if (cursor !== undefined) {
+                newCursors[streamId] = cursor;
+            }
+        }
+        setCursors(newCursors);
+        // we defensively create a new object so object identity matches contents
+        state.deltaStreams = streamMessages.map((streamMessage) => {
+            const streamId = streamMessage.streamId;
+            const old = state.deltaStreams?.find((ds) => ds.streamMessage.streamId === streamId);
+            const newDeltas = newDeltasByStreamId.get(streamId);
+            if (!newDeltas && streamMessage === old?.streamMessage) {
+                return old;
+            }
+            return {
+                streamMessage,
+                deltas: [...(old?.deltas ?? []), ...(newDeltas ?? [])],
+            };
+        });
+    }
+    return state.deltaStreams;
+}
+//# sourceMappingURL=useDeltaStreams.js.map

package/dist/react/useDeltaStreams.js.map

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

package/dist/react/useSmoothText.d.ts

@@ -1,14 +1,4 @@
-/**
- * A hook that smoothly displays text as it is streamed.
- *
- * @param text The text to display. Pass in the full text each time.
- * @param charsPerSec The number of characters to display per second.
- * @returns A tuple of the visible text and the state of the smooth text,
- * including the current cursor position and whether it's still streaming.
- * This allows you to decide if it's too far behind and you want to adjust
- * the charsPerSec or just prefer the full text.
- */
-export declare function useSmoothText(text: string, { charsPerSec, startStreaming, }?: {
+export type SmoothTextOptions = {
     /**
      * The number of characters to display per second.
      */
@@ -19,7 +9,18 @@ export declare function useSmoothText(text: string, { charsPerSec, startStreamin
      * This will start streaming the first value it sees.
      */
     startStreaming?: boolean;
-}): [string, {
+};
+/**
+ * A hook that smoothly displays text as it is streamed.
+ *
+ * @param text The text to display. Pass in the full text each time.
+ * @param charsPerSec The number of characters to display per second.
+ * @returns A tuple of the visible text and the state of the smooth text,
+ * including the current cursor position and whether it's still streaming.
+ * This allows you to decide if it's too far behind and you want to adjust
+ * the charsPerSec or just prefer the full text.
+ */
+export declare function useSmoothText(text: string, { charsPerSec, startStreaming, }?: SmoothTextOptions): [string, {
     cursor: number;
     isStreaming: boolean;
 }];

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

@@ -1 +1 @@
-{"version":3,"file":"useSmoothText.d.ts","sourceRoot":"","sources":["../../src/react/useSmoothText.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,EACE,WAAiB,EACjB,cAAsB,GACvB,GAAE;IACD;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACrB,GACL,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAsDpD"}
+{"version":3,"file":"useSmoothText.d.ts","sourceRoot":"","sources":["../../src/react/useSmoothText.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AACF;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,EACE,WAAmC,EACnC,cAAsB,GACvB,GAAE,iBAAsB,GACxB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAwEpD"}

package/dist/react/useSmoothText.js

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 const FPS = 20;
 const MS_PER_FRAME = 1000 / FPS;
-const MAX_TIME_JUMP_MS = 250;
+const INITIAL_CHARS_PER_SEC = 128;
 /**
  * A hook that smoothly displays text as it is streamed.
  *
@@ -12,34 +12,51 @@ const MAX_TIME_JUMP_MS = 250;
  * This allows you to decide if it's too far behind and you want to adjust
  * the charsPerSec or just prefer the full text.
  */
-export function useSmoothText(text, { charsPerSec = 256, startStreaming = false, } = {}) {
-    const [visibleText, setVisibleText] = useState(startStreaming ? "" : text);
+export function useSmoothText(text, { charsPerSec = INITIAL_CHARS_PER_SEC, startStreaming = false, } = {}) {
+    const [visibleText, setVisibleText] = useState(startStreaming ? "" : text || "");
     const smoothState = useRef({
-        tick: Date.now() + (visibleText.length * 1000) / charsPerSec,
+        tick: Date.now(),
         cursor: visibleText.length,
-        start: Date.now(),
-        initialLength: visibleText.length,
+        lastUpdate: Date.now(),
+        lastUpdateLength: text.length,
         charsPerMs: charsPerSec / 1000,
+        initial: true,
     });
     const isStreaming = smoothState.current.cursor < text.length;
     useEffect(() => {
         if (!isStreaming) {
             return;
         }
-        const latestCharsPerMs = (text.length - smoothState.current.initialLength) /
-            (Date.now() - smoothState.current.start);
-        // Smooth out the charsPerSec by averaging it with the previous value.
-        smoothState.current.charsPerMs = Math.min((2 * latestCharsPerMs + smoothState.current.charsPerMs) / 3, smoothState.current.charsPerMs * 2);
-        smoothState.current.tick = Math.max(smoothState.current.tick, Date.now() - 2 * MS_PER_FRAME);
+        if (smoothState.current.lastUpdateLength !== text.length) {
+            const timeSinceLastUpdate = Date.now() - smoothState.current.lastUpdate;
+            const latestCharsPerMs = (text.length - smoothState.current.lastUpdateLength) /
+                timeSinceLastUpdate;
+            // Is the rate increasing?
+            const rateError = latestCharsPerMs - smoothState.current.charsPerMs;
+            // Is our visible text falling behind what it could show?
+            const charLag = smoothState.current.lastUpdateLength - smoothState.current.cursor;
+            const lagRate = charLag / timeSinceLastUpdate;
+            const charsPerMs = latestCharsPerMs +
+                (smoothState.current.initial
+                    ? 0
+                    : Math.max(0, (rateError + lagRate) / 2));
+            smoothState.current.initial = false;
+            // Smooth out the charsPerSec by weighting it with the previous value.
+            smoothState.current.charsPerMs = Math.min((2 * charsPerMs + smoothState.current.charsPerMs) / 3, smoothState.current.charsPerMs * 2);
+        }
+        smoothState.current.tick = Math.max(smoothState.current.tick, Date.now() - MS_PER_FRAME);
+        smoothState.current.lastUpdate = Date.now();
+        smoothState.current.lastUpdateLength = text.length;
         function update() {
             if (smoothState.current.cursor >= text.length) {
                 return;
             }
             const now = Date.now();
-            const timeSinceLastUpdate = Math.min(MAX_TIME_JUMP_MS, now - smoothState.current.tick);
-            const chars = Math.floor(timeSinceLastUpdate * smoothState.current.charsPerMs);
-            smoothState.current.cursor = Math.min(smoothState.current.cursor + chars, text.length);
-            smoothState.current.tick = now;
+            const timeSinceLastUpdate = now - smoothState.current.tick;
+            const charsSinceLastUpdate = Math.floor(timeSinceLastUpdate * smoothState.current.charsPerMs);
+            const chars = Math.min(charsSinceLastUpdate, text.length - smoothState.current.cursor);
+            smoothState.current.cursor += chars;
+            smoothState.current.tick += chars / smoothState.current.charsPerMs;
             setVisibleText(text.slice(0, smoothState.current.cursor));
         }
         update();

package/dist/react/useSmoothText.js.map

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

package/dist/react/useStreamingUIMessages.d.ts

@@ -0,0 +1,22 @@
+import { type UIDataTypes, type UITools } from "ai";
+import type { StreamQuery, StreamQueryArgs } from "./types.js";
+import { type UIMessage } from "../UIMessages.js";
+/**
+ * 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 declare function useStreamingUIMessages<METADATA = unknown, DATA_PARTS extends UIDataTypes = UIDataTypes, TOOLS extends UITools = UITools, Query extends StreamQuery<any> = StreamQuery<object>>(query: Query, args: StreamQueryArgs<Query> | "skip", options?: {
+    startOrder?: number;
+    skipStreamIds?: string[];
+}): UIMessage<METADATA, DATA_PARTS, TOOLS>[] | undefined;
+//# sourceMappingURL=useStreamingUIMessages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useStreamingUIMessages.d.ts","sourceRoot":"","sources":["../../src/react/useStreamingUIMessages.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAuB,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAiBlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,GAAG,OAAO,EAClB,UAAU,SAAS,WAAW,GAAG,WAAW,EAC5C,KAAK,SAAS,OAAO,GAAG,OAAO,EAC/B,KAAK,SAAS,WAAW,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,EAEpD,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,MAAM,EACrC,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,GAEA,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,GAAG,SAAS,CA8FtD"}

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":"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"}

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":"AAAA,YAAY,CAAC;AACb,OAAO,EACL,IAAI,GAIL,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAGN,MAAM,cAAc,CAAC;AAOtB,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQlD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAsCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAY,EACZ,IAAwC,EACxC,OAKC;IAID,0BAA0B;IAC1B,MAAM,SAAS,GAAG,iBAAiB,CACjC,KAAK,EACL,IAA0C,EAC1C,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAC7C,CAAC;IAEF,IAAI,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;IACtD,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACvD,MAAM,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC3C,uDAAuD;YACvD,UAAU,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;YACtC,MAAM;QACR,CAAC;IACH,CAAC;IACD,oEAAoE;IACpE,MAAM,cAAc,GAAG,0BAA0B,CAC/C,KAA+C,EAC/C,CAAC,OAAO,CAAC,MAAM;QACb,IAAI,KAAK,MAAM;QACf,SAAS,CAAC,MAAM,KAAK,kBAAkB;QACvC,CAAC,CAAC,MAAM;QACR,CAAC,CAAE,EAAE,GAAG,IAAI,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAU,EACvE,EAAE,UAAU,EAAE,CACf,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;IAE7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,MAAM,kBAAkB,GACtB,cAAc,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1B,GAAG,CAAC;YACJ,SAAS,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS;SAC/C,CAAC,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO;YACL,GAAG,SAAS;YACZ,OAAO,EAAE,MAAM,CACb,SAAS,CAAC,OAAO;iBACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;gBACzC,uDAAuD;iBACtD,MAAM,CAAC,kBAAkB,CAGxB,CACL,CAAC,MAAM,CACN,CAAC,IAAI,EAAE,GAAyD,EAAE,EAAE;gBAClE,GAAG,CAAC,GAAG,GAAG,GAAG,QAAQ,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;gBACtD,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;gBACzB,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,OAAO,CAAC,GAAG,CAAC,CAAC;gBACf,CAAC;gBACD,IAAI,IAAI,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,SAAS,KAAK,GAAG,CAAC,SAAS,EAAE,CAAC;oBACjE,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;gBACxB,CAAC;gBACD,IACE,IAAI,CAAC,MAAM,KAAK,SAAS;oBACzB,CAAC,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,EAC3C,CAAC;oBACD,+DAA+D;oBAC/D,OAAO;oBACP,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBACrC,CAAC;gBACD,8DAA8D;gBAC9D,OAAO,IAAI,CAAC;YACd,CAAC,EACD,EAA8D,CAC/D;SACF,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1C,OAAO,MAGN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAY,EACZ,IAKU,EACV,OAGC;IAED,MAAM,SAAS,GACb,IAAI,KAAK,MAAM;QACb,CAAC,CAAC,IAAI;QACN,CAAC,CAAE,IAAI,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,CAAuC,CAAC;IACxE,MAAM,UAAU,GACd,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC,CAAC;IAC/D,MAAM,YAAY,GAAG,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,CAAC;IAChD,MAAM,UAAU,GAAG,sBAAsB,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAC1E,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,EAAiC,CAAC;IAC1E,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAEhC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YACnC,WAAW,CAAC,SAAS,CAAC,CAAC;YACvB,OAAO;QACT,CAAC;QACD,MAAM,iBAAiB,GAAG,EAAE,aAAa,CAAC,OAAO,CAAC;QAClD,CAAC,KAAK,IAAI,EAAE;YACV,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CACxE,CAAC;YACF,IAAI,aAAa,CAAC,OAAO,KAAK,iBAAiB,EAAE,CAAC;gBAChD,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE9D,OAAO,QAAQ,CAAC;AAClB,CAAC"}