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

package/src/client/streaming.ts

@@ -1,7 +1,16 @@
-import { ChunkDetector, smoothStream, StreamTextTransform, ToolSet } from "ai";
-import { ProviderOptions, StreamDelta, TextStreamPart } from "../validators";
+import {
+  type ChunkDetector,
+  smoothStream,
+  type StreamTextTransform,
+  type ToolSet,
+} from "ai";
+import type {
+  ProviderOptions,
+  StreamDelta,
+  TextStreamPart,
+} from "../validators";
 import type { AgentComponent, MessageDoc } from "./index";
-import { RunActionCtx } from "./types";
+import type { RunActionCtx } from "./types";
 
 export type StreamingOptions = {
   /**
@@ -9,7 +18,7 @@ export type StreamingOptions = {
    * Note: this is not a guarantee that every delta will be exactly one line.
    * E.g. if "line" is specified, it won't save any deltas until it encounters
    * a newline character.
-   * Defaults to "word".
+   * Defaults to a regex that chunks by punctuation followed by whitespace.
    */
   chunking?: "word" | "line" | RegExp | ChunkDetector;
   /**
@@ -19,7 +28,8 @@ export type StreamingOptions = {
   throttleMs?: number;
 };
 export const DEFAULT_STREAMING_OPTIONS = {
-  chunking: "word",
+  // This chunks by sentences / clauses. Punctuation followed by whitespace.
+  chunking: /[\p{P}\s]/u,
   throttleMs: 250,
 } satisfies StreamingOptions;
 

package/src/component/files.ts

@@ -1,7 +1,7 @@
 import { paginator } from "convex-helpers/server/pagination";
-import { mutation, MutationCtx, query } from "./_generated/server.js";
+import type { Id } from "./_generated/dataModel.js";
+import { mutation, type MutationCtx, query } from "./_generated/server.js";
 import { schema, v } from "./schema.js";
-import { Id } from "./_generated/dataModel.js";
 
 export const addFile = mutation({
   args: {

package/src/component/messages.test.ts

@@ -1,12 +1,12 @@
 /// <reference types="vite/client" />
 
-import { describe, expect, test } from "vitest";
 import { convexTest } from "convex-test";
-import schema from "./schema.js";
+import { describe, expect, test } from "vitest";
 import { api } from "./_generated/api.js";
-import { modules } from "./setup.test.js";
-import { Id } from "./_generated/dataModel.js";
+import type { Id } from "./_generated/dataModel.js";
 import { getMaxMessage } from "./messages.js";
+import schema from "./schema.js";
+import { modules } from "./setup.test.js";
 
 describe("agent", () => {
   test("getMaxMessage works for threads", async () => {

package/src/component/messages.ts

@@ -1,6 +1,7 @@
 import { assert, omit } from "convex-helpers";
 import { mergedStream, stream } from "convex-helpers/server/stream";
-import { ObjectType } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import type { ObjectType } from "convex/values";
 import {
   DEFAULT_MESSAGE_RANGE,
   DEFAULT_RECENT_MESSAGES,
@@ -8,38 +9,37 @@ import {
   isTool,
 } from "../shared.js";
 import {
-  vPaginationResult,
   vMessageEmbeddings,
   vMessageStatus,
   vMessageWithMetadata,
+  vPaginationResult,
   vSearchOptions,
   vStepWithMessages,
 } from "../validators.js";
 import { api, internal } from "./_generated/api.js";
-import { Doc, Id } from "./_generated/dataModel.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
 import {
   action,
   internalQuery,
   mutation,
-  MutationCtx,
+  type MutationCtx,
   query,
-  QueryCtx,
+  type QueryCtx,
 } from "./_generated/server.js";
-import { schema, v } from "./schema.js";
+import type { MessageDoc } from "./schema.js";
+import { schema, v, vMessageDoc } from "./schema.js";
+import {
+  getThread as _getThread,
+  listThreadsByUserId as _listThreadsByUserId,
+  updateThread as _updateThread,
+} from "./threads.js";
 import { insertVector, searchVectors } from "./vector/index.js";
 import {
-  VectorDimension,
+  type VectorDimension,
   VectorDimensions,
-  VectorTableId,
+  type VectorTableId,
   vVectorId,
 } from "./vector/tables.js";
-import {
-  listThreadsByUserId as _listThreadsByUserId,
-  getThread as _getThread,
-  updateThread as _updateThread,
-} from "./threads.js";
-import { paginationOptsValidator } from "convex/server";
-import { MessageDoc, vMessageDoc } from "./schema.js";
 
 /** @deprecated Use *.threads.listMessagesByThreadId instead. */
 export const listThreadsByUserId = _listThreadsByUserId;

package/src/component/schema.ts

@@ -1,5 +1,5 @@
 import { defineSchema, defineTable } from "convex/server";
-import { Infer, v } from "convex/values";
+import { type Infer, v } from "convex/values";
 import {
   vThreadStatus,
   vMessage,

package/src/component/streams.ts

@@ -1,15 +1,15 @@
+import { omit, pick } from "convex-helpers";
 import { v } from "convex/values";
+import { type StreamDelta, vStreamDelta, vStreamMessage } from "../validators";
+import { internal } from "./_generated/api";
+import type { Id } from "./_generated/dataModel";
 import {
   internalMutation,
   mutation,
-  MutationCtx,
+  type MutationCtx,
   query,
 } from "./_generated/server";
-import { omit, pick } from "convex-helpers";
-import { StreamDelta, vStreamDelta, vStreamMessage } from "../validators";
 import schema from "./schema";
-import { internal } from "./_generated/api";
-import { Id } from "./_generated/dataModel";
 
 const MAX_DELTAS_PER_REQUEST = 1000;
 const MAX_DELTAS_PER_STREAM = 100;
@@ -51,10 +51,9 @@ export const listDeltas = query({
         );
       totalDeltas += streamDeltas.length;
       deltas.push(
-        ...streamDeltas.map((d) => ({
-          streamId: d.streamId.toString(),
-          ...pick(d, ["start", "end", "parts"]),
-        }))
+        ...streamDeltas.map((d) =>
+          pick(d, ["streamId", "start", "end", "parts"])
+        )
       );
       if (totalDeltas >= MAX_DELTAS_PER_REQUEST) {
         break;

package/src/component/threads.ts

@@ -1,21 +1,21 @@
 import { assert, omit, pick } from "convex-helpers";
 import { paginator } from "convex-helpers/server/pagination";
 import { partial } from "convex-helpers/validators";
-import { ObjectType } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import type { ObjectType } from "convex/values";
+import { type ThreadDoc, vThreadDoc } from "../client/index.js";
 import { vPaginationResult } from "../validators.js";
 import { api, internal } from "./_generated/api.js";
-import { Doc } from "./_generated/dataModel.js";
+import type { Doc } from "./_generated/dataModel.js";
 import {
   action,
   internalMutation,
   mutation,
-  MutationCtx,
+  type MutationCtx,
   query,
 } from "./_generated/server.js";
-import { schema, v } from "./schema.js";
-import { paginationOptsValidator } from "convex/server";
 import { deleteMessage } from "./messages.js";
-import { ThreadDoc, vThreadDoc } from "../client/index.js";
+import { schema, v } from "./schema.js";
 
 function publicThreadOrNull(thread: Doc<"threads"> | null): ThreadDoc | null {
   if (thread === null) {

package/src/component/users.ts

@@ -1,21 +1,21 @@
 import { paginator } from "convex-helpers/server/pagination";
+import { stream } from "convex-helpers/server/stream";
 import { nullable } from "convex-helpers/validators";
-import { ObjectType } from "convex/values";
+import { paginationOptsValidator } from "convex/server";
+import type { ObjectType } from "convex/values";
+import { vPaginationResult } from "../validators.js";
 import { internal } from "./_generated/api.js";
+import type { Id } from "./_generated/dataModel.js";
 import {
   action,
   internalMutation,
   internalQuery,
   mutation,
-  MutationCtx,
+  type MutationCtx,
   query,
 } from "./_generated/server.js";
-import { schema, v } from "./schema.js";
 import { deleteMessage } from "./messages.js";
-import { paginationOptsValidator } from "convex/server";
-import { stream } from "convex-helpers/server/stream";
-import { vPaginationResult } from "../validators.js";
-import { Id } from "./_generated/dataModel.js";
+import { schema, v } from "./schema.js";
 
 // Note: it only searches for users with threads
 export const listUsersWithThreads = query({

package/src/component/vector/index.ts

@@ -1,18 +1,22 @@
 import { paginator } from "convex-helpers/server/pagination";
+import { mergedStream, stream } from "convex-helpers/server/stream";
 import { v } from "convex/values";
-import { ActionCtx, mutation, MutationCtx, query } from "../_generated/server";
+import type { Id } from "../_generated/dataModel.js";
 import {
-  EmbeddingsWithoutDenormalizedFields,
+  type ActionCtx,
+  mutation,
+  type MutationCtx,
+  query,
+} from "../_generated/server.js";
+import schema from "../schema.js";
+import {
+  type EmbeddingsWithoutDenormalizedFields,
   getVectorTableName,
-  VectorDimension,
+  type VectorDimension,
   vEmbeddingsWithoutDenormalizedFields,
   vVectorDimension,
   vVectorId,
-} from "./tables";
-import schema from "../schema";
-import { mergedStream } from "convex-helpers/server/stream";
-import { stream } from "convex-helpers/server/stream";
-import { Id } from "../_generated/dataModel";
+} from "./tables.js";
 
 export const paginate = query({
   args: {

package/src/component/vector/tables.ts

@@ -2,20 +2,20 @@ import { omit } from "convex-helpers";
 import { literals } from "convex-helpers/validators";
 import {
   defineTable,
-  GenericTableSearchIndexes,
-  SchemaDefinition,
-  TableDefinition,
+  type GenericTableSearchIndexes,
+  type SchemaDefinition,
+  type TableDefinition,
 } from "convex/server";
 import {
-  GenericId,
-  Infer,
-  ObjectType,
+  type GenericId,
+  type Infer,
+  type ObjectType,
   v,
-  VId,
-  VObject,
-  VUnion,
+  type VId,
+  type VObject,
+  type VUnion,
 } from "convex/values";
-import { QueryCtx } from "../_generated/server";
+import type { QueryCtx } from "../_generated/server";
 
 // We only generate embeddings for non-tool, non-system messages
 const embeddings = {

package/src/mapping.ts

@@ -1,19 +1,19 @@
+import type { FileUIPart } from "@ai-sdk/ui-utils";
 import {
   convertToCoreMessages,
   coreMessageSchema,
-  GenerateObjectResult,
+  type Message as AIMessage,
   type AssistantContent,
   type CoreMessage,
   type DataContent,
+  type GenerateObjectResult,
   type StepResult,
   type ToolContent,
   type ToolSet,
-  type Message as AIMessage,
   type UserContent,
 } from "ai";
-import type { FileUIPart } from "@ai-sdk/ui-utils";
 import { assert } from "convex-helpers";
-import {
+import type {
   MessageWithMetadata,
   Step,
   StepWithMessagesWithMetadata,

package/src/react/deltas.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect } from "vitest";
+import { mergeDeltas, applyDeltasToStreamMessage } from "./deltas";
+import type { StreamMessage, StreamDelta, TextStreamPart } from "../validators";
+
+function makeStreamMessage(
+  streamId: string,
+  order: number,
+  stepOrder: number
+): StreamMessage {
+  return {
+    streamId,
+    order,
+    stepOrder,
+  } as StreamMessage;
+}
+
+function makeDelta(
+  streamId: string,
+  start: number,
+  end: number,
+  parts: TextStreamPart[]
+): StreamDelta {
+  return {
+    streamId,
+    start,
+    end,
+    parts,
+  };
+}
+
+describe("mergeDeltas", () => {
+  it("merges a single text-delta into a message", () => {
+    const streamId = "s1";
+    const streamMessages = [makeStreamMessage(streamId, 1, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+    ];
+    const [messages, newStreams, changed] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    expect(messages).toHaveLength(1);
+    expect(messages[0].text).toBe("Hello");
+    expect(messages[0].message?.role).toBe("assistant");
+    expect(changed).toBe(true);
+    expect(newStreams[0].cursor).toBe(5);
+  });
+
+  it("merges multiple deltas for the same stream", () => {
+    const streamId = "s1";
+    const streamMessages = [makeStreamMessage(streamId, 1, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+      makeDelta(streamId, 5, 11, [
+        { type: "text-delta", textDelta: " World!" },
+      ]),
+    ];
+    const [messages, newStreams, changed] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    expect(messages).toHaveLength(1);
+    expect(messages[0].text).toBe("Hello World!");
+    expect(changed).toBe(true);
+    expect(newStreams[0].cursor).toBe(11);
+  });
+
+  it("handles tool-call and tool-result parts", () => {
+    const streamId = "s2";
+    const streamMessages = [makeStreamMessage(streamId, 2, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 1, [
+        {
+          type: "tool-call",
+          toolCallId: "call1",
+          toolName: "myTool",
+          args: "",
+        },
+      ]),
+      makeDelta(streamId, 1, 2, [
+        {
+          type: "tool-result",
+          toolCallId: "call1",
+          toolName: "myTool",
+          result: "42",
+        },
+      ]),
+    ];
+    const [messages, _, changed] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    expect(messages).toHaveLength(2);
+    expect(messages[0].message?.role).toBe("assistant");
+    expect(messages[0].tool).toBe(true);
+    const content = messages[0].message?.content;
+    expect(content).toEqual([
+      {
+        type: "tool-call",
+        toolCallId: "call1",
+        toolName: "myTool",
+        args: "",
+      },
+    ]);
+    expect(messages[1].message?.role).toBe("tool");
+    expect(messages[1].tool).toBe(true);
+    expect(messages[1].message?.content).toEqual([
+      {
+        type: "tool-result",
+        toolCallId: "call1",
+        toolName: "myTool",
+        result: "42",
+      },
+    ]);
+    expect(changed).toBe(true);
+  });
+
+  it("returns changed=false if no new deltas", () => {
+    const streamId = "s3";
+    const streamMessages = [makeStreamMessage(streamId, 3, 0)];
+    const deltas: StreamDelta[] = [];
+    const [messages, newStreams, changed] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    expect(messages).toHaveLength(0);
+    expect(changed).toBe(false);
+    expect(newStreams[0].cursor).toBe(0);
+  });
+
+  it("handles multiple streams and sorts by order/stepOrder", () => {
+    const s1 = makeStreamMessage("s1", 1, 0);
+    const s2 = makeStreamMessage("s2", 2, 0);
+    const deltas = [
+      makeDelta("s2", 0, 3, [{ type: "text-delta", textDelta: "B" }]),
+      makeDelta("s1", 0, 3, [{ type: "text-delta", textDelta: "A" }]),
+    ];
+    const [messages, _, changed] = mergeDeltas("thread1", [s2, s1], [], deltas);
+    expect(messages).toHaveLength(2);
+    expect(messages[0].text).toBe("A");
+    expect(messages[1].text).toBe("B");
+    expect(changed).toBe(true);
+    // Sorted by order
+    expect(messages[0].order).toBe(1);
+    expect(messages[1].order).toBe(2);
+  });
+
+  it("does not duplicate text content when merging sequential text-deltas", () => {
+    const streamId = "s4";
+    const streamMessages = [makeStreamMessage(streamId, 4, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+      makeDelta(streamId, 5, 11, [
+        { type: "text-delta", textDelta: " World!" },
+      ]),
+      makeDelta(streamId, 11, 12, [{ type: "text-delta", textDelta: "!" }]),
+    ];
+    const [messages] = mergeDeltas("thread1", streamMessages, [], deltas);
+    expect(messages).toHaveLength(1);
+    expect(messages[0].text).toBe("Hello World!!");
+    // There should only be one text part per message
+    const content = messages[0].message?.content;
+    if (Array.isArray(content)) {
+      const textParts = content.filter((p) => p.type === "text");
+      expect(textParts).toHaveLength(1);
+      expect(textParts[0].text).toBe("Hello World!!");
+    }
+  });
+
+  it("does not duplicate reasoning parts", () => {
+    const streamId = "s6";
+    const streamMessages = [makeStreamMessage(streamId, 6, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 1, [
+        { type: "reasoning", textDelta: "I'm thinking..." },
+      ]),
+      makeDelta(streamId, 1, 2, [
+        { type: "reasoning", textDelta: " Still thinking..." },
+      ]),
+    ];
+    const [messages] = mergeDeltas("thread1", streamMessages, [], deltas);
+    expect(messages).toHaveLength(1);
+    if (Array.isArray(messages[0].message?.content)) {
+      const reasoningParts = messages[0].message.content.filter(
+        (p) => p.type === "reasoning"
+      );
+      expect(reasoningParts).toHaveLength(1);
+      expect(reasoningParts[0].text).toBe("I'm thinking... Still thinking...");
+    }
+  });
+
+  it("applyDeltasToStreamMessage is idempotent and does not duplicate content", () => {
+    const streamId = "s7";
+    const streamMessage = makeStreamMessage(streamId, 7, 0);
+    const deltas = [
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+      makeDelta(streamId, 5, 11, [
+        { type: "text-delta", textDelta: " World!" },
+      ]),
+    ];
+    // First call: apply both deltas
+    let [result, changed] = applyDeltasToStreamMessage(
+      "thread1",
+      streamMessage,
+      undefined,
+      deltas
+    );
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].text).toBe("Hello World!");
+    // Second call: re-apply the same deltas (should not duplicate)
+    [result, changed] = applyDeltasToStreamMessage(
+      "thread1",
+      streamMessage,
+      result,
+      deltas
+    );
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].text).toBe("Hello World!");
+    // Third call: add a new delta
+    const moreDeltas = [
+      ...deltas,
+      makeDelta(streamId, 11, 12, [{ type: "text-delta", textDelta: "!" }]),
+    ];
+    [result, changed] = applyDeltasToStreamMessage(
+      "thread1",
+      streamMessage,
+      result,
+      moreDeltas
+    );
+    expect(changed).toBe(true);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].text).toBe("Hello World!!");
+    // Re-apply all deltas again (should still not duplicate)
+    [result, changed] = applyDeltasToStreamMessage(
+      "thread1",
+      streamMessage,
+      result,
+      moreDeltas
+    );
+    expect(changed).toBe(false);
+    expect(result.messages).toHaveLength(1);
+    expect(result.messages[0].text).toBe("Hello World!!");
+  });
+
+  it("mergeDeltas is pure and does not mutate inputs", () => {
+    const streamId = "s8";
+    const streamMessages = [makeStreamMessage(streamId, 8, 0)];
+    const deltas = [
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+      makeDelta(streamId, 5, 11, [
+        { type: "text-delta", textDelta: " World!" },
+      ]),
+    ];
+    // Deep freeze inputs to catch mutation
+    function deepFreeze(obj: unknown): unknown {
+      if (obj && typeof obj === "object" && !Object.isFrozen(obj)) {
+        Object.freeze(obj);
+        for (const key of Object.keys(obj)) {
+          deepFreeze((obj as Record<string, unknown>)[key]);
+        }
+      }
+      return obj;
+    }
+    deepFreeze(streamMessages);
+    deepFreeze(deltas);
+    const [messages1, streams1, changed1] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    const [messages2, streams2, changed2] = mergeDeltas(
+      "thread1",
+      streamMessages,
+      [],
+      deltas
+    );
+    expect(messages1).toEqual(messages2);
+    expect(streams1).toEqual(streams2);
+    expect(changed1).toBe(changed2);
+    // Inputs should remain unchanged
+    expect(streamMessages).toEqual([makeStreamMessage(streamId, 8, 0)]);
+    expect(deltas).toEqual([
+      makeDelta(streamId, 0, 5, [{ type: "text-delta", textDelta: "Hello" }]),
+      makeDelta(streamId, 5, 11, [
+        { type: "text-delta", textDelta: " World!" },
+      ]),
+    ]);
+  });
+});