From 6ac941eff330fe531dda5dcb55046b12e2aea389 Mon Sep 17 00:00:00 2001 From: Marco Beretta <81851188+berry-13@users.noreply.github.com> Date: Sat, 26 Sep 2026 15:54:58 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=A7=A9=20feat:=20Map=20Message=20Content?= =?UTF-8?q?=20Parts=20to=20a=20UI=20Parts=20Union=20(#16374)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: map message content parts to a UI parts union Adds a UIMessage-shaped view of TMessage modelled on the AI SDK (ai@7.0.114): content parts map one-to-one onto text, reasoning, tool-, file and data-* parts, holes map to step-start, and the reverse restores the stored content so a view round-trips. * fix: carry text, files and metadata through the reverse message mapping An empty content array with text now views as contentless, an edited text part updates the stored text, attachment file parts reconcile message files, and metadata fields restore a message rebuilt without a stored base. * fix: read durable tool markers and apply view edits in the parts mapping Tool parts fall back from an empty id to the host step id, surface approval pauses and background-cancel or validation failures, and treat an empty legacy function output as submitted. The reverse mapping writes file and attachment edits over the stored records, keeps an explicit null parent, carries non-derived message text and absent text fields, persists hand-built tool failures, and collects text, content and attachments in one pass. Web search sources include link references and take message-wide ids. UIMessage drops the system role it could not round-trip. Adds mock-harness scenarios that view persisted replies, reasoning and tool turns and map them back. * fix: view persisted reasoning without its think tags Persisted reasoning is stored inside tags that every renderer strips; the reasoning part now exposes the text alone and keeps the exact wrapper so the reverse mapping restores it. The tool-turn scenario skips mobile, where the composer MCP picker is not offered. * fix: give view attachments a stable identity and read legacy tool outcomes Attachment file parts carry the stored path they were viewed with, so an edited url still matches its file. Reverse slots advance only for content parts, audio takes its format from an edited media type, a null model survives a base-less rebuild, legacy retrieval outputs count as submitted, and error-prefixed outputs map to output-error through isToolErrorOutput, the predicate the tool output renderers use. * fix: keep attachments, empty content and hand-built tool results through a rebuild A base-less rebuild restores the stored attachments and an explicit empty content array from metadata. Hand-built tool parts record a completed status for output-available and keep an array output as a code interpreter call. Files the view never showed keep their stored positions while visible files fill the others in view order. * feat: let the caller supply tool outcome rules to the parts mapping Some tool outcomes are decided by rules the client owns, such as memory failure prose and background status attachments. toUIMessage, toUIParts and toUIPart take a resolveToolFailure option instead of copying those rules. Text deltas keep their ownership metadata, an empty hand-built array output is marked completed, and fromUIMessage documents that a stored message round-trips only with its base. * fix: map untyped lane placeholders to step-start A dual-conversation turn seeds type '' placeholder slots, which fell through the part switch and crashed toUIMessage. Any slot without a known type now maps to step-start, and the reverse leaves a hole, the same thing persistence compaction does. * fix: identify view attachments by position and keep content added to plain messages Attachment parts carry their index in message.files beside the path, so two files sharing a path stay distinct, and a hand-built part claims the first unclaimed match. Content parts added to a view of a plain message are written as content. Tool arguments that parse to a JSON primitive stay their string, inside the declared input type. * fix: derive fallback tool ids from the streamed index and drop stale annotations A tool call with neither a provider id nor a step id takes its fallback id from the streamed index the settled message keeps, so its identity survives compaction. Annotations on object-form text are dropped once the view's text no longer matches the value they index into. * fix: map tool call slots without a call to step-start and keep text delta object shape Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017snqTCuA2LHsoKuC335HFG * fix: report background and caller-resolved tool failures by their reason Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_017snqTCuA2LHsoKuC335HFG --------- Co-authored-by: Claude Opus 5.5 --- e2e/specs/mock/scenarios/parts.spec.ts | 133 +++ packages/data-provider/src/errors.ts | 5 + packages/data-provider/src/index.ts | 2 + packages/data-provider/src/parts.spec.ts | 1229 ++++++++++++++++++++++ packages/data-provider/src/parts.ts | 1065 +++++++++++++++++++ 5 files changed, 2434 insertions(+) create mode 100644 e2e/specs/mock/scenarios/parts.spec.ts create mode 100644 packages/data-provider/src/parts.spec.ts create mode 100644 packages/data-provider/src/parts.ts 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; +}