@convex-dev/agent 0.1.4-alpha.0 → 0.1.5-alpha.0

package/src/react/optimisticallySendMessage.ts

@@ -0,0 +1,46 @@
+import { insertAtTop } from "convex/react";
+import type { MessageDoc } from "../client";
+import type { OptimisticLocalStore } from "convex/browser";
+import type { ThreadQuery } from "./types";
+
+export function optimisticallySendMessage(
+  query: ThreadQuery<unknown, MessageDoc>
+): (
+  store: OptimisticLocalStore,
+  args: { threadId: string; prompt: string }
+) => void {
+  return (store, args) => {
+    const queries = store.getAllQueries(query);
+    let maxOrder = 0;
+    let maxStepOrder = 0;
+    for (const q of queries) {
+      if (q.args?.threadId !== args.threadId) continue;
+      if (q.args.streamArgs) continue;
+      for (const m of q.value?.page ?? []) {
+        maxOrder = Math.max(maxOrder, m.order);
+        maxStepOrder = Math.max(maxStepOrder, m.stepOrder);
+      }
+    }
+    const order = maxOrder + 1;
+    const stepOrder = 0;
+    insertAtTop({
+      paginatedQuery: query,
+      argsToMatch: { threadId: args.threadId, streamArgs: undefined },
+      item: {
+        _creationTime: Date.now(),
+        _id: crypto.randomUUID(),
+        order,
+        stepOrder,
+        status: "pending",
+        threadId: args.threadId,
+        tool: false,
+        message: {
+          role: "user",
+          content: args.prompt,
+        },
+        text: args.prompt,
+      },
+      localQueryStore: store,
+    });
+  };
+}

package/src/react/toUIMessages.test.ts

@@ -0,0 +1,301 @@
+import { describe, it, expect } from "vitest";
+import { toUIMessages } from "./toUIMessages";
+import type { MessageDoc } from "../client";
+
+// Helper to create a base message doc
+function baseMessageDoc(overrides: Partial<MessageDoc> = {}): MessageDoc {
+  return {
+    _id: "msg1",
+    _creationTime: Date.now(),
+    order: 1,
+    stepOrder: 0,
+    status: "success",
+    threadId: "thread1",
+    tool: false,
+    ...overrides,
+  };
+}
+
+describe("toUIMessages", () => {
+  it("handles user message", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: "Hello!",
+        },
+        text: "Hello!",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("user");
+    expect(uiMessages[0].content).toBe("Hello!");
+    expect(uiMessages[0].parts[0]).toEqual({ type: "text", text: "Hello!" });
+  });
+
+  it("handles assistant message", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: "Hi, how can I help?",
+        },
+        text: "Hi, how can I help?",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+    expect(uiMessages[0].content).toBe("Hi, how can I help?");
+    expect(uiMessages[0].parts[0]).toEqual({
+      type: "text",
+      text: "Hi, how can I help?",
+    });
+  });
+
+  it("handles multiple messages", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "user",
+          content: "Hello!",
+        },
+        text: "Hello!",
+      }),
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "reasoning",
+              text: "I'm thinking...",
+            },
+            {
+              type: "redacted-reasoning",
+              data: "asdfasdfasdf",
+            },
+            {
+              type: "text",
+              text: "I'm thinking...",
+            },
+            {
+              type: "file",
+              mimeType: "text/plain",
+              data: "asdfasdfasdf",
+            },
+            {
+              type: "tool-call",
+              toolName: "myTool",
+              toolCallId: "call1",
+              args: "",
+            },
+          ],
+        },
+        tool: true,
+        files: [
+          {
+            mimeType: "text/plain",
+            data: "asdfasdfasdf",
+          },
+        ],
+        reasoning: "I'm thinking...",
+        text: "I'm thinking...",
+      }),
+      baseMessageDoc({
+        message: {
+          role: "tool",
+          content: [
+            {
+              type: "tool-result",
+              toolCallId: "call1",
+              toolName: "myTool",
+              result: "42",
+            },
+          ],
+        },
+        text: "42",
+        tool: true,
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(2);
+    expect(uiMessages[0].role).toBe("user");
+    expect(uiMessages[0].parts.filter((p) => p.type === "text")).toHaveLength(
+      1
+    );
+    expect(uiMessages[1].role).toBe("assistant");
+    expect(
+      uiMessages[1].parts.filter((p) => p.type === "tool-invocation")
+    ).toHaveLength(1);
+    expect(
+      uiMessages[1].parts.filter((p) => p.type === "tool-invocation")[0]
+        .toolInvocation
+    ).toEqual({
+      toolName: "myTool",
+      toolCallId: "call1",
+      args: "",
+      state: "result",
+      result: "42",
+      step: 0,
+    });
+  });
+
+  it("handles multiple text and reasoning parts", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "reasoning",
+              text: "I'm thinking...",
+            },
+            {
+              type: "text",
+              text: "Here's one idea.",
+            },
+            {
+              type: "reasoning",
+              text: "I'm thinking...",
+            },
+            {
+              type: "text",
+              text: "Here's another idea.",
+            },
+          ],
+        },
+        reasoning: "I'm thinking...I'm thinking...",
+        text: "Here's one idea. Here's another idea.",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+    expect(uiMessages[0].content).toBe("Here's one idea. Here's another idea.");
+    expect(
+      uiMessages[0].parts.filter((p) => p.type === "reasoning")
+    ).toHaveLength(1);
+    expect(uiMessages[0].parts.filter((p) => p.type === "text")).toHaveLength(
+      1
+    );
+    expect(uiMessages[0].parts.filter((p) => p.type === "text")[0].text).toBe(
+      "Here's one idea. Here's another idea."
+    );
+  });
+
+  it("handles system message", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "system",
+          content: "System message here",
+        },
+        text: "System message here",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("system");
+    expect(uiMessages[0].content).toBe("System message here");
+    expect(uiMessages[0].parts[0]).toEqual({
+      type: "text",
+      text: "System message here",
+    });
+  });
+
+  it("handles tool call", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool-call",
+              toolName: "myTool",
+              toolCallId: "call1",
+              args: "",
+            },
+          ],
+        },
+        text: "",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+    expect(
+      uiMessages[0].parts.filter((p) => p.type === "tool-invocation")
+    ).toHaveLength(1);
+    expect(
+      uiMessages[0].parts.filter((p) => p.type === "tool-invocation")[0]
+        .toolInvocation
+    ).toEqual({
+      toolName: "myTool",
+      toolCallId: "call1",
+      args: "",
+      state: "call",
+      step: 0,
+    });
+  });
+
+  it("handles tool result", () => {
+    const messages = [
+      baseMessageDoc({
+        tool: true,
+        message: {
+          role: "assistant",
+          content: [
+            {
+              type: "tool-call",
+              toolName: "myTool",
+              toolCallId: "call1",
+              args: "",
+            },
+          ],
+        },
+        text: "",
+      }),
+      baseMessageDoc({
+        message: {
+          role: "tool",
+          content: [
+            {
+              type: "tool-result",
+              toolCallId: "call1",
+              toolName: "myTool",
+              result: "42",
+            },
+          ],
+        },
+        text: "",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    expect(uiMessages).toHaveLength(1);
+    expect(uiMessages[0].role).toBe("assistant");
+    // Should have a tool-invocation part
+    expect(uiMessages[0].parts.some((p) => p.type === "tool-invocation")).toBe(
+      true
+    );
+  });
+
+  it("does not duplicate text content", () => {
+    const messages = [
+      baseMessageDoc({
+        message: {
+          role: "assistant",
+          content: "Hello!",
+        },
+        text: "Hello!",
+      }),
+    ];
+    const uiMessages = toUIMessages(messages);
+    // There should only be one text part
+    const textParts = uiMessages[0].parts.filter((p) => p.type === "text");
+    expect(textParts).toHaveLength(1);
+    expect(textParts[0].text).toBe("Hello!");
+  });
+
+  // Add more tests for array content, tool calls, etc. as needed
+});

package/src/react/toUIMessages.ts

@@ -1,8 +1,8 @@
-import { UIMessage as AIUIMessage } from "ai";
 import type { ToolInvocationUIPart } from "@ai-sdk/ui-utils";
-import { MessageDoc } from "../client";
+import type { UIMessage as AIUIMessage } from "ai";
+import type { MessageDoc } from "../client";
 import { deserializeMessage, toUIFilePart } from "../mapping";
-import { MessageStatus } from "../validators";
+import type { MessageStatus } from "../validators";
 
 export type UIMessage = AIUIMessage & {
   key: string;
@@ -64,7 +64,7 @@ export function toUIMessages(
         assistantMessage = {
           ...common,
           role: "assistant",
-          content: message.text ?? "",
+          content: "",
           parts: [],
         };
         uiMessages.push(assistantMessage);
@@ -152,7 +152,11 @@ export function toUIMessages(
         }
       }
     }
-    if (!message.tool) {
+    if (
+      !message.tool &&
+      assistantMessage &&
+      assistantMessage.parts.length > 0
+    ) {
       // Reset it so the next set of tool calls will create a new assistant message
       assistantMessage = undefined;
     }

package/src/react/types.ts

@@ -0,0 +1,52 @@
+import type { BetterOmit, Expand } from "convex-helpers";
+import type {
+  FunctionArgs,
+  FunctionReference,
+  PaginationOptions,
+  PaginationResult,
+} from "convex/server";
+import type { MessageDoc } from "../client";
+import type { SyncStreamsReturnValue } from "../client/types";
+import type { StreamArgs } from "../validators";
+
+export type ThreadQuery<
+  Args = unknown,
+  M extends MessageDoc = MessageDoc,
+> = FunctionReference<
+  "query",
+  "public",
+  {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    // TODO: will this allow passing a function that doesn't have this param?
+    /**
+     * 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 ThreadStreamQuery<
+  Args = Record<string, unknown>,
+  M extends MessageDoc = MessageDoc,
+> = FunctionReference<
+  "query",
+  "public",
+  {
+    threadId: string;
+    paginationOpts: PaginationOptions;
+    streamArgs?: StreamArgs; // required for stream query
+  } & Args,
+  PaginationResult<M> & { streams: SyncStreamsReturnValue }
+>;
+
+export type ThreadMessagesArgs<Query extends ThreadQuery<unknown, MessageDoc>> =
+  Query extends ThreadQuery<unknown, MessageDoc>
+    ? Expand<BetterOmit<FunctionArgs<Query>, "paginationOpts" | "streamArgs">>
+    : never;
+
+export type ThreadMessagesResult<
+  Query extends ThreadQuery<unknown, MessageDoc>,
+> = Query extends ThreadQuery<unknown, infer M> ? M : never;

package/src/react/useSmoothText.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef, useState } from "react";
+
+const FPS = 20;
+const MS_PER_FRAME = 1000 / FPS;
+const MAX_TIME_JUMP_MS = 250;
+/**
+ * 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 function useSmoothText(
+  text: string,
+  {
+    charsPerSec = 256,
+  }: {
+    /**
+     * The number of characters to display per second.
+     */
+    charsPerSec?: number;
+  } = {}
+): [string, { cursor: number; isStreaming: boolean }] {
+  const [visibleText, setVisibleText] = useState(text);
+  const smoothState = useRef({
+    tick: Date.now() + (text.length * 1000) / charsPerSec,
+    cursor: text.length,
+    start: Date.now(),
+    initialLength: text.length,
+    charsPerMs: charsPerSec / 1000,
+  });
+
+  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
+    );
+
+    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;
+      setVisibleText(text.slice(0, smoothState.current.cursor));
+    }
+    update();
+    const interval = setInterval(update, MS_PER_FRAME);
+    return () => clearInterval(interval);
+  }, [text, isStreaming, charsPerSec]);
+
+  return [visibleText, { cursor: smoothState.current.cursor, isStreaming }];
+}

package/src/shared.ts

@@ -1,5 +1,5 @@
-import { CoreMessage } from "ai";
-import { Message } from "./validators";
+import type { CoreMessage } from "ai";
+import type { Message } from "./validators";
 
 export const DEFAULT_RECENT_MESSAGES = 100;
 

package/src/validators.test.ts

@@ -1,5 +1,24 @@
-import { Infer } from "convex/values";
+import type {
+  TextStreamPart as AITextStreamPart,
+  AssistantContent,
+  CoreAssistantMessage,
+  CoreMessage,
+  CoreSystemMessage,
+  CoreToolMessage,
+  CoreUserMessage,
+  FilePart,
+  ImagePart,
+  TextPart,
+  ToolCallPart,
+  ToolContent,
+  ToolSet,
+  UserContent,
+} from "ai";
+import type { Infer } from "convex/values";
 import { expectTypeOf, test } from "vitest";
+import type { ContextOptions, StorageOptions } from "./client";
+import type { SerializeUrlsAndUint8Arrays } from "./mapping";
+import type { TextStreamPart } from "./validators";
 import {
   vAssistantContent,
   vAssistantMessage,
@@ -15,28 +34,9 @@ import {
   vToolCallPart,
   vToolContent,
   vToolMessage,
+  vUserContent,
   vUserMessage,
 } from "./validators";
-import { vUserContent } from "./validators";
-import type { TextStreamPart } from "./validators";
-import {
-  AssistantContent,
-  CoreAssistantMessage,
-  CoreMessage,
-  CoreSystemMessage,
-  CoreToolMessage,
-  CoreUserMessage,
-  FilePart,
-  ImagePart,
-  TextPart,
-  TextStreamPart as AITextStreamPart,
-  ToolCallPart,
-  ToolContent,
-  ToolSet,
-  UserContent,
-} from "ai";
-import { SerializeUrlsAndUint8Arrays } from "./mapping";
-import { ContextOptions, StorageOptions } from "./client";
 
 // type assertion
 type OurUserContent = SerializeUrlsAndUint8Arrays<UserContent>;
@@ -125,4 +125,4 @@ type StreamPart = Extract<
 >;
 expectTypeOf<StreamPart>().toExtend<TextStreamPart>();
 
-test("noop", () => { });
+test("noop", () => {});

package/src/validators.ts

@@ -1,5 +1,11 @@
-import { Infer, ObjectType, v, Validator, Value } from "convex/values";
-import { vVectorDimension } from "./component/vector/tables";
+import {
+  v,
+  type Infer,
+  type ObjectType,
+  type Validator,
+  type Value,
+} from "convex/values";
+import { vVectorDimension } from "./component/vector/tables.js";
 
 // const deprecated = v.optional(v.any()) as unknown as VNull<unknown, "optional">;