@librechat/agents 3.0.53 → 3.0.54

package/src/scripts/sequential-full-metadata-test.ts

@@ -0,0 +1,197 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { Providers, GraphEvents } from '@/common';
+import { sleep } from '@/utils/run';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+/**
+ * Dump ALL metadata for SEQUENTIAL execution to compare with parallel
+ */
+async function testSequentialMetadata() {
+  console.log('Dumping FULL metadata for SEQUENTIAL execution...\n');
+
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  const allMetadata: Array<{
+    event: string;
+    timestamp: number;
+    metadata: Record<string, unknown>;
+  }> = [];
+  const startTime = Date.now();
+
+  // Sequential chain: agent_a -> agent_b
+  const agents: t.AgentInputs[] = [
+    {
+      agentId: 'agent_a',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are Agent A. Just say "Hello from A" in one sentence.`,
+    },
+    {
+      agentId: 'agent_b',
+      provider: Providers.ANTHROPIC,
+      clientOptions: {
+        modelName: 'claude-haiku-4-5',
+        apiKey: process.env.ANTHROPIC_API_KEY,
+      },
+      instructions: `You are Agent B. Just say "Hello from B" in one sentence.`,
+    },
+  ];
+
+  // Sequential edge: A -> B (using edgeType not type)
+  const edges: t.GraphEdge[] = [
+    { from: 'agent_a', to: 'agent_b', edgeType: 'direct' },
+  ];
+
+  const captureMetadata = (
+    eventName: string,
+    metadata?: Record<string, unknown>
+  ) => {
+    if (metadata) {
+      allMetadata.push({
+        event: eventName,
+        timestamp: Date.now() - startTime,
+        metadata: { ...metadata },
+      });
+    }
+  };
+
+  const customHandlers = {
+    [GraphEvents.CHAT_MODEL_END]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        captureMetadata('CHAT_MODEL_END', metadata);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_START]: {
+      handle: (
+        _event: string,
+        _data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        captureMetadata('CHAT_MODEL_START', metadata);
+      },
+    },
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP,
+        data: t.StreamEventData,
+        metadata?: Record<string, unknown>
+      ): void => {
+        captureMetadata('ON_RUN_STEP', metadata);
+        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 => {
+        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 => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+  };
+
+  const runConfig: t.RunConfig = {
+    runId: `sequential-metadata-${Date.now()}`,
+    graphConfig: {
+      type: 'multi-agent',
+      agents,
+      edges,
+    },
+    customHandlers,
+    returnContent: true,
+  };
+
+  try {
+    const run = await Run.create(runConfig);
+
+    const userMessage = `Hi`;
+    conversationHistory.push(new HumanMessage(userMessage));
+
+    const config = {
+      configurable: {
+        thread_id: 'sequential-metadata-test-1',
+      },
+      streamMode: 'values',
+      version: 'v2' as const,
+    };
+
+    await run.processStream({ messages: conversationHistory }, config);
+
+    // Print ALL CHAT_MODEL_START metadata (don't dedupe)
+    console.log(
+      '\n\n========== ALL CHAT_MODEL_START EVENTS (SEQUENTIAL) ==========\n'
+    );
+    for (const entry of allMetadata) {
+      if (entry.event === 'CHAT_MODEL_START') {
+        const node = entry.metadata.langgraph_node as string;
+        console.log(`\n--- ${node} (at ${entry.timestamp}ms) ---`);
+        console.dir(entry.metadata, { depth: null });
+      }
+    }
+
+    console.log('\n\n========== ALL EVENTS ==========\n');
+    for (const entry of allMetadata) {
+      console.log(
+        `[${entry.timestamp}ms] ${entry.event}: ${entry.metadata.langgraph_node}`
+      );
+    }
+
+    // Key comparison
+    console.log(
+      '\n\n========== KEY FIELDS COMPARISON (SEQUENTIAL) ==========\n'
+    );
+
+    const agentMetadataMap = new Map<string, Record<string, unknown>>();
+    for (const entry of allMetadata) {
+      if (entry.event === 'CHAT_MODEL_START') {
+        const node = entry.metadata.langgraph_node as string;
+        if (!agentMetadataMap.has(node)) {
+          agentMetadataMap.set(node, entry.metadata);
+        }
+      }
+    }
+
+    for (const [node, meta] of agentMetadataMap) {
+      console.log(`${node}:`);
+      console.log(`  langgraph_step: ${meta.langgraph_step}`);
+      console.log(
+        `  langgraph_triggers: ${JSON.stringify(meta.langgraph_triggers)}`
+      );
+      console.log(`  checkpoint_ns: ${meta.checkpoint_ns}`);
+      console.log(`  __pregel_task_id: ${meta.__pregel_task_id}`);
+      console.log(`  langgraph_path: ${JSON.stringify(meta.langgraph_path)}`);
+      console.log();
+    }
+
+    await sleep(1000);
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+testSequentialMetadata();

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

@@ -0,0 +1,192 @@
+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 } = 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.dir(contentParts, { 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,
@@ -581,12 +584,13 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       };
     }
 
-    // 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;
+    // Apply agentId and groupId to content part for parallel execution attribution
+    const meta = contentMetaMap.get(index);
+    if (meta?.agentId !== undefined) {
+      (contentParts[index] as t.MessageContentComplex).agentId = meta.agentId;
+    }
+    if (meta?.groupId !== undefined) {
+      (contentParts[index] as t.MessageContentComplex).groupId = meta.groupId;
     }
   };
 
@@ -606,9 +610,19 @@ 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)
+      // Track agentId and groupId for this content index
+      const existingMeta = contentMetaMap.get(runStep.index) ?? {};
       if (runStep.agentId != null && runStep.agentId !== '') {
-        contentAgentMap.set(runStep.index, runStep.agentId);
+        existingMeta.agentId = runStep.agentId;
+      }
+      if (runStep.groupId != null) {
+        existingMeta.groupId = runStep.groupId;
+      }
+      if (
+        (existingMeta.agentId != null && existingMeta.agentId !== '') ||
+        existingMeta.groupId != null
+      ) {
+        contentMetaMap.set(runStep.index, existingMeta);
       }
 
       // Store tool call IDs if present
@@ -721,5 +735,5 @@ export function createContentAggregator(): t.ContentAggregatorResult {
     }
   };
 
-  return { contentParts, aggregateContent, stepMap, contentAgentMap };
+  return { contentParts, aggregateContent, stepMap };
 }

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;
@@ -334,6 +345,8 @@ export type MessageContentComplex = (
   tool_call_ids?: string[];
   // Optional agentId for parallel execution attribution
   agentId?: string;
+  // Optional groupId for parallel group attribution
+  groupId?: number;
 };
 
 export interface TMessage {
@@ -401,6 +414,4 @@ export type ContentAggregatorResult = {
   stepMap: Map<string, RunStep | undefined>;
   contentParts: Array<MessageContentComplex | undefined>;
   aggregateContent: ContentAggregator;
-  // Maps content index to agentId for parallel execution attribution
-  contentAgentMap: Map<number, string>;
 };