Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧩 feat: Map Message Content Parts to a UI Parts Union (#16374)

Marco Beretta7f4bde8352c6
diff --git a/e2e/specs/mock/scenarios/parts.spec.ts b/e2e/specs/mock/scenarios/parts.spec.ts
new file mode 100644
index 0000000000..9a9f379e6c
--- /dev/null
+++ b/e2e/specs/mock/scenarios/parts.spec.ts
@@ -0,0 +1,133 @@
+import { expect, test } from '@playwright/test';
+import { fromUIMessage, toUIMessage } from 'librechat-data-provider';
+import type { Page } from '@playwright/test';
+import type { TMessage, UIMessage } from 'librechat-data-provider';
+import {
+ sendMessageAndWaitForCompletion,
+ selectMockEndpoint,
+ getAccessToken,
+ MOCK_ENDPOINTS,
+ NEW_CHAT_PATH,
+ replyPrompt,
+ thinkPrompt,
+ replyText,
+ thinkText,
+ fetchJson,
+} from '../helpers';
+
+/** Non-spec endpoint without an activity label, so its MCP tool cards stay separate parts. */
+const TOOL_ENDPOINT = { label: 'Mock Provider D', model: 'mock-model-d' };
+const MCP_SERVER_TITLE = 'E2E Memory';
+
+const uniqueLabel = (prefix: string) =>
+ `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e4)}`;
+
+/** Reads the conversation the page is on, as persisted, through the messages API. */
+async function readPersistedMessages(page: Page): Promise<TMessage[]> {
+ const conversationId = new URL(page.url()).pathname.replace('/c/', '');
+ expect(conversationId).not.toBe('new');
+ const token = await getAccessToken(page);
+ return fetchJson<TMessage[]>(page, `/api/messages/${encodeURIComponent(conversationId)}`, token);
+}
+
+/** Views every persisted message and requires each view to map back to the stored message. */
+function viewAndRestore(messages: TMessage[]): UIMessage[] {
+ return messages.map((message) => {
+ const view = toUIMessage(message);
+ expect(fromUIMessage(view, message)).toStrictEqual(message);
+ return view;
+ });
+}
+
+async function selectMemoryServer(page: Page) {
+ await page.getByRole('button', { name: 'MCP Servers', exact: true }).click();
+ const serverItem = page.getByRole('menuitemcheckbox', { name: new RegExp(MCP_SERVER_TITLE) });
+ await expect(serverItem).toBeVisible();
+ await serverItem.click();
+ await expect(serverItem).toHaveAttribute('aria-checked', 'true');
+ await page.keyboard.press('Escape');
+}
+
+test.describe('UI parts view of persisted messages', () => {
+ test('views a persisted reply as a user and an assistant UI message @scenario:persisted-reply-views-as-user-and-assistant-messages', async ({
+ page,
+ }) => {
+ const label = uniqueLabel('parts-reply');
+ await page.goto(NEW_CHAT_PATH, { timeout: 10_000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ const response = await sendMessageAndWaitForCompletion(page, replyPrompt(label));
+ expect(response.ok()).toBeTruthy();
+
+ const [user, assistant] = viewAndRestore(await readPersistedMessages(page));
+
+ expect(user.role).toBe('user');
+ expect(user.parts).toContainEqual({ type: 'text', text: replyPrompt(label) });
+ expect(assistant.role).toBe('assistant');
+ expect(assistant.metadata?.parentMessageId).toBe(user.id);
+ const text = assistant.parts
+ .filter((part) => part.type === 'text')
+ .map((part) => part.text)
+ .join('');
+ expect(text).toBe(replyText(label));
+ });
+
+ test('views persisted reasoning before the answer, in content order @scenario:persisted-reasoning-views-before-its-answer', async ({
+ page,
+ }) => {
+ const label = uniqueLabel('parts-think');
+ await page.goto(NEW_CHAT_PATH, { timeout: 10_000 });
+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);
+ const response = await sendMessageAndWaitForCompletion(page, thinkPrompt(label));
+ expect(response.ok()).toBeTruthy();
+
+ const messages = await readPersistedMessages(page);
+ const assistant = viewAndRestore(messages).find((message) => message.role === 'assistant');
+ const stored = messages.find((message) => !message.isCreatedByUser);
+ if (!assistant || !stored?.content) {
+ throw new Error('Persisted reasoning reply missing');
+ }
+
+ expect(assistant.parts.slice(0, stored.content.length).map((part) => part.type)).toEqual(
+ stored.content.map((part) => (part.type === 'think' ? 'reasoning' : part.type)),
+ );
+ const reasoning = assistant.parts.findIndex((part) => part.type === 'reasoning');
+ const answer = assistant.parts.findIndex((part) => part.type === 'text');
+ expect(reasoning).toBeGreaterThanOrEqual(0);
+ expect(reasoning).toBeLessThan(answer);
+ expect(assistant.parts[reasoning]).toMatchObject({ text: thinkText(label) });
+ });
+
+ test.describe('with an MCP tool turn', () => {
+ test.skip(({ isMobile }) => isMobile === true, 'composer MCP picker is desktop-only');
+
+ test('views persisted tool calls as completed tool parts @scenario:persisted-tool-calls-view-as-completed-tool-parts', async ({
+ page,
+ }) => {
+ test.setTimeout(90_000);
+ const label = uniqueLabel('parts-tool');
+ await page.goto(NEW_CHAT_PATH, { timeout: 10_000 });
+ await selectMockEndpoint(page, TOOL_ENDPOINT);
+ await selectMemoryServer(page);
+ const response = await sendMessageAndWaitForCompletion(page, `E2E_ACTIVITY_REPLY:${label}`, {
+ timeout: 60_000,
+ });
+ expect(response.ok()).toBeTruthy();
+
+ const messages = await readPersistedMessages(page);
+ const assistant = viewAndRestore(messages).find((message) => message.role === 'assistant');
+ if (!assistant) {
+ throw new Error('Persisted tool reply missing');
+ }
+
+ const tools = assistant.parts.filter((part) => part.type.startsWith('tool-'));
+ expect(tools.length).toBeGreaterThanOrEqual(2);
+ for (const tool of tools) {
+ expect(tool).toMatchObject({ state: 'output-available', toolCallId: expect.any(String) });
+ expect((tool as { toolCallId: string }).toolCallId).not.toBe('');
+ }
+ expect(new Set(tools.map((tool) => (tool as { toolCallId: string }).toolCallId)).size).toBe(
+ tools.length,
+ );
+ });
+ });
+});
diff --git a/packages/data-provider/src/errors.ts b/packages/data-provider/src/errors.ts
index a8709ff5b3..ed9da1909e 100644
--- a/packages/data-provider/src/errors.ts
+++ b/packages/data-provider/src/errors.ts
@@ -4,6 +4,11 @@ export function hasToolCallErrorPrefix(text: string): boolean {
return TOOL_CALL_ERROR_PREFIX.test(text);
}
+/** Whether a tool output string is one the tool output renderers present as a failure. */
+export function isToolErrorOutput(text: string): boolean {
+ return hasToolCallErrorPrefix(text) || text.startsWith('Error processing tool');
+}
+
export function stripToolCallErrorPrefix(text: string): string {
return text.replace(TOOL_CALL_ERROR_PREFIX, '');
}
diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.ts
index 1f14ec84dc..c6caeccb91 100644
--- a/packages/data-provider/src/index.ts
+++ b/packages/data-provider/src/index.ts
@@ -13,7 +13,8 @@ export * from './messages';
export * from './errors';
/* run steps */
export * from './runSteps';
-export * from './toolTiming';
+/* ui parts */
+export * from './parts';
/* artifacts */
export * from './artifacts';
/* schema helpers */
diff --git a/packages/data-provider/src/parts.spec.ts b/packages/data-provider/src/parts.spec.ts
new file mode 100644
index 0000000000..7fe722d22b
--- /dev/null
+++ b/packages/data-provider/src/parts.spec.ts
@@ -0,0 +1,1229 @@
+import type { UIMappingOptions, MappableContentPart, UIMessagePart, UIToolPart } from './parts';
+import type { TMessageContentParts, PartMetadata } from './types/content';
+import type { TAttachment, TMessage } from './schemas';
+import type { Agents } from './types/agents';
+import {
+ fromUIMessage,
+ isUIToolPart,
+ isUIDataPart,
+ toUIMessage,
+ fromUIParts,
+ fromUIPart,
+ toUIParts,
+ toUIPart,
+} from './parts';
+import { ContentTypes } from './types/runs';
+import { Tools } from './types/tools';
+
+/** One representative part per content type; the `Record` makes a missing member a type error. */
+const samples: Record<ContentTypes, MappableContentPart> = {
+ [ContentTypes.TEXT]: {
+ type: ContentTypes.TEXT,
+ text: 'Hello',
+ tool_call_ids: ['call-1'],
+ phase: 'final_answer',
+ agentId: 'agent-a',
+ groupId: 1,
+ },
+ [ContentTypes.THINK]: {
+ type: ContentTypes.THINK,
+ think: 'Considering',
+ reasoning_label: 'Planning',
+ reasoning_label_status: 'complete',
+ },
+ [ContentTypes.TEXT_DELTA]: { type: ContentTypes.TEXT_DELTA, text_delta: 'chunk' },
+ [ContentTypes.TOOL_CALL]: {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-1',
+ name: 'search',
+ args: '{"q":"cats"}',
+ output: '3',
+ progress: 1,
+ type: 'tool_call',
+ },
+ },
+ [ContentTypes.IMAGE_FILE]: {
+ type: ContentTypes.IMAGE_FILE,
+ image_file: {
+ file_id: 'file-1',
+ filename: 'cat.png',
+ filepath: '/images/cat.png',
+ height: 10,
+ width: 20,
+ type: 'image/png',
+ user: 'user-1',
+ bytes: 42,
+ embedded: false,
+ object: 'file',
+ usage: 0,
+ },
+ },
+ [ContentTypes.IMAGE_URL]: {
+ type: ContentTypes.IMAGE_URL,
+ image_url: { url: 'https://x/cat.png', detail: 'high' },
+ },
+ [ContentTypes.VIDEO_URL]: { type: ContentTypes.VIDEO_URL, video_url: { url: 'https://x/v.mp4' } },
+ [ContentTypes.INPUT_AUDIO]: {
+ type: ContentTypes.INPUT_AUDIO,
+ input_audio: { data: 'AAAA', format: 'wav' },
+ },
+ [ContentTypes.AGENT_UPDATE]: {
+ type: ContentTypes.AGENT_UPDATE,
+ agent_update: { index: 1, runId: 'run-1', agentId: 'agent-b' },
+ agentId: 'agent-b',
+ groupId: 1,
+ },
+ [ContentTypes.SUMMARY]: {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Earlier, we talked.' }],
+ summarizing: false,
+ },
+ [ContentTypes.ACTIVITY_LABEL]: {
+ type: ContentTypes.ACTIVITY_LABEL,
+ activity_label: 'Searched the web',
+ tool_call_ids: ['call-1'],
+ status: 'ok',
+ },
+ [ContentTypes.STEER]: { type: ContentTypes.STEER, steer: 'Focus on cats', steerId: 's-1' },
+ [ContentTypes.ERROR]: { type: ContentTypes.ERROR, error: 'Rate limited' },
+};
+
+const expectedUITypes: Record<ContentTypes, string> = {
+ [ContentTypes.TEXT]: 'text',
+ [ContentTypes.THINK]: 'reasoning',
+ [ContentTypes.TEXT_DELTA]: 'text',
+ [ContentTypes.TOOL_CALL]: 'tool-search',
+ [ContentTypes.IMAGE_FILE]: 'file',
+ [ContentTypes.IMAGE_URL]: 'file',
+ [ContentTypes.VIDEO_URL]: 'file',
+ [ContentTypes.INPUT_AUDIO]: 'file',
+ [ContentTypes.AGENT_UPDATE]: 'data-agent-update',
+ [ContentTypes.SUMMARY]: 'data-summary',
+ [ContentTypes.ACTIVITY_LABEL]: 'data-activity-label',
+ [ContentTypes.STEER]: 'data-steer',
+ [ContentTypes.ERROR]: 'data-error',
+};
+
+const lossless = Object.values(ContentTypes).filter((type) => type !== ContentTypes.TEXT_DELTA);
+
+/** A content array of `length` slots with only `slots` written, as the reducers leave it. */
+const sparse = (length: number, slots: Record<number, TMessageContentParts>) => {
+ const content: TMessageContentParts[] = new Array(length);
+ for (const [index, part] of Object.entries(slots)) {
+ content[Number(index)] = part;
+ }
+ return content;
+};
+
+/**
+ * Content arrays recorded from the stream reducers in
+ * `client/src/hooks/SSE/__tests__/steps.spec.ts` (text, tool calls, reasoning, handoff, summary,
+ * image scenarios), captured by running those reducers. Holes are where a later step arrived
+ * before an earlier one.
+ */
+const recorded: Record<string, TMessageContentParts[]> = {
+ toolCompleted: [
+ { type: ContentTypes.TEXT, text: 'Hi' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-1',
+ name: 'search',
+ args: '{"q":"cats"}',
+ stepId: 'step-tool',
+ type: 'tool_call',
+ progress: 1,
+ output: '3',
+ },
+ },
+ ],
+ toolStreaming: [
+ { type: ContentTypes.TEXT, text: 'Hi' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-1',
+ name: 'search',
+ args: '{"q":',
+ stepId: 'step-tool',
+ type: 'tool_call',
+ },
+ },
+ ],
+ toolCancelled: [
+ { type: ContentTypes.TEXT, text: 'Hi' },
+ {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-1',
+ name: 'search',
+ args: '{"q":"cats"}',
+ stepId: 'step-tool',
+ type: 'tool_call',
+ runStepStatus: 'cancelled',
+ runStepDurationMs: 250,
+ },
+ },
+ ],
+ outOfOrder: sparse(3, {
+ 0: { type: ContentTypes.TEXT, text: 'first' },
+ 2: { type: ContentTypes.TEXT, text: 'second' },
+ }),
+ reasoning: [
+ {
+ type: ContentTypes.THINK,
+ think: 'Let me think',
+ agentId: 'agent-a',
+ groupId: 2,
+ reasoning_label_step_id: 'step-think',
+ },
+ { type: ContentTypes.TEXT, text: 'Answer', agentId: 'agent-a', groupId: 2 },
+ ],
+ agentUpdate: [
+ { type: ContentTypes.TEXT, text: 'Hi' },
+ {
+ type: ContentTypes.AGENT_UPDATE,
+ agent_update: { index: 1, runId: 'response-1', agentId: 'agent-b' },
+ agentId: 'agent-b',
+ groupId: 1,
+ },
+ ],
+ summaryFailed: [
+ { type: ContentTypes.TEXT, text: 'Hi' },
+ {
+ type: ContentTypes.SUMMARY,
+ content: [
+ { type: ContentTypes.TEXT, text: 'Earlier, ' },
+ { type: ContentTypes.TEXT, text: 'we talked.' },
+ ],
+ summarizing: false,
+ failed: true,
+ },
+ { type: ContentTypes.TEXT, text: 'after' },
+ ],
+ imageUrl: [{ type: ContentTypes.IMAGE_URL, image_url: 'https://x/first.png' }],
+};
+
+const toolPartAt = (content: TMessageContentParts[], index: number) =>
+ toUIParts(content)[index] as UIToolPart;
+
+/** Deterministic PRNG so a failing generated case reproduces. */
+const createRandom = (seed: number) => {
+ let state = seed;
+ return () => {
+ state = (state * 1_103_515_245 + 12_345) % 2_147_483_648;
+ return state / 2_147_483_648;
+ };
+};
+
+const createMessage = (overrides: Partial<TMessage>): TMessage => ({
+ messageId: 'response-1',
+ conversationId: 'convo-1',
+ parentMessageId: 'user-1',
+ isCreatedByUser: false,
+ text: '',
+ ...overrides,
+});
+
+type ResolveToolFailure = NonNullable<UIMappingOptions['resolveToolFailure']>;
+
+describe('parts', () => {
+ describe('toUIPart', () => {
+ it.each(Object.values(ContentTypes))('maps %s to its UI part', (type) => {
+ expect(toUIPart(samples[type]).type).toBe(expectedUITypes[type]);
+ });
+
+ it.each(lossless)('round-trips %s', (type) => {
+ expect(fromUIPart(toUIPart(samples[type]))).toStrictEqual(samples[type]);
+ });
+
+ it('maps a streamed text delta to a streaming text part', () => {
+ expect(toUIPart(samples[ContentTypes.TEXT_DELTA])).toEqual({
+ type: 'text',
+ text: 'chunk',
+ state: 'streaming',
+ });
+ });
+
+ it('keeps the object form of text and its annotations', () => {
+ const part: TMessageContentParts = {
+ type: ContentTypes.TEXT,
+ text: {
+ value: 'See file',
+ annotations: [
+ {
+ type: 'file_path',
+ text: 'file',
+ start_index: 4,
+ end_index: 8,
+ file_path: { file_id: 'f' },
+ },
+ ],
+ },
+ };
+ const uiPart = toUIPart(part);
+
+ expect(uiPart).toMatchObject({ type: 'text', text: 'See file' });
+ expect(fromUIPart(uiPart)).toStrictEqual(part);
+ });
+
+ it('maps an untyped lane placeholder to step-start', () => {
+ const placeholder = { type: '' } as unknown as MappableContentPart;
+ const content = [
+ { type: ContentTypes.TEXT, text: 'a' },
+ placeholder,
+ ] as TMessageContentParts[];
+
+ expect(toUIPart(placeholder)).toEqual({ type: 'step-start' });
+ expect(toUIMessage(createMessage({ content })).parts).toEqual([
+ { type: 'text', text: 'a' },
+ { type: 'step-start' },
+ ]);
+ });
+
+ it('maps a tool call slot whose call has not arrived to step-start', () => {
+ const placeholder = { type: ContentTypes.TOOL_CALL } as unknown as MappableContentPart;
+ const content = [
+ { type: ContentTypes.TEXT, text: 'a' },
+ placeholder,
+ ] as TMessageContentParts[];
+
+ expect(toUIPart(placeholder)).toEqual({ type: 'step-start' });
+ expect(toUIMessage(createMessage({ content })).parts).toEqual([
+ { type: 'text', text: 'a' },
+ { type: 'step-start' },
+ ]);
+ });
+
+ it('maps a missing slot to step-start and step-start back to nothing', () => {
+ expect(toUIPart(undefined)).toEqual({ type: 'step-start' });
+ expect(fromUIPart({ type: 'step-start' })).toBeUndefined();
+ });
+
+ it('exposes the AI SDK fields of a file part', () => {
+ expect(toUIPart(samples[ContentTypes.IMAGE_FILE])).toMatchObject({
+ type: 'file',
+ mediaType: 'image/png',
+ filename: 'cat.png',
+ url: '/images/cat.png',
+ });
+ expect(toUIPart(samples[ContentTypes.INPUT_AUDIO])).toMatchObject({
+ mediaType: 'audio/wav',
+ url: 'data:audio/wav;base64,AAAA',
+ });
+ });
+
+ it('builds an agents tool call from a hand-made tool part', () => {
+ const part: UIToolPart = {
+ type: 'tool-search',
+ toolCallId: 'call-9',
+ state: 'output-available',
+ input: { q: 'dogs' },
+ output: '5',
+ };
+
+ expect(fromUIPart(part)).toEqual({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ type: 'tool_call',
+ name: 'search',
+ id: 'call-9',
+ args: '{"q":"dogs"}',
+ output: '5',
+ runStepStatus: 'completed',
+ },
+ });
+ });
+
+ it('names legacy assistants tool calls by their kind', () => {
+ const code = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'ci-1',
+ type: 'code_interpreter',
+ code_interpreter: { input: 'print(1)', outputs: [{ logs: '1' }] },
+ },
+ });
+ const fn = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'fn-1',
+ type: 'function',
+ function: { name: 'lookup', arguments: '{"id":1}', output: null },
+ },
+ });
+
+ expect(code).toMatchObject({
+ type: 'tool-code_interpreter',
+ toolCallId: 'ci-1',
+ state: 'output-available',
+ input: 'print(1)',
+ output: [{ logs: '1' }],
+ });
+ expect(fn).toMatchObject({
+ type: 'tool-lookup',
+ toolCallId: 'fn-1',
+ state: 'input-available',
+ input: { id: 1 },
+ });
+ });
+ });
+
+ describe('tool states from recorded streams', () => {
+ it('reports a completed call as output-available with parsed input', () => {
+ expect(toolPartAt(recorded.toolCompleted, 1)).toMatchObject({
+ type: 'tool-search',
+ toolCallId: 'call-1',
+ state: 'output-available',
+ input: { q: 'cats' },
+ output: '3',
+ });
+ });
+
+ it('reports partial arguments as input-streaming', () => {
+ expect(toolPartAt(recorded.toolStreaming, 1)).toMatchObject({
+ state: 'input-streaming',
+ input: '{"q":',
+ });
+ });
+
+ it('reports a cancelled step as output-error', () => {
+ expect(toolPartAt(recorded.toolCancelled, 1)).toMatchObject({
+ state: 'output-error',
+ errorText: 'cancelled',
+ input: { q: 'cats' },
+ });
+ });
+ });
+
+ describe('recorded reducer output', () => {
+ it.each(Object.entries(recorded))('%s keeps positions and round-trips', (_name, content) => {
+ const parts = toUIParts(content);
+
+ expect(parts).toHaveLength(content.length);
+ for (let i = 0; i < content.length; i++) {
+ const part = content[i] as MappableContentPart | undefined;
+ expect(parts[i].type).toBe(part ? expectedUITypes[part.type] : 'step-start');
+ }
+ expect(fromUIParts(parts)).toStrictEqual(content);
+ });
+ });
+
+ describe('generated content', () => {
+ const pool = lossless.map((type) => samples[type]);
+
+ it('preserves order, holes and every part over random content arrays', () => {
+ const random = createRandom(7);
+ for (let run = 0; run < 250; run++) {
+ const length = Math.floor(random() * 12);
+ const content: TMessageContentParts[] = new Array(length);
+ for (let i = 0; i < length; i++) {
+ if (random() < 0.2) {
+ continue;
+ }
+ content[i] = pool[Math.floor(random() * pool.length)] as TMessageContentParts;
+ }
+
+ const parts = toUIParts(content);
+ expect(parts).toHaveLength(length);
+ for (let i = 0; i < length; i++) {
+ const part = content[i] as MappableContentPart | undefined;
+ expect(parts[i].type).toBe(part ? expectedUITypes[part.type] : 'step-start');
+ }
+ expect(fromUIParts(parts)).toStrictEqual(content);
+ }
+ });
+ });
+
+ describe('toUIMessage', () => {
+ it('views a response with content, metadata, files and sources', () => {
+ const attachment = {
+ conversationId: 'convo-1',
+ messageId: 'response-1',
+ toolCallId: 'call-1',
+ type: Tools.web_search,
+ [Tools.web_search]: {
+ organic: [{ link: 'https://a.example', title: 'A' }],
+ topStories: [{ link: 'https://b.example' }],
+ },
+ } as TAttachment;
+ const content: TMessageContentParts[] = [
+ samples[ContentTypes.STEER] as TMessageContentParts,
+ ...recorded.reasoning,
+ samples[ContentTypes.AGENT_UPDATE] as TMessageContentParts,
+ samples[ContentTypes.ACTIVITY_LABEL] as TMessageContentParts,
+ samples[ContentTypes.SUMMARY] as TMessageContentParts,
+ ];
+ const message = createMessage({
+ content,
+ sender: 'Agent',
+ model: 'agent-a',
+ unfinished: true,
+ files: [{ filepath: '/files/report.pdf', filename: 'report.pdf', type: 'application/pdf' }],
+ attachments: [attachment],
+ });
+
+ const view = toUIMessage(message);
+
+ expect(view.id).toBe('response-1');
+ expect(view.role).toBe('assistant');
+ expect(view.parts.map((part) => part.type)).toEqual([
+ 'data-steer',
+ 'reasoning',
+ 'text',
+ 'data-agent-update',
+ 'data-activity-label',
+ 'data-summary',
+ 'file',
+ 'source-url',
+ 'source-url',
+ ]);
+ expect(view.parts.slice(-3)).toEqual([
+ {
+ type: 'file',
+ mediaType: 'application/pdf',
+ filename: 'report.pdf',
+ url: '/files/report.pdf',
+ providerMetadata: {
+ librechat: { source: 'attachment', filepath: '/files/report.pdf', index: 0 },
+ },
+ },
+ { type: 'source-url', sourceId: 'call-1-0', url: 'https://a.example', title: 'A' },
+ { type: 'source-url', sourceId: 'call-1-1', url: 'https://b.example' },
+ ]);
+ expect(view.metadata).toEqual({
+ conversationId: 'convo-1',
+ parentMessageId: 'user-1',
+ sender: 'Agent',
+ model: 'agent-a',
+ unfinished: true,
+ text: '',
+ attachments: [attachment],
+ agentIds: ['agent-a', 'agent-b'],
+ groupIds: [2, 1],
+ steers: [{ steer: 'Focus on cats', steerId: 's-1' }],
+ activityLabels: [
+ { activity_label: 'Searched the web', tool_call_ids: ['call-1'], status: 'ok' },
+ ],
+ summaries: [
+ {
+ content: [{ type: ContentTypes.TEXT, text: 'Earlier, we talked.' }],
+ summarizing: false,
+ },
+ ],
+ });
+ expect(fromUIMessage(view, message)).toStrictEqual(message);
+ });
+
+ it('views a contentless user message as its text and files', () => {
+ const message = createMessage({
+ messageId: 'user-1',
+ parentMessageId: null,
+ isCreatedByUser: true,
+ text: 'Describe this',
+ files: [{ filepath: '/images/cat.png', filename: 'cat.png', type: 'image/png' }],
+ });
+
+ const view = toUIMessage(message);
+
+ expect(view).toEqual({
+ id: 'user-1',
+ role: 'user',
+ metadata: { conversationId: 'convo-1', parentMessageId: null, contentless: true },
+ parts: [
+ { type: 'text', text: 'Describe this' },
+ {
+ type: 'file',
+ mediaType: 'image/png',
+ filename: 'cat.png',
+ url: '/images/cat.png',
+ providerMetadata: {
+ librechat: { source: 'attachment', filepath: '/images/cat.png', index: 0 },
+ },
+ },
+ ],
+ });
+ expect(fromUIMessage(view)).toEqual(message);
+ });
+
+ it('writes edited parts back onto the stored message', () => {
+ const message = createMessage({ content: recorded.toolCompleted, text: 'Hi' });
+ const view = toUIMessage(message);
+ const parts: UIMessagePart[] = [{ type: 'text', text: 'Hello' }, ...view.parts.slice(1)];
+
+ const next = fromUIMessage({ ...view, parts }, message);
+
+ expect(next.content?.[0]).toEqual({ type: ContentTypes.TEXT, text: 'Hello' });
+ expect(next.content?.[1]).toStrictEqual(recorded.toolCompleted[1]);
+ expect(next.parentMessageId).toBe('user-1');
+ });
+ });
+
+ describe('fromUIMessage', () => {
+ it('views an empty content array with text as contentless', () => {
+ const message = createMessage({ content: [], text: 'Legacy answer' });
+
+ const view = toUIMessage(message);
+
+ expect(view.parts).toEqual([{ type: 'text', text: 'Legacy answer' }]);
+ expect(view.metadata?.contentless).toBe(true);
+ expect(fromUIMessage(view, message)).toStrictEqual(message);
+ });
+
+ it('keeps an empty streaming placeholder as content', () => {
+ const message = createMessage({ content: [] });
+
+ const view = toUIMessage(message);
+
+ expect(view.parts).toEqual([]);
+ expect(fromUIMessage(view, message)).toStrictEqual(message);
+ });
+
+ it('updates the stored text when a text part is edited', () => {
+ const message = createMessage({
+ text: 'old',
+ content: [{ type: ContentTypes.TEXT, text: 'old' }],
+ });
+ const view = toUIMessage(message);
+
+ const next = fromUIMessage({ ...view, parts: [{ type: 'text', text: 'new' }] }, message);
+
+ expect(next.text).toBe('new');
+ expect(next.content).toEqual([{ type: ContentTypes.TEXT, text: 'new' }]);
+ });
+
+ it('keeps stored text that the parts do not derive', () => {
+ const message = createMessage({
+ text: 'stored summary',
+ content: [{ type: ContentTypes.TEXT, text: 'Answer' }],
+ });
+
+ expect(fromUIMessage(toUIMessage(message), message).text).toBe('stored summary');
+ });
+
+ it('applies removed and added attachments to a stored message', () => {
+ const kept = {
+ file_id: 'a',
+ filepath: '/files/a.pdf',
+ filename: 'a.pdf',
+ type: 'application/pdf',
+ };
+ const removed = {
+ file_id: 'b',
+ filepath: '/files/b.pdf',
+ filename: 'b.pdf',
+ type: 'application/pdf',
+ };
+ const unlisted = { file_id: 'c' };
+ const message = createMessage({
+ isCreatedByUser: true,
+ text: 'Files',
+ files: [kept, removed, unlisted],
+ });
+ const view = toUIMessage(message);
+ const parts: UIMessagePart[] = [
+ view.parts[0],
+ view.parts[1],
+ { type: 'file', mediaType: 'image/png', filename: 'new.png', url: '/images/new.png' },
+ ];
+
+ const next = fromUIMessage({ ...view, parts }, message);
+
+ expect(next.files).toEqual([
+ kept,
+ { filepath: '/images/new.png', filename: 'new.png', type: 'image/png' },
+ unlisted,
+ ]);
+ });
+
+ it('restores metadata fields when no stored message exists', () => {
+ const message = createMessage({
+ sender: 'Agent',
+ model: 'gpt-5',
+ endpoint: 'agents',
+ error: true,
+ unfinished: true,
+ createdAt: '2026-09-25T00:00:00.000Z',
+ content: [{ type: ContentTypes.TEXT, text: 'Partial' }],
+ });
+
+ expect(fromUIMessage(toUIMessage(message))).toStrictEqual(message);
+ });
+ });
+
+ describe('stored shapes', () => {
+ const toolCall = (fields: Partial<Agents.ToolCall> & PartMetadata): TMessageContentParts => ({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { type: 'tool_call', name: 'search', args: '{"q":"cats"}', ...fields },
+ });
+
+ it('falls back from an empty tool call id to the host step id', () => {
+ expect(toUIPart(toolCall({ id: '', stepId: 'step-7' }), 3)).toMatchObject({
+ toolCallId: 'step-7',
+ });
+ expect(toUIPart(toolCall({ id: '' }), 3)).toMatchObject({ toolCallId: 'tool_call-3' });
+ });
+
+ it('reports durable failure markers as output-error', () => {
+ const cancelled = toolCall({
+ id: 'call-1',
+ output: 'partial',
+ progress: 1,
+ backgroundTask: {
+ version: 1,
+ taskId: 't',
+ toolName: 'search',
+ status: 'completed',
+ cancelled: true,
+ settledAt: new Date(0),
+ },
+ });
+ const rejected = toolCall({ id: 'call-2', progress: 1, inputValidationError: true });
+
+ expect(toUIPart(cancelled)).toMatchObject({ state: 'output-error', errorText: 'cancelled' });
+ expect(toUIPart(rejected)).toMatchObject({
+ state: 'output-error',
+ errorText: 'input-validation-error',
+ });
+ });
+
+ it('reports a call paused for review as approval-requested', () => {
+ const paused = toolCall({
+ id: 'call-1',
+ approval: { actionId: 'action-1', allowed_decisions: ['approve'], description: 'Run it?' },
+ });
+
+ expect(toUIPart(paused)).toMatchObject({
+ state: 'approval-requested',
+ approval: { id: 'action-1', requestReason: 'Run it?' },
+ });
+ expect(fromUIPart(toUIPart(paused))).toStrictEqual(paused);
+ });
+
+ it('treats an empty legacy function output as submitted', () => {
+ const part = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'fn-1',
+ type: 'function',
+ function: { name: 'lookup', arguments: '{}', output: '' },
+ },
+ });
+
+ expect(part).toMatchObject({ state: 'output-available', output: '' });
+ });
+
+ it('views persisted reasoning without its think tags and restores them', () => {
+ const part = {
+ type: ContentTypes.THINK,
+ think: '<think>\nWeighing options\n</think>',
+ } as TMessageContentParts;
+ const bare = { type: ContentTypes.THINK, think: 'No tags' } as TMessageContentParts;
+
+ expect(toUIPart(part)).toMatchObject({ type: 'reasoning', text: 'Weighing options' });
+ expect(fromUIPart(toUIPart(part))).toStrictEqual(part);
+ expect(fromUIPart(toUIPart(bare))).toStrictEqual(bare);
+ });
+
+ it('keeps a text or think part without its text field', () => {
+ const text = { type: ContentTypes.TEXT } as TMessageContentParts;
+ const think = { type: ContentTypes.THINK } as TMessageContentParts;
+
+ expect(fromUIPart(toUIPart(text))).toStrictEqual(text);
+ expect(fromUIPart(toUIPart(think))).toStrictEqual(think);
+ });
+
+ it('persists the failure of a hand-built error tool part', () => {
+ const part: UIToolPart = {
+ type: 'tool-search',
+ toolCallId: 'call-9',
+ state: 'output-error',
+ input: { q: 'dogs' },
+ errorText: 'Timed out',
+ };
+
+ expect(toUIPart(fromUIPart(part))).toMatchObject({
+ state: 'output-error',
+ errorText: 'Timed out',
+ });
+ });
+
+ it('collects agents that own only a nested tool call', () => {
+ const message = createMessage({ content: [toolCall({ id: 'call-1', agentId: 'agent-z' })] });
+
+ expect(toUIMessage(message).metadata?.agentIds).toEqual(['agent-z']);
+ });
+ });
+
+ describe('sources', () => {
+ const search = (toolCallId: string, links: string[]) =>
+ ({
+ conversationId: 'convo-1',
+ messageId: 'response-1',
+ toolCallId,
+ type: Tools.web_search,
+ [Tools.web_search]: {
+ organic: links.map((link) => ({ link })),
+ references: [
+ { link: 'https://ref.example', type: 'link', title: 'Ref' },
+ { link: 'https://img.example/a.png', type: 'image' },
+ ],
+ },
+ }) as TAttachment;
+
+ it('gives distinct sources distinct ids when tool call ids repeat', () => {
+ const message = createMessage({
+ content: [{ type: ContentTypes.TEXT, text: 'Found' }],
+ attachments: [
+ search('call_0', ['https://a.example']),
+ search('call_0', ['https://b.example']),
+ ],
+ });
+
+ const sources = toUIMessage(message).parts.filter((part) => part.type === 'source-url');
+
+ expect(sources).toEqual([
+ { type: 'source-url', sourceId: 'call_0-0', url: 'https://a.example' },
+ { type: 'source-url', sourceId: 'call_0-1', url: 'https://ref.example', title: 'Ref' },
+ { type: 'source-url', sourceId: 'call_0-2', url: 'https://b.example' },
+ ]);
+ });
+ });
+
+ describe('edits through the view', () => {
+ it('writes image file edits back while keeping the stored record', () => {
+ const part = samples[ContentTypes.IMAGE_FILE] as TMessageContentParts;
+ const edited: UIMessagePart = {
+ ...(toUIPart(part) as Extract<UIMessagePart, { type: 'file' }>),
+ url: '/images/dog.png',
+ filename: 'dog.png',
+ };
+
+ expect(fromUIPart(edited)).toMatchObject({
+ type: ContentTypes.IMAGE_FILE,
+ image_file: { file_id: 'file-1', filepath: '/images/dog.png', filename: 'dog.png' },
+ });
+ });
+
+ it('writes attachment renames onto the matched stored file', () => {
+ const stored = {
+ file_id: 'a',
+ filepath: '/files/a.pdf',
+ filename: 'a.pdf',
+ type: 'application/pdf',
+ };
+ const message = createMessage({ isCreatedByUser: true, text: 'File', files: [stored] });
+ const view = toUIMessage(message);
+ const parts: UIMessagePart[] = [
+ view.parts[0],
+ {
+ type: 'file',
+ mediaType: 'application/pdf',
+ filename: 'renamed.pdf',
+ url: '/files/a.pdf',
+ },
+ ];
+
+ expect(fromUIMessage({ ...view, parts }, message).files).toEqual([
+ { ...stored, filename: 'renamed.pdf' },
+ ]);
+ });
+
+ it('keeps an explicit null parent instead of the stored one', () => {
+ const message = createMessage({
+ text: 'Hi',
+ content: [{ type: ContentTypes.TEXT, text: 'Hi' }],
+ });
+ const view = toUIMessage(message);
+
+ const next = fromUIMessage(
+ {
+ ...view,
+ metadata: { ...view.metadata, conversationId: 'convo-1', parentMessageId: null },
+ },
+ message,
+ );
+
+ expect(next.parentMessageId).toBeNull();
+ });
+
+ it('keeps stored text that the parts do not derive without a base', () => {
+ const message = createMessage({
+ text: 'stored summary',
+ content: [samples[ContentTypes.THINK] as TMessageContentParts],
+ });
+
+ expect(fromUIMessage(toUIMessage(message)).text).toBe('stored summary');
+ });
+ });
+
+ describe('legacy and edited shapes', () => {
+ it('keeps a null model through a base-less rebuild', () => {
+ const message = createMessage({
+ model: null,
+ text: 'Hi',
+ content: [{ type: ContentTypes.TEXT, text: 'Hi' }],
+ });
+
+ expect(fromUIMessage(toUIMessage(message))).toStrictEqual(message);
+ });
+
+ it('takes the audio format from an edited media type', () => {
+ const view = toUIPart(samples[ContentTypes.INPUT_AUDIO]) as Extract<
+ UIMessagePart,
+ { type: 'file' }
+ >;
+
+ expect(
+ fromUIPart({ ...view, mediaType: 'audio/mp3', url: 'data:audio/mp3;base64,BBBB' }),
+ ).toEqual({ type: ContentTypes.INPUT_AUDIO, input_audio: { data: 'BBBB', format: 'mp3' } });
+ });
+
+ it('gives sources and attachments no content slot', () => {
+ const parts: UIMessagePart[] = [
+ { type: 'text', text: 'a' },
+ { type: 'source-url', sourceId: 's', url: 'https://a.example' },
+ { type: 'file', mediaType: 'image/png', url: '/x.png' },
+ { type: 'text', text: 'b' },
+ { type: 'step-start' },
+ { type: 'text', text: 'c' },
+ ];
+
+ expect(fromUIParts(parts)).toStrictEqual(
+ sparse(4, {
+ 0: { type: ContentTypes.TEXT, text: 'a' },
+ 1: { type: ContentTypes.TEXT, text: 'b' },
+ 3: { type: ContentTypes.TEXT, text: 'c' },
+ }),
+ );
+ });
+
+ it('reports a legacy retrieval output as submitted', () => {
+ const part = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'r-1', type: 'retrieval', retrieval: {}, output: 'found' },
+ } as TMessageContentParts);
+
+ expect(part).toMatchObject({ state: 'output-available', output: 'found' });
+ });
+
+ it('reports an error-prefixed output as output-error', () => {
+ const part = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'call-1',
+ type: 'tool_call',
+ name: 'search',
+ args: '{}',
+ output: 'Error processing tool search: boom',
+ },
+ });
+
+ expect(part).toMatchObject({
+ state: 'output-error',
+ errorText: 'Error processing tool search: boom',
+ });
+ });
+
+ it('matches an attachment whose url was edited to its stored file', () => {
+ const stored = {
+ file_id: 'a',
+ filepath: '/files/a.pdf',
+ filename: 'a.pdf',
+ type: 'application/pdf',
+ };
+ const message = createMessage({ isCreatedByUser: true, text: 'File', files: [stored] });
+ const view = toUIMessage(message);
+ const attachment = view.parts[1] as Extract<UIMessagePart, { type: 'file' }>;
+ const parts: UIMessagePart[] = [view.parts[0], { ...attachment, url: '/files/moved.pdf' }];
+
+ expect(fromUIMessage({ ...view, parts }, message).files).toEqual([
+ { ...stored, filepath: '/files/moved.pdf' },
+ ]);
+ });
+ });
+
+ describe('rebuilds without a stored base', () => {
+ it('keeps a successful hand-built tool part successful', () => {
+ const part: UIToolPart = {
+ type: 'tool-search',
+ toolCallId: 'call-9',
+ state: 'output-available',
+ input: { q: 'dogs' },
+ };
+
+ expect(toUIPart(fromUIPart(part))).toMatchObject({ state: 'output-available' });
+ });
+
+ it('keeps an array output from a hand-built tool part', () => {
+ const part: UIToolPart = {
+ type: 'tool-code_interpreter',
+ toolCallId: 'ci-9',
+ state: 'output-available',
+ input: 'print(1)',
+ output: [{ logs: 'done' }],
+ };
+
+ expect(toUIPart(fromUIPart(part))).toMatchObject({
+ type: 'tool-code_interpreter',
+ state: 'output-available',
+ output: [{ logs: 'done' }],
+ });
+ });
+
+ it('keeps attachments and an empty content array', () => {
+ const attachment = {
+ conversationId: 'convo-1',
+ messageId: 'response-1',
+ toolCallId: 'call-1',
+ filename: 'notes.txt',
+ filepath: '/files/notes.txt',
+ } as TAttachment;
+ const message = createMessage({ content: [], text: 'Legacy', attachments: [attachment] });
+
+ expect(fromUIMessage(toUIMessage(message))).toStrictEqual(message);
+ });
+
+ it('keeps hidden files in their stored positions', () => {
+ const hidden = { file_id: 'h' };
+ const visible = {
+ file_id: 'v',
+ filepath: '/files/v.pdf',
+ filename: 'v.pdf',
+ type: 'application/pdf',
+ };
+ const message = createMessage({
+ isCreatedByUser: true,
+ text: 'Files',
+ files: [hidden, visible],
+ });
+
+ expect(fromUIMessage(toUIMessage(message), message).files).toEqual([hidden, visible]);
+ });
+ });
+
+ describe('caller-supplied tool outcomes', () => {
+ it('keeps ownership metadata on a streamed text delta', () => {
+ const part = {
+ type: ContentTypes.TEXT_DELTA,
+ text_delta: 'chunk',
+ agentId: 'agent-a',
+ groupId: 2,
+ } as MappableContentPart;
+
+ expect(toUIPart(part)).toEqual({
+ type: 'text',
+ text: 'chunk',
+ state: 'streaming',
+ providerMetadata: { librechat: { agentId: 'agent-a', groupId: 2 } },
+ });
+ });
+
+ it('keeps the object form and annotations of a streamed text delta', () => {
+ const annotations = [
+ {
+ type: 'file_citation',
+ text: 'cite',
+ start_index: 4,
+ end_index: 8,
+ file_citation: { file_id: 'f', quote: 'q' },
+ },
+ ];
+ const part = {
+ type: ContentTypes.TEXT_DELTA,
+ text_delta: { value: 'See cite', annotations },
+ } as MappableContentPart;
+ const uiPart = toUIPart(part);
+
+ expect(uiPart).toMatchObject({ type: 'text', text: 'See cite', state: 'streaming' });
+ expect(fromUIPart(uiPart)).toStrictEqual({
+ type: ContentTypes.TEXT,
+ text: { value: 'See cite', annotations },
+ });
+ });
+
+ it('marks an empty hand-built array output completed', () => {
+ const part: UIToolPart = {
+ type: 'tool-code_interpreter',
+ toolCallId: 'ci-9',
+ state: 'output-available',
+ input: 'print()',
+ output: [],
+ };
+
+ expect(toUIPart(fromUIPart(part))).toMatchObject({ state: 'output-available' });
+ });
+
+ it('applies a failure the caller resolves from its own rules', () => {
+ const memory: TMessageContentParts = {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'mem-1',
+ type: 'tool_call',
+ name: 'set_memory',
+ args: '{}',
+ output: 'Invalid key',
+ },
+ };
+ const message = createMessage({ content: [memory] });
+ const resolveToolFailure = jest.fn<string | undefined, Parameters<ResolveToolFailure>>(
+ (toolCall) =>
+ 'name' in toolCall && toolCall.name === 'set_memory' && toolCall.output !== 'Memory set'
+ ? toolCall.output
+ : undefined,
+ );
+
+ expect(toUIMessage(message).parts[0]).toMatchObject({ state: 'output-available' });
+ expect(toUIMessage(message, { resolveToolFailure }).parts[0]).toMatchObject({
+ state: 'output-error',
+ errorText: 'Invalid key',
+ });
+ expect(resolveToolFailure).toHaveBeenCalledWith(
+ expect.objectContaining({ id: 'mem-1' }),
+ message,
+ );
+ });
+ });
+
+ describe('failure reasons', () => {
+ const dispatchHandle = JSON.stringify({ taskId: 't-1', status: 'running' });
+ const detached = (fields: Partial<Agents.ToolCall> & PartMetadata): TMessageContentParts => ({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ id: 'bg-1',
+ type: 'tool_call',
+ name: 'bash',
+ args: '{}',
+ output: dispatchHandle,
+ progress: 1,
+ ...fields,
+ },
+ });
+
+ it('reports a cancelled background task by its reason, not its dispatch handle', () => {
+ const part = detached({
+ backgroundTask: {
+ version: 1,
+ taskId: 't-1',
+ toolName: 'bash',
+ status: 'completed',
+ cancelled: true,
+ settledAt: new Date(0),
+ },
+ });
+
+ expect(toUIPart(part)).toMatchObject({ state: 'output-error', errorText: 'cancelled' });
+ });
+
+ it('reports a caller-resolved failure by the reason the caller returns', () => {
+ const message = createMessage({ content: [detached({})] });
+ const resolveToolFailure: ResolveToolFailure = () => 'Task exited with code 1';
+
+ expect(toUIMessage(message, { resolveToolFailure }).parts[0]).toMatchObject({
+ state: 'output-error',
+ errorText: 'Task exited with code 1',
+ });
+ });
+
+ it('keeps a failed step output as the error text', () => {
+ const part = detached({ output: 'partial', runStepStatus: 'failed' });
+
+ expect(toUIPart(part)).toMatchObject({ state: 'output-error', errorText: 'partial' });
+ });
+ });
+
+ describe('identity and additions', () => {
+ it('keeps two stored files that share a path distinct', () => {
+ const first = {
+ file_id: 'a',
+ filepath: '/files/same.pdf',
+ filename: 'first.pdf',
+ type: 'application/pdf',
+ };
+ const second = {
+ file_id: 'b',
+ filepath: '/files/same.pdf',
+ filename: 'second.pdf',
+ type: 'application/pdf',
+ };
+ const message = createMessage({
+ isCreatedByUser: true,
+ text: 'Files',
+ files: [first, second],
+ });
+
+ expect(fromUIMessage(toUIMessage(message), message)).toStrictEqual(message);
+ });
+
+ it('writes content added to a contentless message', () => {
+ const message = createMessage({ isCreatedByUser: false, text: 'Plain' });
+ const view = toUIMessage(message);
+ const tool: UIToolPart = {
+ type: 'tool-search',
+ toolCallId: 'call-1',
+ state: 'input-available',
+ input: { q: 'x' },
+ };
+
+ const next = fromUIMessage({ ...view, parts: [...view.parts, tool] }, message);
+
+ expect(next.content?.map((part) => part.type)).toEqual([
+ ContentTypes.TEXT,
+ ContentTypes.TOOL_CALL,
+ ]);
+ expect(next.text).toBe('Plain');
+ });
+
+ it('keeps primitive JSON arguments as their string', () => {
+ const part = toUIPart({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'call-1', type: 'tool_call', name: 'count', args: '42' },
+ });
+
+ expect(part).toMatchObject({ input: '42', state: 'input-available' });
+ });
+ });
+
+ describe('stable identities', () => {
+ it('derives a fallback tool call id from the streamed index', () => {
+ const part = {
+ type: ContentTypes.TOOL_CALL,
+ streamedIndex: 3,
+ tool_call: { type: 'tool_call', name: 'search', args: '{}' },
+ } as TMessageContentParts;
+
+ expect(toUIPart(part, 2)).toMatchObject({ toolCallId: 'tool_call-3' });
+ });
+
+ it('drops annotations once their text is edited', () => {
+ const annotations = [
+ {
+ type: 'file_path' as const,
+ text: 'file',
+ start_index: 4,
+ end_index: 8,
+ file_path: { file_id: 'f' },
+ },
+ ];
+ const part = {
+ type: ContentTypes.TEXT,
+ text: { value: 'See file', annotations },
+ } as TMessageContentParts;
+ const view = toUIPart(part) as Extract<UIMessagePart, { type: 'text' }>;
+
+ expect(fromUIPart(view)).toStrictEqual(part);
+ expect(fromUIPart({ ...view, text: 'Rewritten' })).toEqual({
+ type: ContentTypes.TEXT,
+ text: { value: 'Rewritten' },
+ });
+ });
+ });
+
+ it('narrows tool and data parts', () => {
+ const parts = toUIParts(recorded.agentUpdate.concat(recorded.toolCompleted[1]));
+
+ expect(parts.filter(isUIDataPart).map((part) => part.type)).toEqual(['data-agent-update']);
+ expect(parts.filter(isUIToolPart).map((part) => part.toolCallId)).toEqual(['call-1']);
+ });
+});
diff --git a/packages/data-provider/src/parts.ts b/packages/data-provider/src/parts.ts
new file mode 100644
index 0000000000..a605a90070
--- /dev/null
+++ b/packages/data-provider/src/parts.ts
@@ -0,0 +1,1065 @@
+import type { TMessageContentParts, ContentMetadata, TextData, Text } from './types/content';
+import type { TMessage, TAttachment } from './schemas';
+import type { Agents } from './types/agents';
+import type { TFile } from './types/files';
+import { ContentTypes, ToolCallTypes } from './types/runs';
+import { isToolErrorOutput } from './errors';
+import { Tools } from './types/tools';
+
+/**
+ * A UI parts view of LibreChat message content, modelled on the AI SDK `UIMessage`.
+ *
+ * Matched against `[email protected]` (`UIMessage`, `UIMessagePart`, `UIToolInvocation`) and
+ * `@ai-sdk/[email protected]` (`useChat`). The shapes are structural copies, not imports: this
+ * package does not depend on the AI SDK.
+ *
+ * Position invariant: `toUIParts(content)[i]` is the part for `content[i]`, holes included, so an
+ * index-derived identity (the step index the stream reducers write to) survives the mapping.
+ * A hole becomes a `step-start` part and maps back to a hole. Parts that have no content slot
+ * (message files, web search sources) are appended after the last content part.
+ */
+
+/** Stream-only text chunk; never persisted, but it can appear in a message being built. */
+export type TextDeltaContentPart = {
+ type: ContentTypes.TEXT_DELTA;
+ text?: string | TextData;
+ text_delta?: string | TextData;
+} & ContentMetadata;
+
+/** Every content part the mapping accepts. */
+export type MappableContentPart = TMessageContentParts | TextDeltaContentPart;
+
+type ContentPartOf<T extends ContentTypes> = Extract<MappableContentPart, { type: T }>;
+type ToolCallContentPart = ContentPartOf<ContentTypes.TOOL_CALL>;
+type ToolCallValue = ToolCallContentPart['tool_call'];
+
+/** AI SDK `providerMetadata`, keyed by provider; LibreChat keeps its own fields under one key. */
+export type LibreChatProviderMetadata<T> = { librechat: T };
+
+/** Fields of a `TextData` object other than its value, kept so the object form round-trips. */
+type TextObjectFields = Omit<NonNullable<TextData>, 'value'>;
+
+/** How the stored text field was shaped, so the reverse mapping restores that shape. */
+type TextShape = {
+ textObject?: TextObjectFields;
+ /** The stored part had no text field at all, which is not the same as an empty string. */
+ textAbsent?: true;
+ /** The value the stored annotations index into; an edit away from it drops them. */
+ annotatedValue?: string;
+};
+
+export type UITextPartMetadata = Omit<ContentPartOf<ContentTypes.TEXT>, 'type' | 'text'> &
+ TextShape;
+
+/** The `<think>` wrapper persisted reasoning carries, exactly as stored, so it can be restored. */
+type ThinkWrapper = { thinkOpen?: string; thinkClose?: string };
+
+export type UIReasoningPartMetadata = Omit<ContentPartOf<ContentTypes.THINK>, 'type' | 'think'> &
+ TextShape &
+ ThinkWrapper;
+
+/** AI SDK `TextUIPart`. */
+export type UITextPart = {
+ type: 'text';
+ text: string;
+ state?: 'streaming' | 'done';
+ providerMetadata?: LibreChatProviderMetadata<UITextPartMetadata>;
+};
+
+/** AI SDK `ReasoningUIPart`. */
+export type UIReasoningPart = {
+ type: 'reasoning';
+ text: string;
+ state?: 'streaming' | 'done';
+ providerMetadata?: LibreChatProviderMetadata<UIReasoningPartMetadata>;
+};
+
+/** The content part a `file` UI part was mapped from, when it came from content. */
+export type UIFilePartMetadata =
+ | ({ source: ContentTypes.IMAGE_FILE } & Omit<ContentPartOf<ContentTypes.IMAGE_FILE>, 'type'>)
+ | ({ source: ContentTypes.IMAGE_URL; urlObject: boolean } & Omit<
+ ContentPartOf<ContentTypes.IMAGE_URL>,
+ 'type' | 'image_url'
+ > & { detail?: Agents.ImageDetail })
+ | ({ source: ContentTypes.VIDEO_URL } & Omit<
+ ContentPartOf<ContentTypes.VIDEO_URL>,
+ 'type' | 'video_url'
+ >)
+ | ({ source: ContentTypes.INPUT_AUDIO; format: string } & Omit<
+ ContentPartOf<ContentTypes.INPUT_AUDIO>,
+ 'type' | 'input_audio'
+ >)
+ /**
+ * A `message.files` entry: `index` is its position in the stored array and `filepath` the path
+ * it was viewed with, together its identity across edits even when two entries share a path.
+ */
+ | { source: 'attachment'; filepath: string; index: number };
+
+/**
+ * AI SDK `FileUIPart`. A part from a content slot names its content type as `source`; one with
+ * `source: 'attachment'`, or no metadata at all (built by hand), is a message attachment.
+ */
+export type UIFilePart = {
+ type: 'file';
+ mediaType: string;
+ filename?: string;
+ url: string;
+ providerMetadata?: LibreChatProviderMetadata<UIFilePartMetadata>;
+};
+
+/** AI SDK `SourceUrlUIPart`; built from web search attachments. */
+export type UISourceUrlPart = {
+ type: 'source-url';
+ sourceId: string;
+ url: string;
+ title?: string;
+};
+
+/** AI SDK `StepStartUIPart`; stands in for a content slot no step has written yet. */
+export type UIStepStartPart = { type: 'step-start' };
+
+/** The subset of AI SDK tool states LibreChat content can express. */
+export type UIToolState =
+ | 'input-streaming'
+ | 'input-available'
+ | 'approval-requested'
+ | 'output-available'
+ | 'output-error';
+
+/** AI SDK tool `approval`, for a call paused for human review. */
+export type UIToolApproval = { id: string; requestReason?: string };
+
+export type UIToolInput = Agents.ToolCall['args'] | object;
+export type UIToolOutput = string | CodeInterpreterOutputs;
+type CodeInterpreterOutputs = Extract<
+ ToolCallValue,
+ { type: 'code_interpreter' }
+>['code_interpreter']['outputs'];
+
+export type UIToolPartMetadata = Omit<ToolCallContentPart, 'type' | 'tool_call'> & {
+ /** The call as stored, so the reverse mapping restores fields the UI part does not carry. */
+ toolCall: ToolCallValue;
+};
+
+/**
+ * AI SDK `ToolUIPart`: `tool-<name>` with a lifecycle `state`. Cancelled, failed, rejected and
+ * background-cancelled calls all surface as `output-error`; the exact marker stays on the stored
+ * call. A call paused for human review is `approval-requested`.
+ */
+export type UIToolPart = {
+ type: `tool-${string}`;
+ toolCallId: string;
+ state: UIToolState;
+ input?: UIToolInput;
+ output?: UIToolOutput;
+ errorText?: string;
+ approval?: UIToolApproval;
+ callProviderMetadata?: LibreChatProviderMetadata<UIToolPartMetadata>;
+};
+
+type DataOf<T extends ContentTypes> = Omit<ContentPartOf<T>, 'type'>;
+
+/** AI SDK `DataUIPart`: LibreChat parts with no AI SDK counterpart, carried whole. */
+export type UIDataPart =
+ | { type: 'data-agent-update'; data: DataOf<ContentTypes.AGENT_UPDATE> }
+ | { type: 'data-summary'; data: DataOf<ContentTypes.SUMMARY> }
+ | { type: 'data-activity-label'; data: DataOf<ContentTypes.ACTIVITY_LABEL> }
+ | { type: 'data-steer'; data: DataOf<ContentTypes.STEER> }
+ | { type: 'data-error'; data: DataOf<ContentTypes.ERROR> };
+
+/** AI SDK `UIMessagePart`, narrowed to what LibreChat content produces. */
+export type UIMessagePart =
+ | UITextPart
+ | UIReasoningPart
+ | UIToolPart
+ | UIFilePart
+ | UISourceUrlPart
+ | UIStepStartPart
+ | UIDataPart;
+
+/** What a `TMessage` carries that `UIMessage` has no field for. */
+export type UIMessageMetadata = Pick<
+ TMessage,
+ | 'conversationId'
+ | 'parentMessageId'
+ | 'sender'
+ | 'model'
+ | 'endpoint'
+ | 'error'
+ | 'unfinished'
+ | 'createdAt'
+> & {
+ /** Set when the message had no `content`, so its parts were built from `text` and `files`. */
+ contentless?: boolean;
+ /**
+ * The stored `text` of a content-bearing message, present only when it differs from the text
+ * parts joined, so a rebuild without a stored base keeps it.
+ */
+ text?: string;
+ /** Set when a contentless message stored `content: []` rather than no `content` at all. */
+ emptyContent?: true;
+ /** The stored attachments, carried whole so a rebuild without a stored base keeps them. */
+ attachments?: TAttachment[];
+ /** Agents that produced parts of this message, in order of first appearance. */
+ agentIds?: string[];
+ /** Parallel content groups present in this message, in order of first appearance. */
+ groupIds?: number[];
+ activityLabels?: DataOf<ContentTypes.ACTIVITY_LABEL>[];
+ steers?: DataOf<ContentTypes.STEER>[];
+ summaries?: DataOf<ContentTypes.SUMMARY>[];
+};
+
+/**
+ * AI SDK `UIMessage`. `role` omits the AI SDK's `system`: a `TMessage` is either created by the
+ * user or not, so a system role could not survive the reverse mapping.
+ */
+export type UIMessage = {
+ id: string;
+ role: 'user' | 'assistant';
+ metadata?: UIMessageMetadata;
+ parts: UIMessagePart[];
+};
+
+type DataPartType = UIDataPart['type'];
+
+const dataPartTypes = {
+ [ContentTypes.AGENT_UPDATE]: 'data-agent-update',
+ [ContentTypes.SUMMARY]: 'data-summary',
+ [ContentTypes.ACTIVITY_LABEL]: 'data-activity-label',
+ [ContentTypes.STEER]: 'data-steer',
+ [ContentTypes.ERROR]: 'data-error',
+} as const satisfies Partial<Record<ContentTypes, DataPartType>>;
+
+const contentTypesByDataPart: Record<DataPartType, keyof typeof dataPartTypes> = {
+ 'data-agent-update': ContentTypes.AGENT_UPDATE,
+ 'data-summary': ContentTypes.SUMMARY,
+ 'data-activity-label': ContentTypes.ACTIVITY_LABEL,
+ 'data-steer': ContentTypes.STEER,
+ 'data-error': ContentTypes.ERROR,
+};
+
+const stepStart: UIStepStartPart = { type: 'step-start' };
+
+export const isUIToolPart = (part: UIMessagePart): part is UIToolPart =>
+ part.type.startsWith('tool-');
+
+export const isUIDataPart = (part: UIMessagePart): part is UIDataPart =>
+ part.type.startsWith('data-');
+
+const hasKeys = (value: object) => Object.keys(value).length > 0;
+
+const withLibreChatMetadata = <P extends object, M extends object>(part: P, metadata: M) =>
+ hasKeys(metadata) ? { ...part, providerMetadata: { librechat: metadata } } : part;
+
+const splitText = (text: string | TextData | undefined): { value: string } & TextShape => {
+ if (text === undefined) {
+ return { value: '', textAbsent: true };
+ }
+ if (text == null || typeof text === 'string') {
+ return { value: text ?? '' };
+ }
+ const { value, ...textObject } = text;
+ const stored = value ?? '';
+ return {
+ value: stored,
+ textObject,
+ ...((textObject.annotations?.length ?? 0) > 0 && { annotatedValue: stored }),
+ };
+};
+
+/** Restores the stored text field; `undefined` means the field is left off the part. */
+const joinText = (value: string, shape: TextShape): string | Text | undefined => {
+ if (shape.textAbsent && value === '') {
+ return undefined;
+ }
+ if (!shape.textObject) {
+ return value;
+ }
+ if (shape.annotatedValue !== undefined && value !== shape.annotatedValue) {
+ const { annotations: _stale, ...textObject } = shape.textObject;
+ return { ...textObject, value };
+ }
+ return { ...shape.textObject, value };
+};
+
+const thinkOpenPattern = /^\s*<think>\s*/;
+const thinkClosePattern = /\s*<\/think>\s*$/;
+
+/**
+ * Persisted reasoning is stored inside `<think>` tags, which every renderer strips; the view
+ * exposes the reasoning alone and keeps the exact wrapper for the reverse mapping.
+ */
+const splitThinkTags = (value: string): { value: string } & ThinkWrapper => {
+ const open = value.match(thinkOpenPattern)?.[0];
+ const inner = open ? value.slice(open.length) : value;
+ const close = inner.match(thinkClosePattern)?.[0];
+ return {
+ value: close ? inner.slice(0, inner.length - close.length) : inner,
+ ...(open && { thinkOpen: open }),
+ ...(close && { thinkClose: close }),
+ };
+};
+
+const toTextMetadata = <M extends object>(rest: M, shape: TextShape) => ({
+ ...rest,
+ ...(shape.textObject && { textObject: shape.textObject }),
+ ...(shape.textAbsent && { textAbsent: shape.textAbsent }),
+ ...(shape.annotatedValue !== undefined && { annotatedValue: shape.annotatedValue }),
+});
+
+const parseToolInput = (args: UIToolInput | undefined) => {
+ if (typeof args !== 'string') {
+ return { input: args, complete: args != null };
+ }
+ try {
+ const parsed: unknown = JSON.parse(args);
+ return {
+ input: typeof parsed === 'object' && parsed !== null ? (parsed as object) : args,
+ complete: true,
+ };
+ } catch {
+ return { input: args, complete: false };
+ }
+};
+
+type ToolCallFields = {
+ name: string;
+ id?: string;
+ args?: UIToolInput;
+ output?: UIToolOutput;
+ /** Whether the call's output was submitted, by that variant's own sentinel. */
+ submitted: boolean;
+};
+
+const readToolCall = (toolCall: ToolCallValue): ToolCallFields => {
+ switch (toolCall.type) {
+ case 'function':
+ return {
+ name: toolCall.function.name,
+ id: toolCall.id || undefined,
+ args: toolCall.function.arguments,
+ output: toolCall.function.output ?? undefined,
+ submitted: toolCall.function.output != null,
+ };
+ case 'code_interpreter':
+ return {
+ name: toolCall.type,
+ id: toolCall.id || undefined,
+ args: toolCall.code_interpreter.input,
+ output: toolCall.code_interpreter.outputs,
+ submitted: toolCall.code_interpreter.outputs.length > 0,
+ };
+ case 'retrieval':
+ case 'file_search': {
+ const output =
+ 'output' in toolCall && typeof toolCall.output === 'string' ? toolCall.output : undefined;
+ return { name: toolCall.type, id: toolCall.id || undefined, output, submitted: !!output };
+ }
+ default:
+ return {
+ name: toolCall.name,
+ id: toolCall.id || toolCall.stepId || undefined,
+ args: toolCall.args,
+ output: toolCall.output,
+ submitted: toolCall.output != null && toolCall.output !== '',
+ };
+ }
+};
+
+/**
+ * The failure a stored call records, if any: a failed or cancelled run step, an output the tool
+ * renderers read as an error, a cancelled background task, or arguments rejected by validation.
+ */
+/**
+ * Options for the forward mapping. Some tool outcomes are decided by knowledge this package does
+ * not hold, such as a memory tool's failure prose or a background task's status attachment; the
+ * caller that owns those rules supplies them here rather than the mapping copying them.
+ */
+export type UIMappingOptions = {
+ /**
+ * Returns a failure reason for a tool call the stored markers leave successful, or `undefined`.
+ * The reason becomes the part's `errorText`, since the stored output (a background dispatch
+ * handle, prose that reads as success) is not what established the failure; return the output
+ * itself when it is the message to show. It receives the stored call; `toUIMessage` also passes
+ * the message, for its attachments.
+ */
+ resolveToolFailure?: (toolCall: ToolCallValue, message?: TMessage) => string | undefined;
+};
+
+type MappingContext = UIMappingOptions & { message?: TMessage };
+
+/**
+ * `detail` says whether the stored output describes the failure (a failed step's partial output, an
+ * error the tool returned); when it does not, as with a cancelled background task whose output is
+ * the benign dispatch handle, the view reports the reason instead.
+ */
+type ToolFailure = { reason: string; detail: boolean };
+
+const getToolFailure = (
+ toolCall: ToolCallValue,
+ output?: UIToolOutput,
+): ToolFailure | undefined => {
+ const { runStepStatus } = toolCall;
+ if (runStepStatus === 'failed' || runStepStatus === 'cancelled') {
+ return { reason: runStepStatus, detail: true };
+ }
+ if (typeof output === 'string' && isToolErrorOutput(output)) {
+ return { reason: 'failed', detail: true };
+ }
+ if (!('name' in toolCall)) {
+ return undefined;
+ }
+ if (toolCall.backgroundTask?.cancelled) {
+ return { reason: 'cancelled', detail: false };
+ }
+ return toolCall.inputValidationError
+ ? { reason: 'input-validation-error', detail: true }
+ : undefined;
+};
+
+/** A caller-resolved failure is known from outside the output, so its reason is what the view shows. */
+const resolveFailure = (
+ toolCall: ToolCallValue,
+ output: UIToolOutput | undefined,
+ context?: MappingContext,
+): ToolFailure | undefined => {
+ const stored = getToolFailure(toolCall, output);
+ if (stored) {
+ return stored;
+ }
+ const reason = context?.resolveToolFailure?.(toolCall, context.message);
+ return reason ? { reason, detail: false } : undefined;
+};
+
+const getToolApproval = (toolCall: ToolCallValue): UIToolApproval | undefined => {
+ if (!('name' in toolCall) || !toolCall.approval) {
+ return undefined;
+ }
+ const { actionId, description } = toolCall.approval;
+ return { id: actionId, ...(description && { requestReason: description }) };
+};
+
+const toToolPart = (
+ part: ToolCallContentPart,
+ index: number,
+ context?: MappingContext,
+): UIToolPart => {
+ const { tool_call: toolCall, type: _type, ...partMetadata } = part;
+ const { name, id, args, output, submitted } = readToolCall(toolCall);
+ const { input, complete } = parseToolInput(args);
+ const { runStepStatus, progress } = toolCall;
+ const failure = resolveFailure(toolCall, output, context);
+ const approval = submitted ? undefined : getToolApproval(toolCall);
+
+ let state: UIToolState = complete ? 'input-available' : 'input-streaming';
+ if (failure) {
+ state = 'output-error';
+ } else if (submitted || runStepStatus === 'completed' || (progress ?? 0) >= 1) {
+ state = 'output-available';
+ } else if (approval) {
+ state = 'approval-requested';
+ }
+
+ return {
+ type: `tool-${name}`,
+ toolCallId: id || `${ContentTypes.TOOL_CALL}-${part.streamedIndex ?? index}`,
+ state,
+ ...(input !== undefined && { input }),
+ ...(state === 'output-available' && output !== undefined && { output }),
+ ...(state === 'output-error' && {
+ errorText: failure?.detail && typeof output === 'string' && output ? output : failure?.reason,
+ }),
+ ...(state === 'approval-requested' && { approval }),
+ callProviderMetadata: { librechat: { ...partMetadata, toolCall } },
+ };
+};
+
+const toDataPart = (part: ContentPartOf<keyof typeof dataPartTypes>): UIDataPart => {
+ const { type, ...data } = part;
+ return { type: dataPartTypes[type], data } as UIDataPart;
+};
+
+/**
+ * Maps one content part to its UI part. A missing part (a hole in a streamed array) maps to
+ * `step-start`, so indexes line up with the content array. So does a slot with no known type,
+ * such as the `type: ''` lane placeholder a dual-conversation turn seeds, and a tool call slot
+ * whose call has not arrived yet: persistence compacts those away, and the reverse mapping leaves
+ * a hole in their place the same way.
+ */
+export function toUIPart(
+ part: MappableContentPart | null | undefined,
+ index = 0,
+ options?: UIMappingOptions,
+): UIMessagePart {
+ if (part == null) {
+ return stepStart;
+ }
+ switch (part.type) {
+ case ContentTypes.TEXT: {
+ const { type: _type, text, ...rest } = part;
+ const { value, ...shape } = splitText(text);
+ return withLibreChatMetadata(
+ { type: 'text', text: value } satisfies UITextPart,
+ toTextMetadata(rest, shape),
+ );
+ }
+ case ContentTypes.TEXT_DELTA: {
+ const { type: _type, text, text_delta: textDelta, ...rest } = part;
+ const { value, ...shape } = splitText(textDelta ?? text);
+ return withLibreChatMetadata(
+ { type: 'text', text: value, state: 'streaming' } satisfies UITextPart,
+ toTextMetadata(rest, shape),
+ );
+ }
+ case ContentTypes.THINK: {
+ const { type: _type, think, ...rest } = part;
+ const { value: raw, ...shape } = splitText(think);
+ const { value, ...wrapper } = splitThinkTags(raw);
+ return withLibreChatMetadata({ type: 'reasoning', text: value } satisfies UIReasoningPart, {
+ ...toTextMetadata(rest, shape),
+ ...wrapper,
+ });
+ }
+ case ContentTypes.TOOL_CALL:
+ return part.tool_call == null ? stepStart : toToolPart(part, index, options);
+ case ContentTypes.IMAGE_FILE: {
+ const { type: _type, ...rest } = part;
+ const { image_file: imageFile } = rest;
+ return {
+ type: 'file',
+ mediaType: imageFile.type || 'image/*',
+ filename: imageFile.filename,
+ url: imageFile.filepath,
+ providerMetadata: { librechat: { source: ContentTypes.IMAGE_FILE, ...rest } },
+ };
+ }
+ case ContentTypes.IMAGE_URL: {
+ const { type: _type, image_url: imageUrl, ...rest } = part;
+ const urlObject = typeof imageUrl !== 'string';
+ const detail = urlObject ? imageUrl.detail : undefined;
+ return {
+ type: 'file',
+ mediaType: 'image/*',
+ url: urlObject ? imageUrl.url : imageUrl,
+ providerMetadata: {
+ librechat: {
+ source: ContentTypes.IMAGE_URL,
+ urlObject,
+ ...(detail !== undefined && { detail }),
+ ...rest,
+ },
+ },
+ };
+ }
+ case ContentTypes.VIDEO_URL: {
+ const { type: _type, video_url: videoUrl, ...rest } = part;
+ return {
+ type: 'file',
+ mediaType: 'video/*',
+ url: videoUrl.url,
+ providerMetadata: { librechat: { source: ContentTypes.VIDEO_URL, ...rest } },
+ };
+ }
+ case ContentTypes.INPUT_AUDIO: {
+ const { type: _type, input_audio: audio, ...rest } = part;
+ return {
+ type: 'file',
+ mediaType: `audio/${audio.format}`,
+ url: `data:audio/${audio.format};base64,${audio.data}`,
+ providerMetadata: {
+ librechat: { source: ContentTypes.INPUT_AUDIO, format: audio.format, ...rest },
+ },
+ };
+ }
+ case ContentTypes.AGENT_UPDATE:
+ case ContentTypes.SUMMARY:
+ case ContentTypes.ACTIVITY_LABEL:
+ case ContentTypes.STEER:
+ case ContentTypes.ERROR:
+ return toDataPart(part);
+ }
+ return stepStart;
+}
+
+/** Maps a content array to UI parts, one per slot, holes included. */
+export function toUIParts(
+ content: ReadonlyArray<MappableContentPart | null | undefined>,
+ options?: UIMappingOptions,
+) {
+ const parts: UIMessagePart[] = new Array(content.length);
+ for (let i = 0; i < content.length; i++) {
+ parts[i] = toUIPart(content[i], i, options);
+ }
+ return parts;
+}
+
+/**
+ * Writes the view's `url`, `filename` and `mediaType` onto a stored file record where they differ
+ * from what the forward mapping derived, so an edit lands and an untouched part round-trips.
+ */
+const applyFileEdits = <F extends Partial<TFile>>(
+ file: F,
+ part: UIFilePart,
+ fallbackType: string,
+) => {
+ const edited = { ...file };
+ if (part.url !== file.filepath) {
+ edited.filepath = part.url;
+ }
+ if (part.filename !== undefined && part.filename !== file.filename) {
+ edited.filename = part.filename;
+ }
+ if (part.mediaType !== (file.type || fallbackType)) {
+ edited.type = part.mediaType;
+ }
+ return edited;
+};
+
+const fromFilePart = (
+ part: UIFilePart,
+ metadata: UIFilePartMetadata,
+): TMessageContentParts | undefined => {
+ switch (metadata.source) {
+ case 'attachment':
+ return undefined;
+ case ContentTypes.IMAGE_FILE: {
+ const { source: _source, image_file: imageFile, ...rest } = metadata;
+ return {
+ type: ContentTypes.IMAGE_FILE,
+ image_file: applyFileEdits(imageFile, part, 'image/*'),
+ ...rest,
+ };
+ }
+ case ContentTypes.IMAGE_URL: {
+ const { source: _source, urlObject, detail, ...rest } = metadata;
+ const url = part.url;
+ const imageUrl = urlObject ? { url, ...(detail !== undefined && { detail }) } : url;
+ return { type: ContentTypes.IMAGE_URL, image_url: imageUrl, ...rest };
+ }
+ case ContentTypes.VIDEO_URL: {
+ const { source: _source, ...rest } = metadata;
+ return { type: ContentTypes.VIDEO_URL, video_url: { url: part.url }, ...rest };
+ }
+ case ContentTypes.INPUT_AUDIO: {
+ const { source: _source, format: storedFormat, ...rest } = metadata;
+ const data = part.url.slice(part.url.indexOf(',') + 1);
+ const format = part.mediaType.startsWith('audio/')
+ ? part.mediaType.slice('audio/'.length)
+ : storedFormat;
+ return { type: ContentTypes.INPUT_AUDIO, input_audio: { data, format }, ...rest };
+ }
+ }
+};
+
+const fromToolPart = (part: UIToolPart): TMessageContentParts => {
+ const stored = part.callProviderMetadata?.librechat;
+ if (stored) {
+ const { toolCall, ...partMetadata } = stored;
+ return { type: ContentTypes.TOOL_CALL, tool_call: toolCall, ...partMetadata };
+ }
+ const name = part.type.slice('tool-'.length);
+ if (Array.isArray(part.output)) {
+ return {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ type: ToolCallTypes.CODE_INTERPRETER,
+ id: part.toolCallId,
+ code_interpreter: {
+ input: typeof part.input === 'string' ? part.input : JSON.stringify(part.input ?? ''),
+ outputs: part.output,
+ },
+ ...(part.state === 'output-error' && { runStepStatus: 'failed' as const }),
+ ...(part.state === 'output-available' && { runStepStatus: 'completed' as const }),
+ },
+ };
+ }
+ const output = typeof part.output === 'string' ? part.output : part.errorText;
+ return {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: {
+ type: ToolCallTypes.TOOL_CALL,
+ name,
+ id: part.toolCallId,
+ ...(part.input !== undefined && {
+ args: typeof part.input === 'string' ? part.input : JSON.stringify(part.input),
+ }),
+ ...(output !== undefined && { output }),
+ ...(part.state === 'output-error' && { runStepStatus: 'failed' as const }),
+ ...(part.state === 'output-available' && { runStepStatus: 'completed' as const }),
+ ...(part.approval && {
+ approval: {
+ actionId: part.approval.id,
+ allowed_decisions: [],
+ ...(part.approval.requestReason && { description: part.approval.requestReason }),
+ },
+ }),
+ },
+ };
+};
+
+/**
+ * Maps a UI part back to content. Returns `undefined` for parts with no content slot:
+ * `step-start` (a hole), `source-url`, and `file` parts that are message attachments.
+ *
+ * Lossless for every part `toUIPart` produced except `text_delta`, which comes back as `text`.
+ * A tool part restores the stored call as it was, so edits to `input`/`output` on a mapped
+ * tool part are not written back; a tool part built by hand becomes an agents tool call.
+ */
+export function fromUIPart(part: UIMessagePart): TMessageContentParts | undefined {
+ switch (part.type) {
+ case 'text': {
+ const { textObject, textAbsent, annotatedValue, ...rest } =
+ part.providerMetadata?.librechat ?? {};
+ const text = joinText(part.text, { textObject, textAbsent, annotatedValue });
+ return { type: ContentTypes.TEXT, ...(text !== undefined && { text }), ...rest };
+ }
+ case 'reasoning': {
+ const { textObject, textAbsent, annotatedValue, thinkOpen, thinkClose, ...rest } =
+ part.providerMetadata?.librechat ?? {};
+ const wrapped = `${thinkOpen ?? ''}${part.text}${thinkClose ?? ''}`;
+ const think = joinText(wrapped, { textObject, textAbsent, annotatedValue });
+ return { type: ContentTypes.THINK, ...(think !== undefined && { think }), ...rest };
+ }
+ case 'file':
+ return part.providerMetadata
+ ? fromFilePart(part, part.providerMetadata.librechat)
+ : undefined;
+ case 'step-start':
+ case 'source-url':
+ return undefined;
+ }
+ if (isUIDataPart(part)) {
+ return { type: contentTypesByDataPart[part.type], ...part.data } as TMessageContentParts;
+ }
+ return fromToolPart(part);
+}
+
+/**
+ * Collects content in slot order: a mapped part takes the next slot and `step-start` holds one
+ * open as a hole, while parts with no content slot (sources, attachments) take none, so their
+ * position in the view never shifts a step's index.
+ */
+const createContentWriter = () => {
+ const content: TMessageContentParts[] = [];
+ let slot = 0;
+ const write = (part: UIMessagePart) => {
+ const mapped = fromUIPart(part);
+ if (mapped) {
+ content[slot++] = mapped;
+ } else if (part.type === 'step-start') {
+ slot++;
+ content.length = slot;
+ }
+ };
+ return { content, write };
+};
+
+/** Maps UI parts back to a content array; `step-start` parts become holes again. */
+export function fromUIParts(parts: ReadonlyArray<UIMessagePart>): TMessageContentParts[] {
+ const writer = createContentWriter();
+ for (const part of parts) {
+ writer.write(part);
+ }
+ return writer.content;
+}
+
+/** A `file` part that stands for a `message.files` entry rather than a content slot. */
+const isAttachmentPart = (part: UIMessagePart): part is UIFilePart =>
+ part.type === 'file' &&
+ (!part.providerMetadata || part.providerMetadata.librechat.source === 'attachment');
+
+const toAttachmentFilePart = (file: Partial<TFile>, index: number): UIFilePart | undefined => {
+ if (!file.filepath) {
+ return undefined;
+ }
+ return {
+ type: 'file',
+ mediaType: file.type || 'application/octet-stream',
+ ...(file.filename && { filename: file.filename }),
+ url: file.filepath,
+ providerMetadata: { librechat: { source: 'attachment', filepath: file.filepath, index } },
+ };
+};
+
+type SourceLink = { link: string; title?: string };
+
+/** The linkable results of a web search: organic, top stories, and plain link references. */
+const getSourceLinks = (attachment: TAttachment): SourceLink[] => {
+ const results = attachment[Tools.web_search];
+ if (!results) {
+ return [];
+ }
+ const links: SourceLink[] = [...(results.organic ?? []), ...(results.topStories ?? [])];
+ for (const reference of results.references ?? []) {
+ if (reference.type === 'link') {
+ links.push(reference);
+ }
+ }
+ return links;
+};
+
+/**
+ * Appends one `source-url` part per distinct URL across every search attachment. The id carries a
+ * message-wide ordinal, since provider tool-call ids repeat across agents and turns.
+ */
+const pushSourceParts = (parts: UIMessagePart[], attachments: TAttachment[] | undefined) => {
+ const seen = new Set<string>();
+ for (const attachment of attachments ?? []) {
+ for (const source of getSourceLinks(attachment)) {
+ if (seen.has(source.link)) {
+ continue;
+ }
+ seen.add(source.link);
+ parts.push({
+ type: 'source-url',
+ sourceId: `${attachment.toolCallId}-${seen.size - 1}`,
+ url: source.link,
+ ...(source.title && { title: source.title }),
+ });
+ }
+ }
+};
+
+const pushUnique = <T>(seen: Set<T>, value: T | undefined) => {
+ if (value !== undefined) {
+ seen.add(value);
+ }
+};
+
+/**
+ * A `UIMessage` view of a `TMessage`: content parts in content order, then attachment files,
+ * then web search sources. A message without `content` gets one text part from `text`.
+ * One pass over the content builds both the parts and the metadata.
+ */
+export function toUIMessage(message: TMessage, options?: UIMappingOptions): UIMessage {
+ const context: MappingContext = { ...options, message };
+ const content = message.content;
+ const parts: UIMessagePart[] = [];
+ const agentIds = new Set<string>();
+ const groupIds = new Set<number>();
+ const activityLabels: UIMessageMetadata['activityLabels'] = [];
+ const steers: UIMessageMetadata['steers'] = [];
+ const summaries: UIMessageMetadata['summaries'] = [];
+
+ const contentless = !content || (content.length === 0 && (message.text?.length ?? 0) > 0);
+ let joinedText = '';
+
+ if (content && !contentless) {
+ for (let i = 0; i < content.length; i++) {
+ const part = content[i] as MappableContentPart | undefined;
+ const uiPart = toUIPart(part, i, context);
+ parts.push(uiPart);
+ if (part == null) {
+ continue;
+ }
+ pushUnique(
+ agentIds,
+ part.agentId ??
+ (part.type === ContentTypes.TOOL_CALL ? part.tool_call?.agentId : undefined),
+ );
+ pushUnique(groupIds, part.groupId);
+ if (uiPart.type === 'text') {
+ joinedText += uiPart.text;
+ } else if (uiPart.type === 'data-agent-update') {
+ pushUnique(agentIds, uiPart.data.agent_update.agentId);
+ } else if (uiPart.type === 'data-activity-label') {
+ activityLabels.push(uiPart.data);
+ } else if (uiPart.type === 'data-steer') {
+ steers.push(uiPart.data);
+ } else if (uiPart.type === 'data-summary') {
+ summaries.push(uiPart.data);
+ }
+ }
+ } else {
+ parts.push({ type: 'text', text: message.text ?? '' });
+ }
+
+ const files = message.files ?? [];
+ for (let i = 0; i < files.length; i++) {
+ const filePart = toAttachmentFilePart(files[i], i);
+ if (filePart) {
+ parts.push(filePart);
+ }
+ }
+ pushSourceParts(parts, message.attachments);
+
+ const metadata: UIMessageMetadata = {
+ conversationId: message.conversationId,
+ parentMessageId: message.parentMessageId,
+ ...(message.sender !== undefined && { sender: message.sender }),
+ ...(message.model !== undefined && { model: message.model }),
+ ...(message.endpoint !== undefined && { endpoint: message.endpoint }),
+ ...(message.error !== undefined && { error: message.error }),
+ ...(message.unfinished !== undefined && { unfinished: message.unfinished }),
+ ...(message.createdAt !== undefined && { createdAt: message.createdAt }),
+ ...(contentless && { contentless: true }),
+ ...(contentless && content && { emptyContent: true }),
+ ...(message.attachments !== undefined && { attachments: message.attachments }),
+ ...(!contentless &&
+ message.text !== undefined &&
+ message.text !== joinedText && { text: message.text }),
+ ...(agentIds.size > 0 && { agentIds: Array.from(agentIds) }),
+ ...(groupIds.size > 0 && { groupIds: Array.from(groupIds) }),
+ ...(activityLabels.length > 0 && { activityLabels }),
+ ...(steers.length > 0 && { steers }),
+ ...(summaries.length > 0 && { summaries }),
+ };
+
+ return {
+ id: message.messageId,
+ role: message.isCreatedByUser ? 'user' : 'assistant',
+ metadata,
+ parts,
+ };
+}
+
+const messageFields = ['sender', 'model', 'endpoint', 'error', 'unfinished', 'createdAt'] as const;
+
+const pickMessageFields = (metadata: UIMessageMetadata | undefined) => {
+ const fields: Partial<Pick<TMessage, (typeof messageFields)[number]>> = {};
+ if (!metadata) {
+ return fields;
+ }
+ for (const key of messageFields) {
+ if (metadata[key] !== undefined) {
+ Object.assign(fields, { [key]: metadata[key] });
+ }
+ }
+ return fields;
+};
+
+const joinPartText = (parts: ReadonlyArray<UIMessagePart | undefined>) => {
+ let text = '';
+ for (const part of parts) {
+ if (part?.type === 'text') {
+ text += part.text;
+ }
+ }
+ return text;
+};
+
+/**
+ * `TMessage.text` of a content-bearing message is not derived from its parts, so the stored text
+ * is kept unless the text parts changed, in which case the view's text wins. Without a base the
+ * stored text travels in `metadata.text`.
+ */
+const resolveText = (text: string, metadata: UIMessageMetadata | undefined, base?: TMessage) => {
+ if (metadata?.contentless) {
+ return text;
+ }
+ if (base?.text === undefined) {
+ return metadata?.text ?? text;
+ }
+ const baseText = joinPartText((base.content ?? []).map((part) => toUIPart(part)));
+ return text === baseText ? base.text : text;
+};
+
+/**
+ * Attachment `file` parts describe `message.files`: each is matched to its stored entry by the
+ * position and path it was viewed with (so an edited `url` still finds it, and entries sharing a
+ * path stay distinct), the view's edits are applied, parts built by hand become new entries, and stored entries the view never showed keep their slots
+ * while the visible entries fill the others in view order.
+ */
+const reconcileFiles = (
+ attachments: ReadonlyArray<UIFilePart>,
+ baseFiles: TMessage['files'],
+): TMessage['files'] => {
+ if (!baseFiles && attachments.length === 0) {
+ return undefined;
+ }
+ const claimed = new Set<Partial<TFile>>();
+ /** A viewed part names its stored entry; a hand-built one takes the first unclaimed match. */
+ const findStored = (part: UIFilePart) => {
+ const metadata = part.providerMetadata?.librechat;
+ if (metadata?.source === 'attachment') {
+ const candidate = baseFiles?.[metadata.index];
+ return candidate?.filepath === metadata.filepath ? candidate : undefined;
+ }
+ return baseFiles?.find((file) => file.filepath === part.url && !claimed.has(file));
+ };
+ const visible = attachments.map((part) => {
+ const stored = findStored(part);
+ if (stored) {
+ claimed.add(stored);
+ return applyFileEdits(stored, part, 'application/octet-stream');
+ }
+ return {
+ filepath: part.url,
+ ...(part.filename && { filename: part.filename }),
+ type: part.mediaType,
+ };
+ });
+ const files: Partial<TFile>[] = [];
+ let next = 0;
+ for (const file of baseFiles ?? []) {
+ if (!file.filepath) {
+ files.push(file);
+ } else if (next < visible.length) {
+ files.push(visible[next++]);
+ }
+ }
+ return files.concat(visible.slice(next));
+};
+
+/** Reads an identity field from metadata, where an explicit `null` is a value, not an absence. */
+const pickIdentity = <K extends 'conversationId' | 'parentMessageId'>(
+ key: K,
+ metadata: UIMessageMetadata | undefined,
+ base: TMessage | undefined,
+): TMessage[K] => {
+ if (metadata && metadata[key] !== undefined) {
+ return metadata[key];
+ }
+ return base?.[key] ?? null;
+};
+
+/**
+ * Maps a `UIMessage` back onto a `TMessage`. `base` is the stored message with the same id,
+ * whose fields the UI view does not carry (tree position, feedback, token counts) are kept.
+ * A stored message round-trips only with its base: without one the message is rebuilt from the
+ * view and its metadata, and a file record keeps only what its part shows (path, name, type).
+ * One pass over the parts collects the text, the content and the attachments.
+ */
+export function fromUIMessage(message: UIMessage, base?: TMessage): TMessage {
+ const metadata = message.metadata;
+ const contentless = metadata?.contentless === true;
+ const writer = createContentWriter();
+ const attachments: UIFilePart[] = [];
+ let text = '';
+ let addedContent = false;
+ for (const part of message.parts) {
+ if (part.type === 'text') {
+ text += part.text;
+ } else if (isAttachmentPart(part)) {
+ attachments.push(part);
+ continue;
+ } else if (part.type !== 'source-url' && part.type !== 'step-start') {
+ addedContent = true;
+ }
+ writer.write(part);
+ }
+ const writesContent = !contentless || addedContent;
+
+ const next: TMessage = {
+ ...base,
+ ...pickMessageFields(metadata),
+ messageId: message.id,
+ isCreatedByUser: message.role === 'user',
+ conversationId: pickIdentity('conversationId', metadata, base),
+ parentMessageId: pickIdentity('parentMessageId', metadata, base),
+ text: resolveText(text, metadata, base),
+ };
+ if (writesContent) {
+ next.content = writer.content;
+ } else if (metadata?.emptyContent && base?.content === undefined) {
+ next.content = [];
+ }
+ if (base?.attachments === undefined && metadata?.attachments !== undefined) {
+ next.attachments = metadata.attachments;
+ }
+ const files = reconcileFiles(attachments, base?.files);
+ if (files) {
+ next.files = files;
+ }
+ return next;
+}