@assistant-ui/react-langchain 0.0.14 → 0.0.17

package/src/convertMessages.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+import { convertLangChainBaseMessage } from "./convertMessages";
+import type { LangChainBaseMessage, UIMessage } from "./types";
+
+const humanMessage = (content: unknown): LangChainBaseMessage => ({
+  _getType: () => "human",
+  id: "msg-1",
+  content,
+});
+
+const aiMessage = (content: unknown): LangChainBaseMessage => ({
+  _getType: () => "ai",
+  id: "msg-2",
+  content,
+});
+
+const contentOf = (result: ReturnType<typeof convertLangChainBaseMessage>) => {
+  if (result.role === "tool")
+    throw new Error("expected a content-bearing message");
+  return result.content;
+};
+
+describe("convertLangChainBaseMessage file content parts", () => {
+  it("converts a base64 file block", () => {
+    const result = convertLangChainBaseMessage(
+      humanMessage([
+        {
+          type: "file",
+          data: "ZmFrZQ==",
+          mime_type: "application/pdf",
+          source_type: "base64",
+          metadata: { filename: "a.pdf" },
+        },
+      ]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      {
+        type: "file",
+        filename: "a.pdf",
+        data: "ZmFrZQ==",
+        mimeType: "application/pdf",
+      },
+    ]);
+  });
+
+  it("falls back to a default filename when metadata is absent", () => {
+    const result = convertLangChainBaseMessage(
+      humanMessage([
+        { type: "file", data: "ZmFrZQ==", mime_type: "application/pdf" },
+      ]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      {
+        type: "file",
+        filename: "file",
+        data: "ZmFrZQ==",
+        mimeType: "application/pdf",
+      },
+    ]);
+  });
+});
+
+describe("convertLangChainBaseMessage reasoning content parts", () => {
+  it("joins summary parts into a single reasoning part", () => {
+    const result = convertLangChainBaseMessage(
+      aiMessage([
+        {
+          type: "reasoning",
+          summary: [
+            { type: "summary_text", text: "first" },
+            { type: "summary_text", text: "second" },
+          ],
+        },
+      ]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      { type: "reasoning", text: "first\n\n\nsecond" },
+    ]);
+  });
+
+  it("falls back to the reasoning string when summary is absent", () => {
+    const result = convertLangChainBaseMessage(
+      aiMessage([{ type: "reasoning", reasoning: "thinking out loud" }]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      { type: "reasoning", text: "thinking out loud" },
+    ]);
+  });
+
+  it("does not throw when a reasoning block omits both summary and reasoning", () => {
+    const result = convertLangChainBaseMessage(
+      aiMessage([{ type: "reasoning" }]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([{ type: "reasoning", text: "" }]);
+  });
+
+  it("tolerates null entries inside the summary array", () => {
+    const result = convertLangChainBaseMessage(
+      aiMessage([
+        {
+          type: "reasoning",
+          summary: [null, { type: "summary_text", text: "kept" }],
+        },
+      ]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      { type: "reasoning", text: "\n\n\nkept" },
+    ]);
+  });
+});
+
+describe("convertLangChainBaseMessage generative UI from graph state", () => {
+  const uiMessage = (messageId: string): UIMessage => ({
+    type: "ui",
+    id: "ui-1",
+    name: "chart",
+    props: { points: [1, 2, 3] },
+    metadata: { message_id: messageId },
+  });
+
+  it("appends a data part for UI attached to the assistant message", () => {
+    const result = convertLangChainBaseMessage(aiMessage("hello"), {
+      uiMessagesByParent: new Map([["msg-2", [uiMessage("msg-2")]]]),
+    });
+
+    expect(contentOf(result)).toEqual([
+      { type: "text", text: "hello" },
+      { type: "data", name: "chart", data: { points: [1, 2, 3] } },
+    ]);
+  });
+
+  it("leaves the message unchanged when no UI targets it", () => {
+    const result = convertLangChainBaseMessage(aiMessage("hello"), {
+      uiMessagesByParent: new Map([["other-id", [uiMessage("other-id")]]]),
+    });
+
+    expect(contentOf(result)).toEqual([{ type: "text", text: "hello" }]);
+  });
+
+  it("appends a data part per UI when several target the same message", () => {
+    const result = convertLangChainBaseMessage(aiMessage("hello"), {
+      uiMessagesByParent: new Map([
+        [
+          "msg-2",
+          [
+            { ...uiMessage("msg-2"), name: "chart", props: { a: 1 } },
+            { ...uiMessage("msg-2"), name: "table", props: { b: 2 } },
+          ],
+        ],
+      ]),
+    });
+
+    expect(contentOf(result)).toEqual([
+      { type: "text", text: "hello" },
+      { type: "data", name: "chart", data: { a: 1 } },
+      { type: "data", name: "table", data: { b: 2 } },
+    ]);
+  });
+
+  it("does not attach UI to an assistant message without an id", () => {
+    const result = convertLangChainBaseMessage(
+      { ...aiMessage("hello"), id: undefined },
+      { uiMessagesByParent: new Map([["", [uiMessage("")]]]) },
+    );
+
+    expect(contentOf(result)).toEqual([{ type: "text", text: "hello" }]);
+  });
+
+  it("leaves the message unchanged when no converter metadata is passed", () => {
+    const result = convertLangChainBaseMessage(aiMessage("hello"));
+
+    expect(contentOf(result)).toEqual([{ type: "text", text: "hello" }]);
+  });
+});
+
+describe("convertLangChainBaseMessage image content parts", () => {
+  it("reads the url from an image_url object", () => {
+    const result = convertLangChainBaseMessage(
+      humanMessage([
+        { type: "image_url", image_url: { url: "https://example.com/a.png" } },
+      ]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([
+      { type: "image", image: "https://example.com/a.png" },
+    ]);
+  });
+
+  it("drops the image part when image_url is undefined", () => {
+    const result = convertLangChainBaseMessage(
+      humanMessage([{ type: "image_url" }]),
+      {},
+    );
+
+    expect(contentOf(result)).toEqual([]);
+  });
+});

package/src/convertMessages.ts

@@ -1,8 +1,29 @@
 "use client";
 
 import type { useExternalMessageConverter } from "@assistant-ui/core/react";
+import type {
+  AppendMessage,
+  DataMessagePart,
+  MessageTiming,
+} from "@assistant-ui/core";
 import type { ReadonlyJSONObject } from "assistant-stream/utils";
-import type { LangChainBaseMessage, LangChainContentBlock } from "./types";
+import type {
+  LangChainBaseMessage,
+  LangChainContentBlock,
+  UIMessage,
+} from "./types";
+
+type LangChainMessageConverterMetadata =
+  useExternalMessageConverter.Metadata & {
+    uiMessagesByParent?: Map<string, UIMessage[]>;
+    messageTiming?: Record<string, MessageTiming>;
+  };
+
+const uiMessageToDataPart = (ui: UIMessage): DataMessagePart => ({
+  type: "data",
+  name: ui.name,
+  data: ui.props,
+});
 
 export const getMessageType = (message: LangChainBaseMessage): string => {
   if (typeof message._getType === "function") return message._getType();
@@ -23,17 +44,30 @@ const contentToParts = (content: unknown) => {
         case "text":
         case "text_delta":
           return { type: "text" as const, text: part.text };
-        case "image_url":
-          if (typeof part.image_url === "string") {
-            return { type: "image" as const, image: part.image_url };
-          }
-          return { type: "image" as const, image: part.image_url.url };
+        case "image_url": {
+          const image =
+            typeof part.image_url === "string"
+              ? part.image_url
+              : part.image_url?.url;
+          if (!image) return null;
+          return { type: "image" as const, image };
+        }
+        case "file":
+          return {
+            type: "file" as const,
+            filename: part.metadata?.filename ?? "file",
+            data: part.data,
+            mimeType: part.mime_type,
+          };
         case "thinking":
           return { type: "reasoning" as const, text: part.thinking };
         case "reasoning":
           return {
             type: "reasoning" as const,
-            text: part.summary.map((s) => s.text).join("\n\n\n"),
+            text:
+              part.summary?.map((s) => s?.text ?? "").join("\n\n\n") ??
+              part.reasoning ??
+              "",
           };
         case "tool_use":
         case "input_json_delta":
@@ -59,9 +93,10 @@ const getStringContent = (content: unknown): string => {
     .join("");
 };
 
-export const convertLangChainBaseMessage: useExternalMessageConverter.Callback<
-  LangChainBaseMessage
-> = (message) => {
+export const convertLangChainBaseMessage = (
+  message: LangChainBaseMessage,
+  metadata: LangChainMessageConverterMetadata = {},
+): useExternalMessageConverter.Message => {
   const type = getMessageType(message);
 
   switch (type) {
@@ -98,12 +133,26 @@ export const convertLangChainBaseMessage: useExternalMessageConverter.Callback<
       const assistantStatus =
         typeof message.status === "object" ? message.status : undefined;
 
+      const uiDataParts =
+        (message.id
+          ? metadata.uiMessagesByParent
+              ?.get(message.id)
+              ?.map(uiMessageToDataPart)
+          : undefined) ?? [];
+
+      const timing = metadata.messageTiming?.[message.id ?? ""];
+
       return {
         role: "assistant",
         id: message.id,
-        content: [...contentToParts(message.content), ...toolCallParts],
+        content: [
+          ...contentToParts(message.content),
+          ...toolCallParts,
+          ...uiDataParts,
+        ],
         metadata: {
           custom: getCustomMetadata(message.additional_kwargs),
+          ...(timing && { timing }),
         },
         ...(assistantStatus && { status: assistantStatus }),
       };
@@ -135,3 +184,54 @@ export const convertLangChainBaseMessage: useExternalMessageConverter.Callback<
       };
   }
 };
+
+export const getMessageContent = (msg: AppendMessage) => {
+  const allContent = [
+    ...msg.content,
+    ...(msg.attachments?.flatMap((a) => a.content) ?? []),
+  ];
+
+  const hasNonText = allContent.some(
+    (part) => part.type === "file" || part.type === "image",
+  );
+  const hasText = allContent.some((part) => part.type === "text");
+  if (hasNonText && !hasText) {
+    allContent.unshift({ type: "text", text: " " });
+  }
+
+  const content = allContent.map((part) => {
+    const type = part.type;
+    switch (type) {
+      case "text":
+        return { type: "text" as const, text: part.text };
+      case "image":
+        return { type: "image_url" as const, image_url: { url: part.image } };
+      case "file":
+        return {
+          type: "file" as const,
+          data: part.data,
+          mime_type: part.mimeType,
+          metadata: { filename: part.filename ?? "file" },
+          source_type: "base64" as const,
+        };
+      case "tool-call":
+        throw new Error("Tool call appends are not supported.");
+      default: {
+        const _exhaustiveCheck:
+          | "reasoning"
+          | "source"
+          | "audio"
+          | "data"
+          | "generative-ui" = type;
+        throw new Error(
+          `Unsupported append message part type: ${_exhaustiveCheck}`,
+        );
+      }
+    }
+  });
+
+  if (content.length === 1 && content[0]?.type === "text") {
+    return content[0].text ?? "";
+  }
+  return content;
+};

package/src/findForkCheckpointInHistory.test.ts

@@ -0,0 +1,263 @@
+import { describe, expect, it, vi } from "vitest";
+import type { LangChainBaseMessage } from "./types";
+import { findForkCheckpointInHistory } from "./findForkCheckpointInHistory";
+
+const msg = (id: string | undefined): LangChainBaseMessage => ({
+  _getType: () => "human",
+  content: "",
+  id,
+});
+
+const makeClient = (history: unknown[]) => ({
+  threads: {
+    getHistory: vi.fn(async () => history as never),
+  },
+});
+
+type HistoryState = {
+  values: Record<string, unknown>;
+  checkpoint: { checkpoint_id?: string };
+};
+
+const makePaginatedClient = (states: HistoryState[]) => ({
+  threads: {
+    getHistory: vi.fn(
+      async (
+        _threadId: string,
+        options?: {
+          limit?: number;
+          before?: { configurable: { checkpoint_id: string } };
+        },
+      ) => {
+        const limit = options?.limit ?? 10;
+        const beforeId = options?.before?.configurable.checkpoint_id;
+        const start = beforeId
+          ? states.findIndex((s) => s.checkpoint.checkpoint_id === beforeId) + 1
+          : 0;
+        return states.slice(start, start + limit) as never;
+      },
+    ),
+  },
+});
+
+describe("findForkCheckpointInHistory", () => {
+  it("returns the checkpoint_id of the state whose messages match by id", async () => {
+    const client = makeClient([
+      {
+        values: { messages: [msg("a"), msg("b"), msg("c")] },
+        checkpoint: { checkpoint_id: "cp-too-long" },
+      },
+      {
+        values: { messages: [msg("a"), msg("b")] },
+        checkpoint: { checkpoint_id: "cp-match" },
+      },
+      {
+        values: { messages: [msg("a")] },
+        checkpoint: { checkpoint_id: "cp-too-short" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a"), msg("b")],
+      "messages",
+    );
+
+    expect(result).toBe("cp-match");
+    expect(client.threads.getHistory).toHaveBeenCalledWith("thread-1", {
+      limit: 100,
+    });
+  });
+
+  it("returns null when no state has the same message ids", async () => {
+    const client = makeClient([
+      {
+        values: { messages: [msg("a"), msg("x")] },
+        checkpoint: { checkpoint_id: "cp-1" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a"), msg("b")],
+      "messages",
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null when message ids are unstable (missing)", async () => {
+    const client = makeClient([
+      {
+        values: { messages: [msg("a"), msg(undefined)] },
+        checkpoint: { checkpoint_id: "cp-1" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a"), msg(undefined)],
+      "messages",
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it("reads messages from a custom messagesKey", async () => {
+    const client = makeClient([
+      {
+        values: { history: [msg("a")] },
+        checkpoint: { checkpoint_id: "cp-custom" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "history",
+    );
+
+    expect(result).toBe("cp-custom");
+  });
+
+  it("returns null when the matching checkpoint has no checkpoint_id", async () => {
+    const client = makeClient([
+      {
+        values: { messages: [msg("a")] },
+        checkpoint: {},
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "messages",
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it("keeps scanning when a matching state has no checkpoint_id", async () => {
+    const client = makeClient([
+      {
+        values: { messages: [msg("a")] },
+        checkpoint: {},
+      },
+      {
+        values: { messages: [msg("a")] },
+        checkpoint: { checkpoint_id: "cp-second" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "messages",
+    );
+
+    expect(result).toBe("cp-second");
+  });
+
+  it("does not throw when a state's messages payload is not an array", async () => {
+    const client = makeClient([
+      {
+        values: { messages: "ab" },
+        checkpoint: { checkpoint_id: "cp-1" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a"), msg("b")],
+      "messages",
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it("forwards a custom history limit to getHistory", async () => {
+    const client = makeClient([]);
+
+    await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "messages",
+      25,
+    );
+
+    expect(client.threads.getHistory).toHaveBeenCalledWith("thread-1", {
+      limit: 25,
+    });
+  });
+
+  it("pages through history to find a match beyond the first page", async () => {
+    const client = makePaginatedClient([
+      {
+        values: { messages: [msg("a"), msg("b"), msg("c"), msg("d")] },
+        checkpoint: { checkpoint_id: "cp-4" },
+      },
+      {
+        values: { messages: [msg("a"), msg("b"), msg("c")] },
+        checkpoint: { checkpoint_id: "cp-3" },
+      },
+      {
+        values: { messages: [msg("a"), msg("b")] },
+        checkpoint: { checkpoint_id: "cp-2" },
+      },
+      {
+        values: { messages: [msg("a")] },
+        checkpoint: { checkpoint_id: "cp-1" },
+      },
+    ]);
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "messages",
+      2,
+    );
+
+    expect(result).toBe("cp-1");
+    expect(client.threads.getHistory).toHaveBeenCalledTimes(2);
+    expect(client.threads.getHistory).toHaveBeenLastCalledWith("thread-1", {
+      limit: 2,
+      before: { configurable: { checkpoint_id: "cp-3" } },
+    });
+  });
+
+  it("stops instead of looping when the cursor does not advance", async () => {
+    const page = [
+      {
+        values: { messages: [msg("x"), msg("y")] },
+        checkpoint: { checkpoint_id: "cp-1" },
+      },
+      {
+        values: { messages: [msg("x")] },
+        checkpoint: { checkpoint_id: "cp-2" },
+      },
+    ];
+    const client = {
+      threads: { getHistory: vi.fn(async () => page as never) },
+    };
+
+    const result = await findForkCheckpointInHistory(
+      client,
+      "thread-1",
+      [msg("a")],
+      "messages",
+      2,
+    );
+
+    expect(result).toBeNull();
+    expect(client.threads.getHistory).toHaveBeenCalledTimes(2);
+  });
+});

package/src/findForkCheckpointInHistory.ts

@@ -0,0 +1,68 @@
+import type { LangChainBaseMessage } from "./types";
+
+type ForkCheckpointHistoryState = {
+  values?: Record<string, unknown> | undefined;
+  checkpoint?: { checkpoint_id?: string | null | undefined } | undefined;
+};
+
+type ForkHistoryCursor = { configurable: { checkpoint_id: string } };
+
+export type ForkCheckpointClient = {
+  threads: {
+    getHistory: (
+      threadId: string,
+      options?: { limit?: number; before?: ForkHistoryCursor },
+    ) => Promise<readonly ForkCheckpointHistoryState[]>;
+  };
+};
+
+export const findForkCheckpointInHistory = async (
+  client: ForkCheckpointClient,
+  threadId: string,
+  messagesUpToParent: readonly LangChainBaseMessage[],
+  messagesKey: string,
+  pageSize = 100,
+): Promise<string | null> => {
+  if (!messagesUpToParent.every((m) => typeof m.id === "string")) return null;
+
+  const scanned = new Set<string>();
+  let before: ForkHistoryCursor | undefined;
+
+  for (;;) {
+    const page = await client.threads.getHistory(
+      threadId,
+      before ? { limit: pageSize, before } : { limit: pageSize },
+    );
+
+    let oldestCheckpointId: string | undefined;
+    let advanced = false;
+    for (const state of page) {
+      const checkpointId = state.checkpoint?.checkpoint_id;
+      if (typeof checkpointId === "string") {
+        oldestCheckpointId = checkpointId;
+        if (!scanned.has(checkpointId)) {
+          scanned.add(checkpointId);
+          advanced = true;
+        }
+      }
+      const stateMessages = state.values?.[messagesKey] as
+        | readonly LangChainBaseMessage[]
+        | undefined;
+      if (
+        !Array.isArray(stateMessages) ||
+        stateMessages.length !== messagesUpToParent.length
+      )
+        continue;
+      if (!stateMessages.every((m) => typeof m.id === "string")) continue;
+      const isMatch = messagesUpToParent.every(
+        (m, i) => m.id === stateMessages[i]?.id,
+      );
+      if (isMatch && checkpointId) return checkpointId;
+    }
+
+    // `advanced` halts paging if the backend ignores `before` and repeats a page
+    if (page.length < pageSize || oldestCheckpointId === undefined || !advanced)
+      return null;
+    before = { configurable: { checkpoint_id: oldestCheckpointId } };
+  }
+};