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 { + const conversationId = new URL(page.url()).pathname.replace('/c/', ''); + expect(conversationId).not.toBe('new'); + const token = await getAccessToken(page); + return fetchJson(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 b226ad4191..d829458837 100644 --- a/packages/data-provider/src/index.ts +++ b/packages/data-provider/src/index.ts @@ -13,6 +13,8 @@ export * from './messages'; export * from './errors'; /* run steps */ export * from './runSteps'; +/* 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.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.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) => { + 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 = { + 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 => ({ + messageId: 'response-1', + conversationId: 'convo-1', + parentMessageId: 'user-1', + isCreatedByUser: false, + text: '', + ...overrides, +}); + +type ResolveToolFailure = NonNullable; + +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 & 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: '\nWeighing options\n', + } 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), + 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; + 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>( + (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 & 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; + + 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 `ai@7.0.114` (`UIMessage`, `UIMessagePart`, `UIToolInvocation`) and + * `@ai-sdk/react@4.0.117` (`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 = Extract; +type ToolCallContentPart = ContentPartOf; +type ToolCallValue = ToolCallContentPart['tool_call']; + +/** AI SDK `providerMetadata`, keyed by provider; LibreChat keeps its own fields under one key. */ +export type LibreChatProviderMetadata = { librechat: T }; + +/** Fields of a `TextData` object other than its value, kept so the object form round-trips. */ +type TextObjectFields = Omit, '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, 'type' | 'text'> & + TextShape; + +/** The `` wrapper persisted reasoning carries, exactly as stored, so it can be restored. */ +type ThinkWrapper = { thinkOpen?: string; thinkClose?: string }; + +export type UIReasoningPartMetadata = Omit, 'type' | 'think'> & + TextShape & + ThinkWrapper; + +/** AI SDK `TextUIPart`. */ +export type UITextPart = { + type: 'text'; + text: string; + state?: 'streaming' | 'done'; + providerMetadata?: LibreChatProviderMetadata; +}; + +/** AI SDK `ReasoningUIPart`. */ +export type UIReasoningPart = { + type: 'reasoning'; + text: string; + state?: 'streaming' | 'done'; + providerMetadata?: LibreChatProviderMetadata; +}; + +/** The content part a `file` UI part was mapped from, when it came from content. */ +export type UIFilePartMetadata = + | ({ source: ContentTypes.IMAGE_FILE } & Omit, 'type'>) + | ({ source: ContentTypes.IMAGE_URL; urlObject: boolean } & Omit< + ContentPartOf, + 'type' | 'image_url' + > & { detail?: Agents.ImageDetail }) + | ({ source: ContentTypes.VIDEO_URL } & Omit< + ContentPartOf, + 'type' | 'video_url' + >) + | ({ source: ContentTypes.INPUT_AUDIO; format: string } & Omit< + ContentPartOf, + '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; +}; + +/** 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 & { + /** The call as stored, so the reverse mapping restores fields the UI part does not carry. */ + toolCall: ToolCallValue; +}; + +/** + * AI SDK `ToolUIPart`: `tool-` 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; +}; + +type DataOf = Omit, 'type'>; + +/** AI SDK `DataUIPart`: LibreChat parts with no AI SDK counterpart, carried whole. */ +export type UIDataPart = + | { type: 'data-agent-update'; data: DataOf } + | { type: 'data-summary'; data: DataOf } + | { type: 'data-activity-label'; data: DataOf } + | { type: 'data-steer'; data: DataOf } + | { type: 'data-error'; data: DataOf }; + +/** 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[]; + steers?: DataOf[]; + summaries?: DataOf[]; +}; + +/** + * 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>; + +const contentTypesByDataPart: Record = { + '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 =

(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*\s*/; +const thinkClosePattern = /\s*<\/think>\s*$/; + +/** + * Persisted reasoning is stored inside `` 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 = (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): 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, + 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 = >( + 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): 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, 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(); + 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 = (seen: Set, 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(); + const groupIds = new Set(); + 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> = {}; + 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) => { + 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, + baseFiles: TMessage['files'], +): TMessage['files'] => { + if (!baseFiles && attachments.length === 0) { + return undefined; + } + const claimed = new Set>(); + /** 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[] = []; + 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 = ( + 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; +}