Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
import type { TMessageContentParts, ContentMetadata, TextData, Text } from './types/content';
import type { TMessage, TAttachment } from './schemas';
import type { Agents } from './types/agents';
import type { TFile } from './types/files';
import { ContentTypes, ToolCallTypes } from './types/runs';
import { isToolErrorOutput } from './errors';
import { Tools } from './types/tools';
/**
* A UI parts view of LibreChat message content, modelled on the AI SDK `UIMessage`.
*
* Matched against `[email protected]` (`UIMessage`, `UIMessagePart`, `UIToolInvocation`) and
* `@ai-sdk/[email protected]` (`useChat`). The shapes are structural copies, not imports: this
* package does not depend on the AI SDK.
*
* Position invariant: `toUIParts(content)[i]` is the part for `content[i]`, holes included, so an
* index-derived identity (the step index the stream reducers write to) survives the mapping.
* A hole becomes a `step-start` part and maps back to a hole. Parts that have no content slot
* (message files, web search sources) are appended after the last content part.
*/
/** Stream-only text chunk; never persisted, but it can appear in a message being built. */
export type TextDeltaContentPart = {
type: ContentTypes.TEXT_DELTA;
text?: string | TextData;
text_delta?: string | TextData;
} & ContentMetadata;
/** Every content part the mapping accepts. */
export type MappableContentPart =
| TMessageContentParts
| TextDeltaContentPart
| AskUserQuestionContentPart;
type ContentPartOf<T extends ContentTypes> = Extract<MappableContentPart, { type: T }>;
type ToolCallContentPart = ContentPartOf<ContentTypes.TOOL_CALL>;
type ToolCallValue = ToolCallContentPart['tool_call'];
/** AI SDK `providerMetadata`, keyed by provider; LibreChat keeps its own fields under one key. */
export type LibreChatProviderMetadata<T> = { librechat: T };
/** Fields of a `TextData` object other than its value, kept so the object form round-trips. */
type TextObjectFields = Omit<NonNullable<TextData>, 'value'>;
/** How the stored text field was shaped, so the reverse mapping restores that shape. */
type TextShape = {
textObject?: TextObjectFields;
/** The stored part had no text field at all, which is not the same as an empty string. */
textAbsent?: true;
/** The value the stored annotations index into; an edit away from it drops them. */
annotatedValue?: string;
};
export type UITextPartMetadata = Omit<ContentPartOf<ContentTypes.TEXT>, 'type' | 'text'> &
TextShape;
/** The `<think>` wrapper persisted reasoning carries, exactly as stored, so it can be restored. */
type ThinkWrapper = { thinkOpen?: string; thinkClose?: string };
export type UIReasoningPartMetadata = Omit<ContentPartOf<ContentTypes.THINK>, 'type' | 'think'> &
TextShape &
ThinkWrapper;
/** AI SDK `TextUIPart`. */
export type UITextPart = {
type: 'text';
text: string;
state?: 'streaming' | 'done';
providerMetadata?: LibreChatProviderMetadata<UITextPartMetadata>;
};
/** AI SDK `ReasoningUIPart`. */
export type UIReasoningPart = {
type: 'reasoning';
text: string;
state?: 'streaming' | 'done';
providerMetadata?: LibreChatProviderMetadata<UIReasoningPartMetadata>;
};
/** The content part a `file` UI part was mapped from, when it came from content. */
export type UIFilePartMetadata =
| ({ source: ContentTypes.IMAGE_FILE } & Omit<ContentPartOf<ContentTypes.IMAGE_FILE>, 'type'>)
| ({ source: ContentTypes.IMAGE_URL; urlObject: boolean } & Omit<
ContentPartOf<ContentTypes.IMAGE_URL>,
'type' | 'image_url'
> & { detail?: Agents.ImageDetail })
| ({ source: ContentTypes.VIDEO_URL } & Omit<
ContentPartOf<ContentTypes.VIDEO_URL>,
'type' | 'video_url'
>)
| ({ source: ContentTypes.INPUT_AUDIO; format: string } & Omit<
ContentPartOf<ContentTypes.INPUT_AUDIO>,
'type' | 'input_audio'
>)
/**
* A `message.files` entry: `index` is its position in the stored array and `filepath` the path
* it was viewed with, together its identity across edits even when two entries share a path.
*/
| { source: 'attachment'; filepath: string; index: number };
/**
* AI SDK `FileUIPart`. A part from a content slot names its content type as `source`; one with
* `source: 'attachment'`, or no metadata at all (built by hand), is a message attachment.
*/
export type UIFilePart = {
type: 'file';
mediaType: string;
filename?: string;
url: string;
providerMetadata?: LibreChatProviderMetadata<UIFilePartMetadata>;
};
/** AI SDK `SourceUrlUIPart`; built from web search attachments. */
export type UISourceUrlPart = {
type: 'source-url';
sourceId: string;
url: string;
title?: string;
};
/** AI SDK `StepStartUIPart`; stands in for a content slot no step has written yet. */
export type UIStepStartPart = { type: 'step-start' };
/** AI SDK tool states. */
export type UIToolState =
| 'input-streaming'
| 'input-available'
| 'approval-requested'
| 'approval-responded'
| 'output-available'
| 'output-error'
| 'output-denied';
/**
* AI SDK tool `approval`, for a call paused for human review. `approved` and `reason` are set once
* the reviewer decided: `approve` and `edit` approve the call, `reject` and `respond` deny it. A
* `respond` still ends with the reviewer's text as the call's output, so it never reads as denied.
*/
export type UIToolApproval = {
id: string;
requestReason?: string;
approved?: boolean;
reason?: string;
};
export type UIToolInput = Agents.ToolCall['args'] | object;
export type UIToolOutput = string | CodeInterpreterOutputs;
type CodeInterpreterOutputs = Extract<
ToolCallValue,
{ type: 'code_interpreter' }
>['code_interpreter']['outputs'];
export type UIToolPartMetadata = Omit<ToolCallContentPart, 'type' | 'tool_call'> & {
/** The call as stored, so the reverse mapping restores fields the UI part does not carry. */
toolCall: ToolCallValue;
};
/**
* AI SDK `ToolUIPart`: `tool-<name>` with a lifecycle `state`. Cancelled, failed, rejected and
* background-cancelled calls all surface as `output-error`; the exact marker stays on the stored
* call. A call paused for human review is `approval-requested`, then `approval-responded` once the
* reviewer decided, and `output-denied` when a denied call has ended.
*/
export type UIToolPart = {
type: `tool-${string}`;
toolCallId: string;
state: UIToolState;
input?: UIToolInput;
output?: UIToolOutput;
errorText?: string;
approval?: UIToolApproval;
callProviderMetadata?: LibreChatProviderMetadata<UIToolPartMetadata>;
};
type DataOf<T extends ContentTypes> = Omit<ContentPartOf<T>, 'type'>;
/** The content part type of an `ask_user_question` pause, which `ContentTypes` does not list. */
export const ASK_USER_QUESTION = 'ask_user_question' as const;
/** The pending question an `ask_user_question` pause shows inline with the message content. */
export type AskUserQuestionData = {
actionId: string;
question: Agents.AskUserQuestionRequest;
questions?: Agents.AskUserQuestionBatchItem[];
/** The ask tool call that raised the pause, when the server reported it. */
tool_call_id?: string;
};
/**
* Client-written content part for an `ask_user_question` pause. It rides in the content array
* under a type outside `ContentTypes`, so it occupies a slot like any other part.
*/
export type AskUserQuestionContentPart = ContentMetadata & {
type: typeof ASK_USER_QUESTION;
[ASK_USER_QUESTION]: AskUserQuestionData;
};
/** Parts that map to a `data-*` part one to one through `ContentTypes`. */
type ContentDataPart =
| { type: 'data-agent-update'; data: DataOf<ContentTypes.AGENT_UPDATE> }
| { type: 'data-summary'; data: DataOf<ContentTypes.SUMMARY> }
| { type: 'data-activity-label'; data: DataOf<ContentTypes.ACTIVITY_LABEL> }
| { type: 'data-steer'; data: DataOf<ContentTypes.STEER> }
| { type: 'data-error'; data: DataOf<ContentTypes.ERROR> };
/** A pending `ask_user_question` pause, carried whole. */
export type UIAskUserQuestionPart = {
type: 'data-ask-user-question';
data: Omit<AskUserQuestionContentPart, 'type'>;
};
/** AI SDK `DataUIPart`: LibreChat parts with no AI SDK counterpart, carried whole. */
export type UIDataPart = ContentDataPart | UIAskUserQuestionPart;
/** AI SDK `UIMessagePart`, narrowed to what LibreChat content produces. */
export type UIMessagePart =
| UITextPart
| UIReasoningPart
| UIToolPart
| UIFilePart
| UISourceUrlPart
| UIStepStartPart
| UIDataPart;
/** What a `TMessage` carries that `UIMessage` has no field for. */
export type UIMessageMetadata = Pick<
TMessage,
| 'conversationId'
| 'parentMessageId'
| 'sender'
| 'model'
| 'endpoint'
| 'error'
| 'unfinished'
| 'createdAt'
> & {
/** Set when the message had no `content`, so its parts were built from `text` and `files`. */
contentless?: boolean;
/**
* The stored `text` of a content-bearing message, present only when it differs from the text
* parts joined, so a rebuild without a stored base keeps it.
*/
text?: string;
/** Set when a contentless message stored `content: []` rather than no `content` at all. */
emptyContent?: true;
/** The stored attachments, carried whole so a rebuild without a stored base keeps them. */
attachments?: TAttachment[];
/** Agents that produced parts of this message, in order of first appearance. */
agentIds?: string[];
/** Parallel content groups present in this message, in order of first appearance. */
groupIds?: number[];
activityLabels?: DataOf<ContentTypes.ACTIVITY_LABEL>[];
steers?: DataOf<ContentTypes.STEER>[];
summaries?: DataOf<ContentTypes.SUMMARY>[];
};
/**
* AI SDK `UIMessage`. `role` omits the AI SDK's `system`: a `TMessage` is either created by the
* user or not, so a system role could not survive the reverse mapping.
*/
export type UIMessage = {
id: string;
role: 'user' | 'assistant';
metadata?: UIMessageMetadata;
parts: UIMessagePart[];
};
type DataPartType = ContentDataPart['type'];
const dataPartTypes = {
[ContentTypes.AGENT_UPDATE]: 'data-agent-update',
[ContentTypes.SUMMARY]: 'data-summary',
[ContentTypes.ACTIVITY_LABEL]: 'data-activity-label',
[ContentTypes.STEER]: 'data-steer',
[ContentTypes.ERROR]: 'data-error',
} as const satisfies Partial<Record<ContentTypes, DataPartType>>;
const contentTypesByDataPart: Record<DataPartType, keyof typeof dataPartTypes> = {
'data-agent-update': ContentTypes.AGENT_UPDATE,
'data-summary': ContentTypes.SUMMARY,
'data-activity-label': ContentTypes.ACTIVITY_LABEL,
'data-steer': ContentTypes.STEER,
'data-error': ContentTypes.ERROR,
};
const stepStart: UIStepStartPart = { type: 'step-start' };
export const isUIToolPart = (part: UIMessagePart): part is UIToolPart =>
part.type.startsWith('tool-');
export const isUIDataPart = (part: UIMessagePart): part is UIDataPart =>
part.type.startsWith('data-');
const hasKeys = (value: object) => Object.keys(value).length > 0;
const withLibreChatMetadata = <P extends object, M extends object>(part: P, metadata: M) =>
hasKeys(metadata) ? { ...part, providerMetadata: { librechat: metadata } } : part;
const splitText = (text: string | TextData | undefined): { value: string } & TextShape => {
if (text === undefined) {
return { value: '', textAbsent: true };
}
if (text == null || typeof text === 'string') {
return { value: text ?? '' };
}
const { value, ...textObject } = text;
const stored = value ?? '';
return {
value: stored,
textObject,
...((textObject.annotations?.length ?? 0) > 0 && { annotatedValue: stored }),
};
};
/** Restores the stored text field; `undefined` means the field is left off the part. */
const joinText = (value: string, shape: TextShape): string | Text | undefined => {
if (shape.textAbsent && value === '') {
return undefined;
}
if (!shape.textObject) {
return value;
}
if (shape.annotatedValue !== undefined && value !== shape.annotatedValue) {
const { annotations: _stale, ...textObject } = shape.textObject;
return { ...textObject, value };
}
return { ...shape.textObject, value };
};
const thinkOpenPattern = /^\s*<think>\s*/;
const thinkClosePattern = /\s*<\/think>\s*$/;
/**
* Persisted reasoning is stored inside `<think>` tags, which every renderer strips; the view
* exposes the reasoning alone and keeps the exact wrapper for the reverse mapping.
*/
const splitThinkTags = (value: string): { value: string } & ThinkWrapper => {
const open = value.match(thinkOpenPattern)?.[0];
const inner = open ? value.slice(open.length) : value;
const close = inner.match(thinkClosePattern)?.[0];
return {
value: close ? inner.slice(0, inner.length - close.length) : inner,
...(open && { thinkOpen: open }),
...(close && { thinkClose: close }),
};
};
const toTextMetadata = <M extends object>(rest: M, shape: TextShape) => ({
...rest,
...(shape.textObject && { textObject: shape.textObject }),
...(shape.textAbsent && { textAbsent: shape.textAbsent }),
...(shape.annotatedValue !== undefined && { annotatedValue: shape.annotatedValue }),
});
const parseToolInput = (args: UIToolInput | undefined) => {
if (typeof args !== 'string') {
return { input: args, complete: args != null };
}
try {
const parsed: unknown = JSON.parse(args);
return {
input: typeof parsed === 'object' && parsed !== null ? (parsed as object) : args,
complete: true,
};
} catch {
return { input: args, complete: false };
}
};
type ToolCallFields = {
name: string;
id?: string;
args?: UIToolInput;
output?: UIToolOutput;
/** Whether the call's output was submitted, by that variant's own sentinel. */
submitted: boolean;
};
const readToolCall = (toolCall: ToolCallValue): ToolCallFields => {
switch (toolCall.type) {
case 'function':
return {
name: toolCall.function.name,
id: toolCall.id || undefined,
args: toolCall.function.arguments,
output: toolCall.function.output ?? undefined,
submitted: toolCall.function.output != null,
};
case 'code_interpreter':
return {
name: toolCall.type,
id: toolCall.id || undefined,
args: toolCall.code_interpreter.input,
output: toolCall.code_interpreter.outputs,
submitted: toolCall.code_interpreter.outputs.length > 0,
};
case 'retrieval':
case 'file_search': {
const output =
'output' in toolCall && typeof toolCall.output === 'string' ? toolCall.output : undefined;
return { name: toolCall.type, id: toolCall.id || undefined, output, submitted: !!output };
}
default:
return {
name: toolCall.name,
id: toolCall.id || toolCall.stepId || undefined,
args: toolCall.args,
output: toolCall.output,
submitted: toolCall.output != null && toolCall.output !== '',
};
}
};
/**
* The failure a stored call records, if any: a failed or cancelled run step, an output the tool
* renderers read as an error, a cancelled background task, or arguments rejected by validation.
*/
/**
* Options for the forward mapping. Some tool outcomes are decided by knowledge this package does
* not hold, such as a memory tool's failure prose or a background task's status attachment; the
* caller that owns those rules supplies them here rather than the mapping copying them.
*/
export type UIMappingOptions = {
/**
* Returns a failure reason for a tool call the stored markers leave successful, or `undefined`.
* The reason becomes the part's `errorText`, since the stored output (a background dispatch
* handle, prose that reads as success) is not what established the failure; return the output
* itself when it is the message to show. It receives the stored call; `toUIMessage` also passes
* the message, for its attachments.
*/
resolveToolFailure?: (toolCall: ToolCallValue, message?: TMessage) => string | undefined;
};
type MappingContext = UIMappingOptions & { message?: TMessage };
/**
* `detail` says whether the stored output describes the failure (a failed step's partial output, an
* error the tool returned); when it does not, as with a cancelled background task whose output is
* the benign dispatch handle, the view reports the reason instead.
*/
type ToolFailure = { reason: string; detail: boolean };
const getToolFailure = (
toolCall: ToolCallValue,
output?: UIToolOutput,
): ToolFailure | undefined => {
const { runStepStatus } = toolCall;
if (runStepStatus === 'failed' || runStepStatus === 'cancelled') {
return { reason: runStepStatus, detail: true };
}
if (typeof output === 'string' && isToolErrorOutput(output)) {
return { reason: 'failed', detail: true };
}
if (!('name' in toolCall)) {
return undefined;
}
if (toolCall.backgroundTask?.cancelled) {
return { reason: 'cancelled', detail: false };
}
return toolCall.inputValidationError
? { reason: 'input-validation-error', detail: true }
: undefined;
};
/** A caller-resolved failure is known from outside the output, so its reason is what the view shows. */
const resolveFailure = (
toolCall: ToolCallValue,
output: UIToolOutput | undefined,
context?: MappingContext,
): ToolFailure | undefined => {
const stored = getToolFailure(toolCall, output);
if (stored) {
return stored;
}
const reason = context?.resolveToolFailure?.(toolCall, context.message);
return reason ? { reason, detail: false } : undefined;
};
const approvingDecisions = new Set<Agents.ToolApprovalDecisionType>(['approve', 'edit']);
const getToolApproval = (toolCall: ToolCallValue): UIToolApproval | undefined => {
if (!('name' in toolCall) || !toolCall.approval) {
return undefined;
}
const { actionId, description, decision, reason } = toolCall.approval;
return {
id: actionId,
...(description && { requestReason: description }),
...(decision && { approved: approvingDecisions.has(decision) }),
...(decision && reason !== undefined && { reason }),
};
};
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 responded = 'name' in toolCall && toolCall.approval?.decision === 'respond';
const failure = responded ? getToolFailure(toolCall) : resolveFailure(toolCall, output, context);
const approval = getToolApproval(toolCall);
const ended = submitted || runStepStatus === 'completed' || (progress ?? 0) >= 1;
let state: UIToolState = complete ? 'input-available' : 'input-streaming';
if (approval?.approved === false && !responded && (ended || failure)) {
state = 'output-denied';
} else if (failure) {
state = 'output-error';
} else if (ended) {
state = 'output-available';
} else if (approval) {
state = approval.approved === undefined ? 'approval-requested' : 'approval-responded';
}
const showsApproval =
state === 'approval-requested' ||
state === 'approval-responded' ||
state === 'output-denied' ||
approval?.approved === true;
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,
}),
...(showsApproval && { approval }),
callProviderMetadata: { librechat: { ...partMetadata, toolCall } },
};
};
const toDataPart = (part: ContentPartOf<keyof typeof dataPartTypes>): UIDataPart => {
const { type, ...data } = part;
return { type: dataPartTypes[type], data } as UIDataPart;
};
/**
* Maps one content part to its UI part. A missing part (a hole in a streamed array) maps to
* `step-start`, so indexes line up with the content array. So does a slot with no known type,
* such as the `type: ''` lane placeholder a dual-conversation turn seeds, and a tool call slot
* whose call has not arrived yet: persistence compacts those away, and the reverse mapping leaves
* a hole in their place the same way.
*/
export function toUIPart(
part: MappableContentPart | null | undefined,
index = 0,
options?: UIMappingOptions,
): UIMessagePart {
if (part == null) {
return stepStart;
}
switch (part.type) {
case ContentTypes.TEXT: {
const { type: _type, text, ...rest } = part;
const { value, ...shape } = splitText(text);
return withLibreChatMetadata(
{ type: 'text', text: value } satisfies UITextPart,
toTextMetadata(rest, shape),
);
}
case ContentTypes.TEXT_DELTA: {
const { type: _type, text, text_delta: textDelta, ...rest } = part;
const { value, ...shape } = splitText(textDelta ?? text);
return withLibreChatMetadata(
{ type: 'text', text: value, state: 'streaming' } satisfies UITextPart,
toTextMetadata(rest, shape),
);
}
case ContentTypes.THINK: {
const { type: _type, think, ...rest } = part;
const { value: raw, ...shape } = splitText(think);
const { value, ...wrapper } = splitThinkTags(raw);
return withLibreChatMetadata({ type: 'reasoning', text: value } satisfies UIReasoningPart, {
...toTextMetadata(rest, shape),
...wrapper,
});
}
case ContentTypes.TOOL_CALL:
return part.tool_call == null ? stepStart : toToolPart(part, index, options);
case ContentTypes.IMAGE_FILE: {
const { type: _type, ...rest } = part;
const { image_file: imageFile } = rest;
return {
type: 'file',
mediaType: imageFile.type || 'image/*',
filename: imageFile.filename,
url: imageFile.filepath,
providerMetadata: { librechat: { source: ContentTypes.IMAGE_FILE, ...rest } },
};
}
case ContentTypes.IMAGE_URL: {
const { type: _type, image_url: imageUrl, ...rest } = part;
const urlObject = typeof imageUrl !== 'string';
const detail = urlObject ? imageUrl.detail : undefined;
return {
type: 'file',
mediaType: 'image/*',
url: urlObject ? imageUrl.url : imageUrl,
providerMetadata: {
librechat: {
source: ContentTypes.IMAGE_URL,
urlObject,
...(detail !== undefined && { detail }),
...rest,
},
},
};
}
case ContentTypes.VIDEO_URL: {
const { type: _type, video_url: videoUrl, ...rest } = part;
return {
type: 'file',
mediaType: 'video/*',
url: videoUrl.url,
providerMetadata: { librechat: { source: ContentTypes.VIDEO_URL, ...rest } },
};
}
case ContentTypes.INPUT_AUDIO: {
const { type: _type, input_audio: audio, ...rest } = part;
return {
type: 'file',
mediaType: `audio/${audio.format}`,
url: `data:audio/${audio.format};base64,${audio.data}`,
providerMetadata: {
librechat: { source: ContentTypes.INPUT_AUDIO, format: audio.format, ...rest },
},
};
}
case ContentTypes.AGENT_UPDATE:
case ContentTypes.SUMMARY:
case ContentTypes.ACTIVITY_LABEL:
case ContentTypes.STEER:
case ContentTypes.ERROR:
return toDataPart(part);
case ASK_USER_QUESTION: {
const { type: _type, ...data } = part;
return { type: 'data-ask-user-question', data };
}
}
return stepStart;
}
/** Maps a content array to UI parts, one per slot, holes included. */
export function toUIParts(
content: ReadonlyArray<MappableContentPart | null | undefined>,
options?: UIMappingOptions,
) {
const parts: UIMessagePart[] = new Array(content.length);
for (let i = 0; i < content.length; i++) {
parts[i] = toUIPart(content[i], i, options);
}
return parts;
}
/**
* Writes the view's `url`, `filename` and `mediaType` onto a stored file record where they differ
* from what the forward mapping derived, so an edit lands and an untouched part round-trips.
*/
const applyFileEdits = <F extends Partial<TFile>>(
file: F,
part: UIFilePart,
fallbackType: string,
) => {
const edited = { ...file };
if (part.url !== file.filepath) {
edited.filepath = part.url;
}
if (part.filename !== undefined && part.filename !== file.filename) {
edited.filename = part.filename;
} else if (part.filename === undefined && file.filename) {
delete edited.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 toStoredApproval = (approval: UIToolApproval): NonNullable<Agents.ToolCall['approval']> => ({
actionId: approval.id,
allowed_decisions: [],
...(approval.requestReason && { description: approval.requestReason }),
...(approval.approved !== undefined && {
decision: approval.approved ? ('approve' as const) : ('reject' as const),
}),
...(approval.approved !== undefined &&
approval.reason !== undefined && { reason: approval.reason }),
});
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' || part.state === 'output-denied') && {
runStepStatus: 'completed' as const,
}),
...(part.approval && { approval: toStoredApproval(part.approval) }),
},
};
};
/**
* 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 (part.type === 'data-ask-user-question') {
return { type: ASK_USER_QUESTION, ...part.data } as unknown as TMessageContentParts;
}
if (isUIDataPart(part)) {
return { type: contentTypesByDataPart[part.type], ...part.data } as TMessageContentParts;
}
return fromToolPart(part);
}
/**
* Collects content in slot order: a mapped part takes the next slot and `step-start` holds one
* open as a hole, while parts with no content slot (sources, attachments) take none, so their
* position in the view never shifts a step's index.
*/
const createContentWriter = () => {
const content: TMessageContentParts[] = [];
let slot = 0;
const write = (part: UIMessagePart) => {
const mapped = fromUIPart(part);
if (mapped) {
content[slot++] = mapped;
} else if (part.type === 'step-start') {
slot++;
content.length = slot;
}
};
return { content, write };
};
/** Maps UI parts back to a content array; `step-start` parts become holes again. */
export function fromUIParts(parts: ReadonlyArray<UIMessagePart>): TMessageContentParts[] {
const writer = createContentWriter();
for (const part of parts) {
writer.write(part);
}
return writer.content;
}
/** A `file` part that stands for a `message.files` entry rather than a content slot. */
const isAttachmentPart = (part: UIMessagePart): part is UIFilePart =>
part.type === 'file' &&
(!part.providerMetadata || part.providerMetadata.librechat.source === 'attachment');
const toAttachmentFilePart = (file: Partial<TFile>, index: number): UIFilePart | undefined => {
if (!file.filepath) {
return undefined;
}
return {
type: 'file',
mediaType: file.type || 'application/octet-stream',
...(file.filename && { filename: file.filename }),
url: file.filepath,
providerMetadata: { librechat: { source: 'attachment', filepath: file.filepath, index } },
};
};
type SourceLink = { link: string; title?: string };
/** The linkable results of a web search: organic, top stories, and plain link references. */
const getSourceLinks = (attachment: TAttachment): SourceLink[] => {
const results = attachment[Tools.web_search];
if (!results) {
return [];
}
const links: SourceLink[] = [...(results.organic ?? []), ...(results.topStories ?? [])];
for (const reference of results.references ?? []) {
if (reference.type === 'link') {
links.push(reference);
}
}
return links;
};
/**
* Appends one `source-url` part per distinct URL across every search attachment. The id carries a
* message-wide ordinal, since provider tool-call ids repeat across agents and turns.
*/
const pushSourceParts = (parts: UIMessagePart[], attachments: TAttachment[] | undefined) => {
const seen = new Set<string>();
for (const attachment of attachments ?? []) {
for (const source of getSourceLinks(attachment)) {
if (seen.has(source.link)) {
continue;
}
seen.add(source.link);
parts.push({
type: 'source-url',
sourceId: `${attachment.toolCallId}-${seen.size - 1}`,
url: source.link,
...(source.title && { title: source.title }),
});
}
}
};
const pushUnique = <T>(seen: Set<T>, value: T | undefined) => {
if (value !== undefined) {
seen.add(value);
}
};
/**
* A `UIMessage` view of a `TMessage`: content parts in content order, then attachment files,
* then web search sources. A message without `content` gets one text part from `text`.
* One pass over the content builds both the parts and the metadata.
*/
export function toUIMessage(message: TMessage, options?: UIMappingOptions): UIMessage {
const context: MappingContext = { ...options, message };
const content = message.content;
const parts: UIMessagePart[] = [];
const agentIds = new Set<string>();
const groupIds = new Set<number>();
const activityLabels: UIMessageMetadata['activityLabels'] = [];
const steers: UIMessageMetadata['steers'] = [];
const summaries: UIMessageMetadata['summaries'] = [];
const contentless = !content || (content.length === 0 && (message.text?.length ?? 0) > 0);
let joinedText = '';
if (content && !contentless) {
for (let i = 0; i < content.length; i++) {
const part = content[i] as MappableContentPart | undefined;
const uiPart = toUIPart(part, i, context);
parts.push(uiPart);
if (part == null) {
continue;
}
pushUnique(
agentIds,
part.agentId ??
(part.type === ContentTypes.TOOL_CALL ? part.tool_call?.agentId : undefined),
);
pushUnique(groupIds, part.groupId);
if (uiPart.type === 'text') {
joinedText += uiPart.text;
} else if (uiPart.type === 'data-agent-update') {
pushUnique(agentIds, uiPart.data.agent_update.agentId);
} else if (uiPart.type === 'data-activity-label') {
activityLabels.push(uiPart.data);
} else if (uiPart.type === 'data-steer') {
steers.push(uiPart.data);
} else if (uiPart.type === 'data-summary') {
summaries.push(uiPart.data);
}
}
} else {
parts.push({ type: 'text', text: message.text ?? '' });
}
const files = message.files ?? [];
for (let i = 0; i < files.length; i++) {
const filePart = toAttachmentFilePart(files[i], i);
if (filePart) {
parts.push(filePart);
}
}
pushSourceParts(parts, message.attachments);
const metadata: UIMessageMetadata = {
conversationId: message.conversationId,
parentMessageId: message.parentMessageId,
...(message.sender !== undefined && { sender: message.sender }),
...(message.model !== undefined && { model: message.model }),
...(message.endpoint !== undefined && { endpoint: message.endpoint }),
...(message.error !== undefined && { error: message.error }),
...(message.unfinished !== undefined && { unfinished: message.unfinished }),
...(message.createdAt !== undefined && { createdAt: message.createdAt }),
...(contentless && { contentless: true }),
...(contentless && content && { emptyContent: true }),
...(message.attachments !== undefined && { attachments: message.attachments }),
...(!contentless &&
message.text !== undefined &&
message.text !== joinedText && { text: message.text }),
...(agentIds.size > 0 && { agentIds: Array.from(agentIds) }),
...(groupIds.size > 0 && { groupIds: Array.from(groupIds) }),
...(activityLabels.length > 0 && { activityLabels }),
...(steers.length > 0 && { steers }),
...(summaries.length > 0 && { summaries }),
};
return {
id: message.messageId,
role: message.isCreatedByUser ? 'user' : 'assistant',
metadata,
parts,
};
}
const messageFields = ['sender', 'model', 'endpoint', 'error', 'unfinished', 'createdAt'] as const;
const pickMessageFields = (metadata: UIMessageMetadata | undefined) => {
const fields: Partial<Pick<TMessage, (typeof messageFields)[number]>> = {};
if (!metadata) {
return fields;
}
for (const key of messageFields) {
if (metadata[key] !== undefined) {
Object.assign(fields, { [key]: metadata[key] });
}
}
return fields;
};
const joinPartText = (parts: ReadonlyArray<UIMessagePart | undefined>) => {
let text = '';
for (const part of parts) {
if (part?.type === 'text') {
text += part.text;
}
}
return text;
};
/**
* `TMessage.text` of a content-bearing message is not derived from its parts, so the stored text
* is kept unless the text parts changed, in which case the view's text wins. Without a base the
* stored text travels in `metadata.text`.
*/
const resolveText = (text: string, metadata: UIMessageMetadata | undefined, base?: TMessage) => {
if (metadata?.contentless) {
return text;
}
if (base?.text === undefined) {
return metadata?.text ?? text;
}
const baseText = joinPartText((base.content ?? []).map((part) => toUIPart(part)));
return text === baseText ? base.text : text;
};
/**
* Attachment `file` parts describe `message.files`: each is matched to its stored entry by the
* position and path it was viewed with (so an edited `url` still finds it, and entries sharing a
* path stay distinct), the view's edits are applied, parts built by hand become new entries, and stored entries the view never showed keep their slots
* while the visible entries fill the others in view order.
*/
const reconcileFiles = (
attachments: ReadonlyArray<UIFilePart>,
baseFiles: TMessage['files'],
): TMessage['files'] => {
if (!baseFiles && attachments.length === 0) {
return undefined;
}
const claimed = new Set<Partial<TFile>>();
/** A viewed part names its stored entry; a hand-built one takes the first unclaimed match. */
const findStored = (part: UIFilePart) => {
const metadata = part.providerMetadata?.librechat;
if (metadata?.source === 'attachment') {
const candidate = baseFiles?.[metadata.index];
return candidate?.filepath === metadata.filepath ? candidate : undefined;
}
return baseFiles?.find((file) => file.filepath === part.url && !claimed.has(file));
};
const visible = attachments.map((part) => {
const stored = findStored(part);
if (stored) {
claimed.add(stored);
return applyFileEdits(stored, part, 'application/octet-stream');
}
return {
filepath: part.url,
...(part.filename && { filename: part.filename }),
type: part.mediaType,
};
});
const files: Partial<TFile>[] = [];
let next = 0;
for (const file of baseFiles ?? []) {
if (!file.filepath) {
files.push(file);
} else if (next < visible.length) {
files.push(visible[next++]);
}
}
return files.concat(visible.slice(next));
};
/** Reads an identity field from metadata, where an explicit `null` is a value, not an absence. */
const pickIdentity = <K extends 'conversationId' | 'parentMessageId'>(
key: K,
metadata: UIMessageMetadata | undefined,
base: TMessage | undefined,
): TMessage[K] => {
if (metadata && metadata[key] !== undefined) {
return metadata[key];
}
return base?.[key] ?? null;
};
/**
* Maps a `UIMessage` back onto a `TMessage`. `base` is the stored message with the same id,
* whose fields the UI view does not carry (tree position, feedback, token counts) are kept.
* A stored message round-trips only with its base: without one the message is rebuilt from the
* view and its metadata, and a file record keeps only what its part shows (path, name, type).
* One pass over the parts collects the text, the content and the attachments.
*/
export function fromUIMessage(message: UIMessage, base?: TMessage): TMessage {
const metadata = message.metadata;
const contentless = metadata?.contentless === true;
const writer = createContentWriter();
const attachments: UIFilePart[] = [];
let text = '';
let addedContent = false;
for (const part of message.parts) {
if (part.type === 'text') {
text += part.text;
} else if (isAttachmentPart(part)) {
attachments.push(part);
continue;
} else if (part.type !== 'source-url' && part.type !== 'step-start') {
addedContent = true;
}
writer.write(part);
}
const writesContent = !contentless || addedContent;
const next: TMessage = {
...base,
...pickMessageFields(metadata),
messageId: message.id,
isCreatedByUser: message.role === 'user',
conversationId: pickIdentity('conversationId', metadata, base),
parentMessageId: pickIdentity('parentMessageId', metadata, base),
text: resolveText(text, metadata, base),
};
if (writesContent) {
next.content = writer.content;
} else if (metadata?.emptyContent && base?.content === undefined) {
next.content = [];
}
if (base?.attachments === undefined && metadata?.attachments !== undefined) {
next.attachments = metadata.attachments;
}
const files = reconcileFiles(attachments, base?.files);
if (files) {
next.files = files;
}
return next;
}