@librechat/agents 3.0.53 → 3.0.55

package/src/scripts/single-agent-metadata-test.ts

@@ -0,0 +1,198 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import { v4 as uuidv4 } from 'uuid';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Single agent test with extensive metadata logging
+ * Compare with multi-agent-parallel-start.ts to see metadata differences
+ */
+async function testSingleAgent() {
+  console.log('Testing Single Agent with Metadata Logging...\n');
+
+  // Set up content aggregator
+  const { contentParts, aggregateContent, contentMetadataMap } =
+    createContentAggregator();
+
+  const startTime = Date.now();
+
+  // Create custom handlers with extensive metadata logging
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  COMPLETED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+        const elapsed = Date.now() - startTime;
+        console.log(`⏱️  STARTED at ${elapsed}ms`);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP_COMPLETED ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_RUN_STEP_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.RunStepDeltaEvent });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== ON_MESSAGE_DELTA ======');
+        console.log('DATA:');
+        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  // Create single-agent run configuration (standard graph, not multi-agent)
+  const runConfig: t.RunConfig = {
+    runId: `single-agent-${Date.now()}`,
+    graphConfig: {
+      type: 'standard',
+      llmConfig: {
+        provider: Providers.ANTHROPIC,
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are a helpful AI assistant. Keep your response concise (50-100 words).`,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    // Create and execute the run
+    const run = await Run.create(runConfig);
+
+    // Debug: Log the graph structure
+    console.log('=== DEBUG: Graph Structure ===');
+    const graph = (run as any).Graph;
+    console.log('Graph exists:', !!graph);
+    if (graph) {
+      console.log('Graph type:', graph.constructor.name);
+      console.log('AgentContexts exists:', !!graph.agentContexts);
+      if (graph.agentContexts) {
+        console.log('AgentContexts size:', graph.agentContexts.size);
+        for (const [agentId, context] of graph.agentContexts) {
+          console.log(`\nAgent: ${agentId}`);
+          console.log(
+            `Tools: ${context.tools?.map((t: any) => t.name || 'unnamed').join(', ') || 'none'}`
+          );
+        }
+      }
+    }
+    console.log('=== END DEBUG ===\n');
+
+    const userMessage = `What are the best approaches to learning a new programming language?`;
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    console.log('Invoking single-agent graph...\n');
+
+    const config = {
+      configurable: {
+        thread_id: 'single-agent-conversation-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    // Process with streaming
+    const inputs = {
+      messages: conversationHistory,
+    };
+
+    const finalContentParts = await run.processStream(inputs, config);
+    const finalMessages = run.getRunMessages();
+
+    if (finalMessages) {
+      conversationHistory.push(...finalMessages);
+    }
+
+    console.log('\n\n========== SUMMARY ==========');
+    console.log('Final content parts:', contentParts.length, 'parts');
+    console.log('\n=== Content Parts (clean, no metadata) ===');
+    console.dir(contentParts, { depth: null });
+    console.log(
+      '\n=== Content Metadata Map (should be empty for single-agent) ==='
+    );
+    console.dir(Object.fromEntries(contentMetadataMap), { depth: null });
+    console.log('====================================\n');
+
+    await sleep(3000);
+  } catch (error) {
+    console.error('Error in single-agent test:', error);
+  }
+}
+
+// Run the test
+testSingleAgent();

package/src/scripts/test-thinking-handoff.ts

@@ -32,6 +32,14 @@ async function testThinkingHandoff() {
         }
       },
     },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (_event: string, data: t.StreamEventData): void => {
+        const runStep = data as t.RunStep;
+        console.log(
+          `\n📍 ON_RUN_STEP: agentId=${runStep.agentId}, groupId=${runStep.groupId}`
+        );
+      },
+    },
   };
 
   // Create the graph configuration

package/src/scripts/tools.ts

@@ -21,15 +21,36 @@ async function testStandardStreaming(): Promise<void> {
     [GraphEvents.TOOL_END]: new ToolEndHandler(undefined, (name?: string) => {
       return true;
     }),
-    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_END METADATA ======');
+        console.dir(metadata, { depth: null });
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        console.log('\n====== CHAT_MODEL_START METADATA ======');
+        console.dir(metadata, { depth: null });
+      },
+    },
     [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
     [GraphEvents.ON_RUN_STEP_COMPLETED]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP_COMPLETED,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         console.log('====== ON_RUN_STEP_COMPLETED ======');
-        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({
           event,
           data: data as unknown as { result: t.ToolEndEvent },
@@ -39,10 +60,14 @@ async function testStandardStreaming(): Promise<void> {
     [GraphEvents.ON_RUN_STEP]: {
       handle: (
         event: GraphEvents.ON_RUN_STEP,
-        data: t.StreamEventData
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
       ): void => {
         console.log('====== ON_RUN_STEP ======');
+        console.log('DATA:');
         console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
         aggregateContent({ event, data: data as t.RunStep });
       },
     },
@@ -51,8 +76,6 @@ async function testStandardStreaming(): Promise<void> {
         event: GraphEvents.ON_RUN_STEP_DELTA,
         data: t.StreamEventData
       ): void => {
-        console.log('====== ON_RUN_STEP_DELTA ======');
-        console.dir(data, { depth: null });
         aggregateContent({ event, data: data as t.RunStepDeltaEvent });
       },
     },
@@ -61,8 +84,6 @@ async function testStandardStreaming(): Promise<void> {
         event: GraphEvents.ON_MESSAGE_DELTA,
         data: t.StreamEventData
       ): void => {
-        console.log('====== ON_MESSAGE_DELTA ======');
-        console.dir(data, { depth: null });
         aggregateContent({ event, data: data as t.MessageDeltaEvent });
       },
     },
@@ -71,8 +92,6 @@ async function testStandardStreaming(): Promise<void> {
         event: GraphEvents.ON_REASONING_DELTA,
         data: t.StreamEventData
       ) => {
-        console.log('====== ON_REASONING_DELTA ======');
-        console.dir(data, { depth: null });
         aggregateContent({ event, data: data as t.ReasoningDeltaEvent });
       },
     },
@@ -83,7 +102,8 @@ async function testStandardStreaming(): Promise<void> {
         metadata?: Record<string, unknown>
       ): void => {
         console.log('====== TOOL_START ======');
-        console.dir(data, { depth: null });
+        console.log('METADATA:');
+        console.dir(metadata, { depth: null });
       },
     },
   };

package/src/stream.ts

@@ -442,8 +442,11 @@ export function createContentAggregator(): t.ContentAggregatorResult {
   const contentParts: Array<t.MessageContentComplex | undefined> = [];
   const stepMap = new Map<string, t.RunStep>();
   const toolCallIdMap = new Map<string, string>();
-  // Track agentId for each content index (for parallel agent attribution)
-  const contentAgentMap = new Map<number, string>();
+  // Track agentId and groupId for each content index (applied to content parts)
+  const contentMetaMap = new Map<
+    number,
+    { agentId?: string; groupId?: number }
+  >();
 
   const updateContent = (
     index: number,
@@ -580,14 +583,6 @@ export function createContentAggregator(): t.ContentAggregatorResult {
         tool_call: newToolCall,
       };
     }
-
-    // Apply agentId to content part for parallel execution attribution
-    const agentId = contentAgentMap.get(index);
-    if (agentId !== undefined) {
-      (
-        contentParts[index] as t.MessageContentComplex & { agentId?: string }
-      ).agentId = agentId;
-    }
   };
 
   const aggregateContent = ({
@@ -606,9 +601,20 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const runStep = data as t.RunStep;
       stepMap.set(runStep.id, runStep);
 
-      // Track agentId for this content index (for parallel execution)
-      if (runStep.agentId != null && runStep.agentId !== '') {
-        contentAgentMap.set(runStep.index, runStep.agentId);
+      // Track agentId (MultiAgentGraph) and groupId (parallel execution) separately
+      // - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
+      // - groupId: present only for parallel execution (enables column rendering)
+      const hasAgentId = runStep.agentId != null && runStep.agentId !== '';
+      const hasGroupId = runStep.groupId != null;
+      if (hasAgentId || hasGroupId) {
+        const existingMeta = contentMetaMap.get(runStep.index) ?? {};
+        if (hasAgentId) {
+          existingMeta.agentId = runStep.agentId;
+        }
+        if (hasGroupId) {
+          existingMeta.groupId = runStep.groupId;
+        }
+        contentMetaMap.set(runStep.index, existingMeta);
       }
 
       // Store tool call IDs if present
@@ -721,5 +727,10 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     }
   };
 
-  return { contentParts, aggregateContent, stepMap, contentAgentMap };
+  return {
+    contentParts,
+    aggregateContent,
+    stepMap,
+    contentMetadataMap: contentMetaMap,
+  };
 }

package/src/types/stream.ts

@@ -66,6 +66,17 @@ export type RunStep = {
   id: string; // #new
   runId?: string; // #new
   agentId?: string; // #new - tracks which agent this step belongs to
+  /**
+   * Group ID - incrementing number (1, 2, 3...) reflecting execution order.
+   * Agents with the same groupId run in parallel and should be rendered together.
+   * undefined means the agent runs sequentially (not part of any parallel group).
+   *
+   * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
+   * - researcher: undefined (sequential)
+   * - analyst1, analyst2, analyst3: 1 (first parallel group)
+   * - summarizer: undefined (sequential)
+   */
+  groupId?: number; // #new
   index: number; // #new
   stepIndex?: number; // #new
   stepDetails: StepDetails;
@@ -332,8 +343,6 @@ export type MessageContentComplex = (
     })
 ) & {
   tool_call_ids?: string[];
-  // Optional agentId for parallel execution attribution
-  agentId?: string;
 };
 
 export interface TMessage {
@@ -397,10 +406,20 @@ export type ContentAggregator = ({
         result: ToolEndEvent;
       };
 }) => void;
+/**
+ * Metadata for content parts in multi-agent runs.
+ * - agentId: present for all MultiAgentGraph runs (enables agent labels in UI)
+ * - groupId: present only for parallel execution (enables column rendering)
+ */
+export type ContentMetadata = {
+  agentId?: string;
+  groupId?: number;
+};
+
 export type ContentAggregatorResult = {
   stepMap: Map<string, RunStep | undefined>;
   contentParts: Array<MessageContentComplex | undefined>;
+  /** Map of content index to metadata (agentId, groupId). Only populated for MultiAgentGraph runs. */
+  contentMetadataMap: Map<number, ContentMetadata>;
   aggregateContent: ContentAggregator;
-  // Maps content index to agentId for parallel execution attribution
-  contentAgentMap: Map<number, string>;
 };