@convex-dev/agent 0.2.6 → 0.2.8-alpha.0

package/src/react/useUIMessages.ts

@@ -0,0 +1,206 @@
+"use client";
+import {
+  type BetterOmit,
+  type ErrorMessage,
+  type Expand,
+} from "convex-helpers";
+import {
+  usePaginatedQuery,
+  type PaginatedQueryArgs,
+  type UsePaginatedQueryResult,
+} from "convex/react";
+import type {
+  FunctionArgs,
+  FunctionReference,
+  PaginationOptions,
+  PaginationResult,
+} from "convex/server";
+import { useMemo } from "react";
+import type { SyncStreamsReturnValue } from "../client/types.js";
+import type { MessageStatus, StreamArgs } from "../validators.js";
+import type { StreamQuery } from "./types.js";
+import { type UIMessage } from "../UIMessages.js";
+import { sorted } from "../shared.js";
+import { useStreamingUIMessages } from "./useStreamingUIMessages.js";
+
+export type UIMessageLike = {
+  order: number;
+  stepOrder: number;
+  status: MessageStatus | "streaming";
+  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);
+ *     const paginated = 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<
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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.">;
+  },
+): UsePaginatedQueryResult<
+  UIMessagesQueryResult<Query> & { streaming: boolean }
+> {
+  // These are full messages
+  const paginated = usePaginatedQuery(
+    query,
+    args as PaginatedQueryArgs<Query> | "skip",
+    { 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 = useStreamingUIMessages(
+    query as StreamQuery<UIMessagesQueryArgs<Query>>,
+    !options.stream ||
+      args === "skip" ||
+      paginated.status === "LoadingFirstPage"
+      ? "skip"
+      : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ({ ...args, paginationOpts: { cursor: null, numItems: 0 } } as any),
+    { startOrder },
+  );
+
+  const merged = useMemo(() => {
+    const streamListMessages =
+      streamMessages?.map((m) => ({
+        ...m,
+        streaming: m.status === "streaming",
+      })) ?? [];
+    return {
+      ...paginated,
+      results: sorted(
+        paginated.results
+          .map((m) => ({ ...m, streaming: false }))
+          // Note: this is intentionally after paginated results.
+          .concat(streamListMessages),
+      ).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" &&
+            (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;
+        },
+        [] as (UIMessagesQueryResult<Query> & {
+          streaming: boolean;
+        })[],
+      ),
+    };
+  }, [paginated, streamMessages]);
+
+  return merged as UIMessagesQueryResult<Query> & {
+    streaming: boolean;
+  };
+}

package/src/{react/toUIMessages.test.ts → toUIMessages.test.ts}

@@ -1,7 +1,7 @@
-import { describe, it, expect } from "vitest";
-import { toUIMessages } from "./toUIMessages.js";
-import type { MessageDoc } from "../client/index.js";
 import { assert } from "convex-helpers";
+import { describe, expect, it } from "vitest";
+import { toUIMessages } from "./UIMessages.js";
+import type { MessageDoc } from "./validators.js";
 
 // Helper to create a base message doc
 function baseMessageDoc(overrides: Partial<MessageDoc> = {}): MessageDoc {

package/src/validators.ts

@@ -442,6 +442,9 @@ export const vStreamMessage = v.object({
     v.literal("finished"),
     v.literal("aborted"),
   ),
+  format: v.optional(
+    v.union(v.literal("UIMessageChunk"), v.literal("TextStreamPart")),
+  ),
   order: v.number(),
   stepOrder: v.number(),
   // metadata

package/dist/client/textStreamParts.d.ts

@@ -1,5 +0,0 @@
-import { type StreamTextTransform, type ToolSet, type TextStreamPart } from "ai";
-import { type StreamingOptions } from "./streaming.js";
-export declare function serializeTextStreamingPartsV5(parts: TextStreamPart<ToolSet>[]): TextStreamPart<ToolSet>[];
-export declare function mergeTransforms<TOOLS extends ToolSet>(options: StreamingOptions | boolean | undefined, existing: StreamTextTransform<TOOLS> | Array<StreamTextTransform<TOOLS>> | undefined): StreamTextTransform<TOOLS> | StreamTextTransform<TOOLS>[] | undefined;
-//# sourceMappingURL=textStreamParts.d.ts.map

package/dist/client/textStreamParts.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"textStreamParts.d.ts","sourceRoot":"","sources":["../../src/client/textStreamParts.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,IAAI,CAAC;AACZ,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,GAC/B,cAAc,CAAC,OAAO,CAAC,EAAE,CAyB3B;AAED,wBAAgB,eAAe,CAAC,KAAK,SAAS,OAAO,EACnD,OAAO,EAAE,gBAAgB,GAAG,OAAO,GAAG,SAAS,EAC/C,QAAQ,EACJ,mBAAmB,CAAC,KAAK,CAAC,GAC1B,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,GACjC,SAAS,yEAgBd"}

package/dist/client/textStreamParts.js

@@ -1,44 +0,0 @@
-import { smoothStream, } from "ai";
-import { DEFAULT_STREAMING_OPTIONS, } from "./streaming.js";
-export function serializeTextStreamingPartsV5(parts) {
-    const compressed = [];
-    for (const part of parts) {
-        const last = compressed.at(-1);
-        if (part.type === "text-delta" && last?.type === "text-delta") {
-            last.text += part.text;
-        }
-        else if (part.type === "reasoning-delta" &&
-            last?.type === "reasoning-delta") {
-            last.text += part.text;
-        }
-        else {
-            if (part.type === "file") {
-                compressed.push({
-                    type: "file",
-                    file: {
-                        ...part.file,
-                        uint8Array: undefined,
-                    },
-                });
-            }
-            compressed.push(part);
-        }
-    }
-    return compressed;
-}
-export function mergeTransforms(options, existing) {
-    if (!options) {
-        return existing;
-    }
-    const chunking = typeof options === "boolean"
-        ? DEFAULT_STREAMING_OPTIONS.chunking
-        : options.chunking;
-    const transforms = Array.isArray(existing)
-        ? existing
-        : existing
-            ? [existing]
-            : [];
-    transforms.push(smoothStream({ delayInMs: null, chunking }));
-    return transforms;
-}
-//# sourceMappingURL=textStreamParts.js.map

package/dist/client/textStreamParts.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"textStreamParts.js","sourceRoot":"","sources":["../../src/client/textStreamParts.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,GAIb,MAAM,IAAI,CAAC;AACZ,OAAO,EACL,yBAAyB,GAE1B,MAAM,gBAAgB,CAAC;AAExB,MAAM,UAAU,6BAA6B,CAC3C,KAAgC;IAEhC,MAAM,UAAU,GAA8B,EAAE,CAAC;IACjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,EAAE,IAAI,KAAK,YAAY,EAAE,CAAC;YAC9D,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;QACzB,CAAC;aAAM,IACL,IAAI,CAAC,IAAI,KAAK,iBAAiB;YAC/B,IAAI,EAAE,IAAI,KAAK,iBAAiB,EAChC,CAAC;YACD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACzB,UAAU,CAAC,IAAI,CAAC;oBACd,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE;wBACJ,GAAG,IAAI,CAAC,IAAI;wBACZ,UAAU,EAAE,SAAkC;qBAC/C;iBACF,CAAC,CAAC;YACL,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,OAA+C,EAC/C,QAGa;IAEb,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GACZ,OAAO,OAAO,KAAK,SAAS;QAC1B,CAAC,CAAC,yBAAyB,CAAC,QAAQ;QACpC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACvB,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QACxC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,QAAQ;YACR,CAAC,CAAC,CAAC,QAAQ,CAAC;YACZ,CAAC,CAAC,EAAE,CAAC;IACT,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC7D,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/react/deltas.d.ts

@@ -1,27 +0,0 @@
-import type { TextStreamPart, ToolSet, UIMessageChunk } from "ai";
-import type { MessageDoc } from "../client/index.js";
-import { type StreamDelta, type StreamMessage } from "../validators.js";
-export declare function mergeDeltas(threadId: string, streamMessages: StreamMessage[], existingStreams: Array<{
-    streamId: string;
-    cursor: number;
-    messages: MessageDoc[];
-}>, allDeltas: StreamDelta[]): [
-    MessageDoc[],
-    Array<{
-        streamId: string;
-        cursor: number;
-        messages: MessageDoc[];
-    }>,
-    boolean
-];
-export declare function applyDeltasToStreamMessage(threadId: string, streamMessage: StreamMessage, existing: {
-    streamId: string;
-    cursor: number;
-    messages: MessageDoc[];
-} | undefined, deltas: StreamDelta[]): [{
-    streamId: string;
-    cursor: number;
-    messages: MessageDoc[];
-}, boolean];
-export declare function createStreamingMessage(threadId: string, message: StreamMessage, part: UIMessageChunk<ToolSet> | TextStreamPart<ToolSet>, index: number): MessageDoc;
-//# sourceMappingURL=deltas.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"deltas.d.ts","sourceRoot":"","sources":["../../src/react/deltas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,cAAc,EACd,OAAO,EACP,cAAc,EACf,MAAM,IAAI,CAAC;AACZ,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,aAAa,EAMnB,MAAM,kBAAkB,CAAC;AAM1B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,aAAa,EAAE,EAC/B,eAAe,EAAE,KAAK,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB,CAAC,EACF,SAAS,EAAE,WAAW,EAAE,GACvB;IACD,UAAU,EAAE;IACZ,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IACnE,OAAO;CACR,CAgCA;AAGD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,aAAa,EAC5B,QAAQ,EACJ;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,GAC5D,SAAS,EACb,MAAM,EAAE,WAAW,EAAE,GACpB,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;CAAE,EAAE,OAAO,CAAC,CAkZzE;AA2FD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,EACvD,KAAK,EAAE,MAAM,GACZ,UAAU,CAmMZ"}