⏸ refactor: Improve UX for Parallel Streams (Multi-Convo) (#11096)

* 🌊 feat: Implement multi-conversation feature with added conversation context and payload adjustments

* refactor: Replace isSubmittingFamily with isSubmitting across message components for consistency

* feat: Add loadAddedAgent and processAddedConvo for multi-conversation agent execution

* refactor: Update ContentRender usage to conditionally render PlaceholderRow based on isLast and isSubmitting

* WIP: first pass, sibling index

* feat: Enhance multi-conversation support with agent tracking and display improvements

* refactor: Introduce isEphemeralAgentId utility and update related logic for agent handling

* refactor: Implement createDualMessageContent utility for sibling message display and enhance useStepHandler for added conversations

* refactor: duplicate tools for added agent if ephemeral and primary agent is also ephemeral

* chore: remove deprecated multimessage rendering

* refactor: enhance dual message content creation and agent handling for parallel rendering

* refactor: streamline message rendering and submission handling by removing unused state and optimizing conditional logic

* refactor: adjust content handling in parallel mode to utilize existing content for improved agent display

* refactor: update @librechat/agents dependency to version 3.0.53

* refactor: update @langchain/core and @librechat/agents dependencies to latest versions

* refactor: remove deprecated @langchain/core dependency from package.json

* chore: remove unused SearchToolConfig and GetSourcesParams types from web.ts

* refactor: remove unused message properties from Message component

* refactor: enhance parallel content handling with groupId support in ContentParts and useStepHandler

* refactor: implement parallel content styling in Message, MessageRender, and ContentRender components. use explicit model name

* refactor: improve agent ID handling in createDualMessageContent for dual message display

* refactor: simplify title generation in AddedConvo by removing unused sender and preset logic

* refactor: replace string interpolation with cn utility for className in HoverButtons component

* refactor: enhance agent ID handling by adding suffix management for parallel agents and updating related components

* refactor: enhance column ordering in ContentParts by sorting agents with suffix management

* refactor: update @librechat/agents dependency to version 3.0.55

* feat: implement parallel content rendering with metadata support

- Added `ParallelContentRenderer` and `ParallelColumns` components for rendering messages in parallel based on groupId and agentId.
- Introduced `contentMetadataMap` to store metadata for each content part, allowing efficient parallel content detection.
- Updated `Message` and `ContentRender` components to utilize the new metadata structure for rendering.
- Modified `useStepHandler` to manage content indices and metadata during message processing.
- Enhanced `IJobStore` interface and its implementations to support storing and retrieving content metadata.
- Updated data schemas to include `contentMetadataMap` for messages, enabling multi-agent and parallel execution scenarios.

* refactor: update @librechat/agents dependency to version 3.0.56

* refactor: remove unused EPHEMERAL_AGENT_ID constant and simplify agent ID check

* refactor: enhance multi-agent message processing and primary agent determination

* refactor: implement branch message functionality for parallel responses

* refactor: integrate added conversation retrieval into message editing and regeneration processes

* refactor: remove unused isCard and isMultiMessage props from MessageRender and ContentRender components

* refactor: update @librechat/agents dependency to version 3.0.60

* refactor: replace usage of EPHEMERAL_AGENT_ID constant with isEphemeralAgentId function for improved clarity and consistency

* refactor: standardize agent ID format in tests for consistency

* chore: move addedConvo property to the correct position in payload construction

* refactor: rename agent_id values in loadAgent tests for clarity

* chore: reorder props in ContentParts component for improved readability

* refactor: rename variable 'content' to 'result' for clarity in RedisJobStore tests

* refactor: streamline useMessageActions by removing duplicate handleFeedback assignment

* chore: revert placeholder rendering logic MessageRender and ContentRender components to original

* refactor: implement useContentMetadata hook for optimized content metadata handling

* refactor: remove contentMetadataMap and related logic from the codebase and revert back to agentId/groupId in content parts

- Eliminated contentMetadataMap from various components and services, simplifying the handling of message content.
- Updated functions to directly access agentId and groupId from content parts instead of relying on a separate metadata map.
- Adjusted related hooks and components to reflect the removal of contentMetadataMap, ensuring consistent handling of message content.
- Updated tests and documentation to align with the new structure of message content handling.

* refactor: remove logging from groupParallelContent function to clean up output

* refactor: remove model parameter from TBranchMessageRequest type for simplification

* refactor: enhance branch message creation by stripping metadata for standalone content

* chore: streamline branch message creation by simplifying content filtering and removing unnecessary metadata checks

* refactor: include attachments in branch message creation for improved content handling

* refactor: streamline agent content processing by consolidating primary agent identification and filtering logic

* refactor: simplify multi-agent message processing by creating a dedicated mapping method and enhancing content filtering

* refactor: remove unused parameter from loadEphemeralAgent function for cleaner code

* refactor: update groupId handling in metadata to only set when provided by the server

packages/data-provider/src/api-endpoints.ts

@@ -66,6 +66,8 @@ export const messages = (params: q.MessagesListParams) => {
 
 export const messagesArtifacts = (messageId: string) => `${messagesRoot}/artifact/${messageId}`;
 
+export const messagesBranch = () => `${messagesRoot}/branch`;
+
 const shareRoot = `${BASE_URL}/api/share`;
 export const shareMessages = (shareId: string) => `${shareRoot}/${shareId}`;
 export const getSharedLink = (conversationId: string) => `${shareRoot}/link/${conversationId}`;

packages/data-provider/src/createPayload.ts

@@ -5,6 +5,7 @@ import * as s from './schemas';
 export default function createPayload(submission: t.TSubmission) {
   const {
     isEdited,
+    addedConvo,
     userMessage,
     isContinued,
     isTemporary,
@@ -32,6 +33,7 @@ export default function createPayload(submission: t.TSubmission) {
     ...userMessage,
     ...endpointOption,
     endpoint,
+    addedConvo,
     isTemporary,
     isRegenerate,
     editedContent,

packages/data-provider/src/data-service.ts

@@ -756,6 +756,12 @@ export const editArtifact = async ({
   return request.post(endpoints.messagesArtifacts(messageId), params);
 };
 
+export const branchMessage = async (
+  payload: m.TBranchMessageRequest,
+): Promise<m.TBranchMessageResponse> => {
+  return request.post(endpoints.messagesBranch(), payload);
+};
+
 export function getMessagesByConvoId(conversationId: string): Promise<s.TMessage[]> {
   if (
     conversationId === config.Constants.NEW_CONVO ||

packages/data-provider/src/parsers.ts

@@ -197,7 +197,7 @@ const extractOmniVersion = (modelStr: string): string => {
   return '';
 };
 
-export const getResponseSender = (endpointOption: t.TEndpointOption): string => {
+export const getResponseSender = (endpointOption: Partial<t.TEndpointOption>): string => {
   const {
     model: _m,
     endpoint: _e,
@@ -216,10 +216,11 @@ export const getResponseSender = (endpointOption: t.TEndpointOption): string =>
   if (
     [EModelEndpoint.openAI, EModelEndpoint.bedrock, EModelEndpoint.azureOpenAI].includes(endpoint)
   ) {
-    if (chatGptLabel) {
-      return chatGptLabel;
-    } else if (modelLabel) {
+    if (modelLabel) {
       return modelLabel;
+    } else if (chatGptLabel) {
+      // @deprecated - prefer modelLabel
+      return chatGptLabel;
     } else if (model && extractOmniVersion(model)) {
       return extractOmniVersion(model);
     } else if (model && (model.includes('mistral') || model.includes('codestral'))) {
@@ -255,6 +256,7 @@ export const getResponseSender = (endpointOption: t.TEndpointOption): string =>
     if (modelLabel) {
       return modelLabel;
     } else if (chatGptLabel) {
+      // @deprecated - prefer modelLabel
       return chatGptLabel;
     } else if (model && extractOmniVersion(model)) {
       return extractOmniVersion(model);
@@ -414,3 +416,138 @@ export function replaceSpecialVars({ text, user }: { text: string; user?: t.TUse
 
   return result;
 }
+
+/**
+ * Parsed ephemeral agent ID result
+ */
+export type ParsedEphemeralAgentId = {
+  endpoint: string;
+  model: string;
+  sender?: string;
+  index?: number;
+};
+
+/**
+ * Encodes an ephemeral agent ID from endpoint, model, optional sender, and optional index.
+ * Uses __ to replace : (reserved in graph node names) and ___ to separate sender.
+ *
+ * Format: endpoint__model___sender or endpoint__model___sender____index (if index provided)
+ *
+ * @example
+ * encodeEphemeralAgentId({ endpoint: 'openAI', model: 'gpt-4o', sender: 'GPT-4o' })
+ * // => 'openAI__gpt-4o___GPT-4o'
+ *
+ * @example
+ * encodeEphemeralAgentId({ endpoint: 'openAI', model: 'gpt-4o', sender: 'GPT-4o', index: 1 })
+ * // => 'openAI__gpt-4o___GPT-4o____1'
+ */
+export function encodeEphemeralAgentId({
+  endpoint,
+  model,
+  sender,
+  index,
+}: {
+  endpoint: string;
+  model: string;
+  sender?: string;
+  index?: number;
+}): string {
+  const base = `${endpoint}:${model}`.replace(/:/g, '__');
+  let result = base;
+  if (sender) {
+    // Use ___ as separator before sender to distinguish from __ in model names
+    result = `${base}___${sender.replace(/:/g, '__')}`;
+  }
+  if (index != null) {
+    // Use ____ (4 underscores) as separator for index
+    result = `${result}____${index}`;
+  }
+  return result;
+}
+
+/**
+ * Parses an ephemeral agent ID back into its components.
+ * Returns undefined if the ID doesn't match the expected format.
+ *
+ * Format: endpoint__model___sender or endpoint__model___sender____index
+ * - ____ (4 underscores) separates optional index suffix
+ * - ___ (triple underscore) separates model from optional sender
+ * - __ (double underscore) replaces : in endpoint/model names
+ *
+ * @example
+ * parseEphemeralAgentId('openAI__gpt-4o___GPT-4o')
+ * // => { endpoint: 'openAI', model: 'gpt-4o', sender: 'GPT-4o' }
+ *
+ * @example
+ * parseEphemeralAgentId('openAI__gpt-4o___GPT-4o____1')
+ * // => { endpoint: 'openAI', model: 'gpt-4o', sender: 'GPT-4o', index: 1 }
+ */
+export function parseEphemeralAgentId(agentId: string): ParsedEphemeralAgentId | undefined {
+  if (!agentId.includes('__')) {
+    return undefined;
+  }
+
+  // First check for index suffix (separated by ____)
+  let index: number | undefined;
+  let workingId = agentId;
+  if (agentId.includes('____')) {
+    const lastIndexSep = agentId.lastIndexOf('____');
+    const indexStr = agentId.slice(lastIndexSep + 4);
+    const parsedIndex = parseInt(indexStr, 10);
+    if (!isNaN(parsedIndex)) {
+      index = parsedIndex;
+      workingId = agentId.slice(0, lastIndexSep);
+    }
+  }
+
+  // Check for sender (separated by ___)
+  let sender: string | undefined;
+  let mainPart = workingId;
+  if (workingId.includes('___')) {
+    const [before, after] = workingId.split('___');
+    mainPart = before;
+    // Restore colons in sender if any
+    sender = after?.replace(/__/g, ':');
+  }
+
+  const [endpoint, ...modelParts] = mainPart.split('__');
+  if (!endpoint || modelParts.length === 0) {
+    return undefined;
+  }
+  // Restore colons in model name (model names can contain colons like claude-3:opus)
+  const model = modelParts.join(':');
+  return { endpoint, model, sender, index };
+}
+
+/**
+ * Checks if an agent ID represents an ephemeral (non-saved) agent.
+ * Real agent IDs always start with "agent_", so anything else is ephemeral.
+ */
+export function isEphemeralAgentId(agentId: string | null | undefined): boolean {
+  return !agentId?.startsWith('agent_');
+}
+
+/**
+ * Strips the index suffix (____N) from an agent ID if present.
+ * Works with both ephemeral and real agent IDs.
+ *
+ * @example
+ * stripAgentIdSuffix('agent_abc123____1') // => 'agent_abc123'
+ * stripAgentIdSuffix('openAI__gpt-4o___GPT-4o____1') // => 'openAI__gpt-4o___GPT-4o'
+ * stripAgentIdSuffix('agent_abc123') // => 'agent_abc123' (unchanged)
+ */
+export function stripAgentIdSuffix(agentId: string): string {
+  return agentId.replace(/____\d+$/, '');
+}
+
+/**
+ * Appends an index suffix (____N) to an agent ID.
+ * Used to distinguish parallel agents with the same base ID.
+ *
+ * @example
+ * appendAgentIdSuffix('agent_abc123', 1) // => 'agent_abc123____1'
+ * appendAgentIdSuffix('openAI__gpt-4o___GPT-4o', 1) // => 'openAI__gpt-4o___GPT-4o____1'
+ */
+export function appendAgentIdSuffix(agentId: string, index: number): string {
+  return `${agentId}____${index}`;
+}

packages/data-provider/src/types.ts

@@ -109,6 +109,8 @@ export type TPayload = Partial<TMessage> &
     isTemporary: boolean;
     ephemeralAgent?: TEphemeralAgent | null;
     editedContent?: TEditedContent | null;
+    /** Added conversation for multi-convo feature */
+    addedConvo?: TConversation;
   };
 
 export type TEditedContent =
@@ -136,6 +138,8 @@ export type TSubmission = {
   clientTimestamp?: string;
   ephemeralAgent?: TEphemeralAgent | null;
   editedContent?: TEditedContent | null;
+  /** Added conversation for multi-convo feature */
+  addedConvo?: TConversation;
 };
 
 export type EventSubmission = Omit<TSubmission, 'initialResponse'> & { initialResponse: TMessage };

packages/data-provider/src/types/agents.ts

@@ -166,8 +166,11 @@ export namespace Agents {
     type: StepTypes;
     id: string; // #new
     runId?: string; // #new
+    agentId?: string; // #new
     index: number; // #new
     stepIndex?: number; // #new
+    /** Group ID for parallel content - parts with same groupId are displayed in columns */
+    groupId?: number; // #new
     stepDetails: StepDetails;
     usage: null | object;
   };

packages/data-provider/src/types/assistants.ts

@@ -466,8 +466,17 @@ export type PartMetadata = {
   action?: boolean;
   auth?: string;
   expires_at?: number;
+  /** Index indicating parallel sibling content (same stepIndex in multi-agent runs) */
+  siblingIndex?: number;
+  /** Agent ID for parallel agent rendering - identifies which agent produced this content */
+  agentId?: string;
+  /** Group ID for parallel content - parts with same groupId are displayed in columns */
+  groupId?: number;
 };
 
+/** Metadata for parallel content rendering - subset of PartMetadata */
+export type ContentMetadata = Pick<PartMetadata, 'agentId' | 'groupId'>;
+
 export type ContentPart = (
   | CodeToolCall
   | RetrievalToolCall
@@ -482,18 +491,18 @@ export type ContentPart = (
 export type TextData = (Text & PartMetadata) | undefined;
 
 export type TMessageContentParts =
-  | {
+  | ({
       type: ContentTypes.ERROR;
       text?: string | TextData;
       error?: string;
-    }
-  | { type: ContentTypes.THINK; think?: string | TextData }
-  | {
+    } & ContentMetadata)
+  | ({ type: ContentTypes.THINK; think?: string | TextData } & ContentMetadata)
+  | ({
       type: ContentTypes.TEXT;
       text?: string | TextData;
       tool_call_ids?: string[];
-    }
-  | {
+    } & ContentMetadata)
+  | ({
       type: ContentTypes.TOOL_CALL;
       tool_call: (
         | CodeToolCall
@@ -503,10 +512,10 @@ export type TMessageContentParts =
         | Agents.AgentToolCall
       ) &
         PartMetadata;
-    }
-  | { type: ContentTypes.IMAGE_FILE; image_file: ImageFile & PartMetadata }
-  | Agents.AgentUpdate
-  | Agents.MessageContentImageUrl;
+    } & ContentMetadata)
+  | ({ type: ContentTypes.IMAGE_FILE; image_file: ImageFile & PartMetadata } & ContentMetadata)
+  | (Agents.AgentUpdate & ContentMetadata)
+  | (Agents.MessageContentImageUrl & ContentMetadata);
 
 export type StreamContentData = TMessageContentParts & {
   /** The index of the current content part */

packages/data-provider/src/types/mutations.ts

@@ -381,6 +381,20 @@ export type EditArtifactOptions = MutationOptions<
   Error
 >;
 
+export type TBranchMessageRequest = {
+  messageId: string;
+  agentId: string;
+};
+
+export type TBranchMessageResponse = types.TMessage;
+
+export type BranchMessageOptions = MutationOptions<
+  TBranchMessageResponse,
+  TBranchMessageRequest,
+  unknown,
+  Error
+>;
+
 export type TLogoutResponse = {
   message: string;
   redirect?: string;

packages/data-provider/src/types/web.ts

@@ -1,5 +1,4 @@
 import type { Logger as WinstonLogger } from 'winston';
-import type { RunnableConfig } from '@langchain/core/runnables';
 
 export type SearchRefType = 'search' | 'image' | 'news' | 'video' | 'ref';
 
@@ -174,16 +173,6 @@ export interface CohereRerankerResponse {
 export type SafeSearchLevel = 0 | 1 | 2;
 
 export type Logger = WinstonLogger;
-export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
-  logger?: Logger;
-  safeSearch?: SafeSearchLevel;
-  jinaApiKey?: string;
-  jinaApiUrl?: string;
-  cohereApiKey?: string;
-  rerankerType?: RerankerType;
-  onSearchResults?: (results: SearchResult, runnableConfig?: RunnableConfig) => void;
-  onGetHighlights?: (link: string) => void;
-}
 export interface MediaReference {
   originalUrl: string;
   title?: string;
@@ -290,18 +279,6 @@ export interface FirecrawlScraperConfig {
   logger?: Logger;
 }
 
-export type GetSourcesParams = {
-  query: string;
-  date?: DATE_RANGE;
-  country?: string;
-  numResults?: number;
-  safeSearch?: SearchToolConfig['safeSearch'];
-  images?: boolean;
-  videos?: boolean;
-  news?: boolean;
-  type?: 'search' | 'images' | 'videos' | 'news';
-};
-
 /** Serper API */
 export interface VideoResult {
   title?: string;
@@ -609,12 +586,3 @@ export interface SearXNGResult {
   publishedDate?: string;
   img_src?: string;
 }
-
-export type ProcessSourcesFields = {
-  result: SearchResult;
-  numElements: number;
-  query: string;
-  news: boolean;
-  proMode: boolean;
-  onGetHighlights: SearchToolConfig['onGetHighlights'];
-};