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

package/dist/esm/react/types.d.ts

@@ -0,0 +1,26 @@
+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;
+    /**
+     * 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;
+} & 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;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/react/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,MAAM,WAAW,CACrB,IAAI,GAAG,OAAO,EACd,CAAC,SAAS,UAAU,GAAG,UAAU,IAC/B,iBAAiB,CACnB,OAAO,EACP,QAAQ,EACR;IACE,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,iBAAiB,CAAC;IAElC;;;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,iBAAiB,CAC3B,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,CAAC,SAAS,UAAU,GAAG,UAAU,IAC/B,iBAAiB,CACnB,OAAO,EACP,QAAQ,EACR;IACE,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,GAAG,IAAI,EACR,gBAAgB,CAAC,CAAC,CAAC,GAAG;IAAE,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAC1D,CAAC;AAEF,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,IAC3E,KAAK,SAAS,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,GAC1C,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,gBAAgB,GAAG,YAAY,CAAC,CAAC,GACxE,KAAK,CAAC;AAEZ,MAAM,MAAM,oBAAoB,CAC9B,KAAK,SAAS,WAAW,CAAC,OAAO,EAAE,UAAU,CAAC,IAC5C,KAAK,SAAS,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC"}

package/dist/esm/react/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/react/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/react/types.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,20 @@
+/**
+ * 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, }?: {
+    /**
+     * The number of characters to display per second.
+     */
+    charsPerSec?: number;
+}): [string, {
+    cursor: number;
+    isStreaming: boolean;
+}];
+//# sourceMappingURL=useSmoothText.d.ts.map

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

@@ -0,0 +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,GAClB,GAAE;IACD;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAkDpD"}

package/dist/esm/react/useSmoothText.js

@@ -0,0 +1,50 @@
+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, { charsPerSec = 256, } = {}) {
+    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 }];
+}
+//# sourceMappingURL=useSmoothText.js.map

package/dist/esm/react/useSmoothText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSmoothText.js","sourceRoot":"","sources":["../../../src/react/useSmoothText.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEpD,MAAM,GAAG,GAAG,EAAE,CAAC;AACf,MAAM,YAAY,GAAG,IAAI,GAAG,GAAG,CAAC;AAChC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAC7B;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,EACE,WAAW,GAAG,GAAG,MAMf,EAAE;IAEN,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,WAAW,GAAG,MAAM,CAAC;QACzB,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,WAAW;QACrD,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE;QACjB,aAAa,EAAE,IAAI,CAAC,MAAM;QAC1B,UAAU,EAAE,WAAW,GAAG,IAAI;KAC/B,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAE7D,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,gBAAgB,GACpB,CAAC,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,aAAa,CAAC;YACjD,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC3C,sEAAsE;QACtE,WAAW,CAAC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CACvC,CAAC,CAAC,GAAG,gBAAgB,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAC3D,WAAW,CAAC,OAAO,CAAC,UAAU,GAAG,CAAC,CACnC,CAAC;QAEF,SAAS,MAAM;YACb,IAAI,WAAW,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC9C,OAAO;YACT,CAAC;YACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAClC,gBAAgB,EAChB,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAC/B,CAAC;YACF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CACtB,mBAAmB,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CACrD,CAAC;YACF,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CACnC,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,KAAK,EAClC,IAAI,CAAC,MAAM,CACZ,CAAC;YACF,WAAW,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC;YAC/B,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,EAAE,CAAC;QACT,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACnD,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC;IAErC,OAAO,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/agent/issues"
   },
-  "version": "0.1.4-alpha.0",
+  "version": "0.1.4",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -105,6 +105,9 @@
     "chokidar-cli": "^3.0.0",
     "convex-test": "^0.0.37",
     "eslint": "^9.24.0",
+    "eslint-plugin-jsx-a11y": "^6.8.0",
+    "eslint-plugin-react": "^7.34.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
     "globals": "^15.15.0",
     "prettier": "3.2.5",
     "typescript": "^5.8.3",

package/src/client/streaming.ts

@@ -9,7 +9,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 +19,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/streams.ts

@@ -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/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!" },
+      ]),
+    ]);
+  });
+});