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

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

@@ -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 }];
+}