@librechat/agents 3.2.57 → 3.2.58

package/src/agents/__tests__/AgentContext.test.ts

@@ -42,6 +42,46 @@ describe('AgentContext', () => {
       schema: { type: 'object', properties: {} },
     }) as unknown as t.GenericTool;
 
+  describe('fromConfig — host-supplied graphTools', () => {
+    it('copies graphTools onto the context without aliasing the host array', () => {
+      const askTool = createMockTool('ask_user_question');
+      const hostGraphTools = [askTool];
+      const ctx = createBasicContext({
+        agentConfig: { graphTools: hostGraphTools },
+      });
+
+      expect(ctx.graphTools).toEqual([askTool]);
+      expect(ctx.graphTools).not.toBe(hostGraphTools);
+
+      /** The SDK pushes graph-managed tools (handoff/subagent) into this
+       *  array later — that must never mutate the host's input. */
+      (ctx.graphTools as t.GenericTool[]).push(createMockTool('subagent'));
+      expect(hostGraphTools).toHaveLength(1);
+    });
+
+    it('leaves graphTools undefined when the host supplies none (or an empty list)', () => {
+      expect(createBasicContext().graphTools).toBeUndefined();
+      expect(
+        createBasicContext({ agentConfig: { graphTools: [] } }).graphTools
+      ).toBeUndefined();
+    });
+
+    it('binds host graphTools to the model in event-driven mode', () => {
+      const askTool = createMockTool('ask_user_question');
+      const ctx = createBasicContext({
+        agentConfig: {
+          graphTools: [askTool],
+          toolDefinitions: [{ name: 'echo', description: 'host event tool' }],
+        },
+      });
+
+      const bound = ctx.getToolsForBinding() ?? [];
+      const names = (bound as Array<{ name?: string }>).map((t) => t.name);
+      expect(names).toContain('ask_user_question');
+      expect(names).toContain('echo');
+    });
+  });
+
   describe('System Runnable - Lazy Creation', () => {
     it('creates system runnable on first access', () => {
       const ctx = createBasicContext({

package/src/graphs/Graph.ts

@@ -1140,7 +1140,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   getToolCount(): number {
     const context = this.agentContexts.get(this.defaultAgentId);
     return (
-      (context?.tools?.length ?? 0) + (context?.toolDefinitions?.length ?? 0)
+      (context?.tools?.length ?? 0) +
+      (context?.toolDefinitions?.length ?? 0) +
+      /**
+       * Graph-managed + host-supplied direct tools (handoff, subagent,
+       * `AgentInputs.graphTools`) are bound to the model and token-accounted,
+       * so a count that omits them under-reports the run's tool surface
+       * (Codex #289 P3).
+       */
+      (context?.graphTools?.length ?? 0)
     );
   }
 
@@ -1286,10 +1294,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       graphTools && graphTools.length > 0
         ? [...baseTools, ...graphTools]
         : baseTools;
+    /**
+     * ToolNode treats a supplied `toolMap` as authoritative (it only derives
+     * one from `tools` when the param is undefined), so when graphTools force
+     * us to build a merged map here, an absent `currentToolMap` must be
+     * seeded from the BASE tools first — otherwise ordinary tools stay bound
+     * to the model but vanish from the execution map and every call to them
+     * fails as an unknown tool (Codex #289 round 2).
+     */
     const traditionalToolMap =
       graphTools && graphTools.length > 0
         ? new Map([
-          ...(currentToolMap ?? new Map()),
+          ...(currentToolMap ??
+              new Map(
+                baseTools
+                  .filter(
+                    (t): t is t.GenericTool & { name: string } => 'name' in t
+                  )
+                  .map((t) => [t.name, t] as [string, t.GenericTool])
+              )),
           ...graphTools
             .filter((t): t is t.GenericTool & { name: string } => 'name' in t)
             .map((t) => [t.name, t] as [string, t.GenericTool]),

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -73,6 +73,59 @@ const expectCompiledWorkflow = (
 };
 
 describe('LangGraph composition smoke tests', () => {
+  it('getToolCount includes direct graph tools (host-supplied graphTools) alongside instances and definitions', () => {
+    const askLikeTool = { name: 'ask_user_question' } as unknown as NonNullable<
+      t.AgentInputs['graphTools']
+    >[number];
+    const graph = new StandardGraph({
+      runId: 'toolcount-smoke',
+      agents: [
+        {
+          ...makeAgent('agent'),
+          toolDefinitions: [
+            { name: 'evt1', description: 'event tool one' },
+            { name: 'evt2', description: 'event tool two' },
+          ],
+          graphTools: [askLikeTool],
+        },
+      ],
+    });
+    // 2 schema-only event tools + 1 in-process direct tool — all bound to the
+    // model and token-accounted, so all must be counted (Codex #289 P3).
+    expect(graph.getToolCount()).toBe(3);
+  });
+
+  it('keeps ordinary tools executable when graphTools are added without a host toolMap (traditional mode)', () => {
+    type HostTool = NonNullable<t.AgentInputs['graphTools']>[number];
+    const echoTool = { name: 'echo_tool' } as unknown as HostTool;
+    const askLikeTool = { name: 'ask_user_question' } as unknown as HostTool;
+    const graph = new StandardGraph({
+      runId: 'toolmap-merge-smoke',
+      agents: [
+        {
+          ...makeAgent('agent'),
+          tools: [echoTool],
+          graphTools: [askLikeTool],
+        },
+      ],
+    });
+    const agentContext = graph.agentContexts.get('agent');
+    const node = graph.initializeTools({
+      currentTools: agentContext?.tools,
+      currentToolMap: undefined,
+      agentContext,
+    });
+    /**
+     * ToolNode treats a provided toolMap as authoritative — if the merged map
+     * built for graphTools drops the base tools, they stay bound to the model
+     * but every call fails as an unknown tool (Codex #289 round 2).
+     */
+    const toolMap = (node as unknown as { toolMap: Map<string, unknown> })
+      .toolMap;
+    expect(toolMap.has('echo_tool')).toBe(true);
+    expect(toolMap.has('ask_user_question')).toBe(true);
+  });
+
   it('clears run-scoped eager tool state on reset', () => {
     const graph = new StandardGraph({
       runId: 'standard-eager-reset',

package/src/langfuseToolOutputTracing.ts

@@ -16,6 +16,10 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  shapeLangfuseSpan,
+  shouldDropLangfuseSpan,
+} from '@/langfuseTraceShaping';
 import { resolveToolOutputTracingConfigForSpan } from '@/langfuseRuntimeScope';
 
 export { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig };
@@ -407,6 +411,9 @@ class ToolOutputRedactingLangfuseSpanProcessor implements SpanProcessor {
   }
 
   onStart(span: Span, parentContext: Context): void {
+    if (shouldDropLangfuseSpan(span.name)) {
+      return;
+    }
     const config =
       resolveToolOutputTracingConfigForSpan(parentContext) ??
       this.fallbackConfig;
@@ -417,7 +424,11 @@ class ToolOutputRedactingLangfuseSpanProcessor implements SpanProcessor {
   }
 
   onEnd(span: ReadableSpan): void {
+    if (shouldDropLangfuseSpan(span.name)) {
+      return;
+    }
     classifyLangfuseToolNodeSpan(span);
+    shapeLangfuseSpan(span);
     const config = this.spanConfigs.get(span) ?? this.fallbackConfig;
     if (config != null) {
       redactLangfuseSpanToolOutputs(span, config);

package/src/langfuseTraceShaping.ts

@@ -0,0 +1,280 @@
+import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+
+const LANGGRAPH_START_NODE = '__start__';
+const ANONYMOUS_LAMBDA_NAME = 'RunnableLambda';
+const LANGGRAPH_AGENT_NODE_PREFIX = 'agent=';
+const LANGGRAPH_TOOL_NODE_PREFIX = 'tools=';
+const TOOL_BATCH_RUN_NAME = 'tool_batch';
+const AGENT_NODE_SPAN_NAME = 'agent';
+
+type MutableSpan = ReadableSpan & {
+  name: string;
+  attributes: Record<string, unknown>;
+};
+
+type SerializedToolCall = {
+  name: string;
+  args: unknown;
+  id?: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function parseAttributeValue(value: unknown): unknown {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('{') && !trimmed.startsWith('[')) {
+    return value;
+  }
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
+  }
+}
+
+function getMessageArray(
+  value: unknown
+): Record<string, unknown>[] | undefined {
+  if (Array.isArray(value)) {
+    const records = value.filter(isRecord);
+    return records.length > 0 ? records : undefined;
+  }
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  return (
+    getMessageArray(value.messages) ??
+    getMessageArray(value.input) ??
+    getMessageArray(value.output)
+  );
+}
+
+function getMessageRole(message: Record<string, unknown>): string | undefined {
+  const id = message.id;
+  if (Array.isArray(id)) {
+    const className = id[id.length - 1];
+    if (typeof className === 'string') {
+      if (className.includes('Human')) {
+        return 'user';
+      }
+      if (className.includes('AI')) {
+        return 'assistant';
+      }
+      if (className.includes('System')) {
+        return 'system';
+      }
+      if (className.includes('Tool')) {
+        return 'tool';
+      }
+    }
+  }
+  const rawRole =
+    message.type ?? message._type ?? message.role ?? message.sender;
+  if (typeof rawRole !== 'string') {
+    const kwargs = message.kwargs;
+    return isRecord(kwargs) ? getMessageRole(kwargs) : undefined;
+  }
+  const normalized = rawRole.toLowerCase();
+  if (normalized === 'human') {
+    return 'user';
+  }
+  if (normalized === 'ai') {
+    return 'assistant';
+  }
+  return normalized;
+}
+
+function getMessageText(message: Record<string, unknown>): string | undefined {
+  const content =
+    message.content ??
+    (isRecord(message.kwargs) ? message.kwargs.content : undefined) ??
+    (isRecord(message.data) ? message.data.content : undefined);
+  if (typeof content === 'string') {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return undefined;
+  }
+  const text = content
+    .filter(isRecord)
+    .map((part) => (typeof part.text === 'string' ? part.text : ''))
+    .join('');
+  return text === '' ? undefined : text;
+}
+
+function findLastMessageText(value: unknown, role: string): string | undefined {
+  const messages = getMessageArray(value);
+  if (messages == null) {
+    return undefined;
+  }
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (getMessageRole(messages[i]) !== role) {
+      continue;
+    }
+    const text = getMessageText(messages[i]);
+    if (text != null && text.trim() !== '') {
+      return text;
+    }
+  }
+  return undefined;
+}
+
+function normalizeToolCall(value: unknown): SerializedToolCall | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  const fn = value.function;
+  if (isRecord(fn) && typeof fn.name === 'string') {
+    return {
+      name: fn.name,
+      args: parseAttributeValue(fn.arguments),
+      ...(typeof value.id === 'string' ? { id: value.id } : {}),
+    };
+  }
+  if (typeof value.name !== 'string') {
+    return undefined;
+  }
+  return {
+    name: value.name,
+    args: value.args ?? {},
+    ...(typeof value.id === 'string' ? { id: value.id } : {}),
+  };
+}
+
+function getMessageToolCalls(
+  message: Record<string, unknown>
+): SerializedToolCall[] {
+  const rawCalls =
+    message.tool_calls ??
+    (isRecord(message.kwargs) ? message.kwargs.tool_calls : undefined) ??
+    (isRecord(message.additional_kwargs)
+      ? message.additional_kwargs.tool_calls
+      : undefined) ??
+    (isRecord(message.data) ? message.data.tool_calls : undefined);
+  if (!Array.isArray(rawCalls)) {
+    return [];
+  }
+  const calls: SerializedToolCall[] = [];
+  for (const rawCall of rawCalls) {
+    const call = normalizeToolCall(rawCall);
+    if (call != null) {
+      calls.push(call);
+    }
+  }
+  return calls;
+}
+
+/** Latest assistant turn's tool calls — the calls this tool node is executing. */
+function findPendingToolCalls(value: unknown): SerializedToolCall[] {
+  const messages = getMessageArray(value);
+  if (messages == null) {
+    return [];
+  }
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (getMessageRole(messages[i]) !== 'assistant') {
+      continue;
+    }
+    const calls = getMessageToolCalls(messages[i]);
+    if (calls.length > 0) {
+      return calls;
+    }
+  }
+  return [];
+}
+
+function getRootSpanParentId(span: ReadableSpan): string | undefined {
+  const legacyParent = (span as { parentSpanId?: string }).parentSpanId;
+  if (typeof legacyParent === 'string' && legacyParent !== '') {
+    return legacyParent;
+  }
+  const parentContext = (span as { parentSpanContext?: { spanId?: string } })
+    .parentSpanContext;
+  const spanId = parentContext?.spanId;
+  return typeof spanId === 'string' && spanId !== '' ? spanId : undefined;
+}
+
+function isRootSpan(span: ReadableSpan): boolean {
+  return getRootSpanParentId(span) == null;
+}
+
+/**
+ * LangGraph plumbing observations that add noise without information:
+ * the duplicated `__start__` channel-seed nodes and anonymous
+ * `RunnableLambda` pass-throughs (Langfuse team feedback items 4 & 5).
+ */
+export function shouldDropLangfuseSpan(spanName: string): boolean {
+  return (
+    spanName === LANGGRAPH_START_NODE || spanName === ANONYMOUS_LAMBDA_NAME
+  );
+}
+
+function shapeToolNodeSpan(span: MutableSpan): void {
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const calls = findPendingToolCalls(
+    parseAttributeValue(span.attributes[inputKey])
+  );
+  if (calls.length === 0) {
+    return;
+  }
+  span.name = [...new Set(calls.map((call) => call.name))].join(', ');
+  span.attributes[inputKey] = JSON.stringify(
+    calls.map(({ name, args }) => ({ name, args }))
+  );
+}
+
+function shapeRootSpan(span: MutableSpan): void {
+  const inputKey = LangfuseOtelSpanAttributes.OBSERVATION_INPUT;
+  const outputKey = LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT;
+  const question = findLastMessageText(
+    parseAttributeValue(span.attributes[inputKey]),
+    'user'
+  );
+  const answer = findLastMessageText(
+    parseAttributeValue(span.attributes[outputKey]),
+    'assistant'
+  );
+  if (question != null) {
+    span.attributes[inputKey] = question;
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_INPUT] = question;
+  }
+  if (answer != null) {
+    span.attributes[outputKey] = answer;
+    span.attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT] = answer;
+  }
+}
+
+/**
+ * Reshapes spans per Langfuse-team feedback before export:
+ * - `agent=<id>` / `tools=<id>` node names carry the ephemeral agent id
+ *   (`provider__model`) — strip it so switching models doesn't break
+ *   name-based logic (item 1).
+ * - Tool node spans are renamed to the actual tool name(s) and their
+ *   input scoped to the pending tool-call args instead of the whole
+ *   chat history (items 3 & 4).
+ * - The root span (and trace) input/output become the user question and
+ *   assistant response so the session view reads as a conversation
+ *   (item 2).
+ */
+export function shapeLangfuseSpan(span: ReadableSpan): void {
+  const mutable = span as MutableSpan;
+  if (mutable.name.startsWith(LANGGRAPH_AGENT_NODE_PREFIX)) {
+    mutable.name = AGENT_NODE_SPAN_NAME;
+    return;
+  }
+  if (
+    mutable.name.startsWith(LANGGRAPH_TOOL_NODE_PREFIX) ||
+    mutable.name === TOOL_BATCH_RUN_NAME
+  ) {
+    shapeToolNodeSpan(mutable);
+    return;
+  }
+  if (isRootSpan(span)) {
+    shapeRootSpan(mutable);
+  }
+}

package/src/llm/anthropic/inherited-stream-events.spec.ts

@@ -32,7 +32,6 @@ import { HumanMessage } from '@langchain/core/messages';
 import { ChatModelStream } from '@langchain/core/language_models/stream';
 import type { BaseChatModelCallOptions } from '@langchain/core/language_models/chat_models';
 import type { ChatModelStreamEvent } from '@langchain/core/language_models/event';
-import type { Stream } from '@anthropic-ai/sdk/streaming';
 import type {
   AnthropicMessageStreamEvent,
   AnthropicRequestOptions,
@@ -57,10 +56,14 @@ class MockStreamChatAnthropic extends ChatAnthropic {
     this.mockEvents = mockEvents;
   }
 
+  // Inherit the base method's own Stream identity instead of importing
+  // @anthropic-ai/sdk/streaming here: the SDK ships dual .d.ts/.d.mts types,
+  // and an independent import can resolve to the other format's identity
+  // depending on compile order (flaky TS2416 in sharded CI).
   protected override async createStreamWithRetry(
     request: AnthropicStreamingMessageCreateParams,
     _options?: AnthropicRequestOptions
-  ): Promise<Stream<AnthropicMessageStreamEvent>> {
+  ): ReturnType<ChatAnthropic['createStreamWithRetry']> {
     this.capturedRequest = request;
     const events = this.mockEvents;
     return {
@@ -70,7 +73,7 @@ class MockStreamChatAnthropic extends ChatAnthropic {
           yield event as AnthropicMessageStreamEvent;
         }
       },
-    } as unknown as Stream<AnthropicMessageStreamEvent>;
+    } as unknown as Awaited<ReturnType<ChatAnthropic['createStreamWithRetry']>>;
   }
 }
 

package/src/run.ts

@@ -1403,7 +1403,7 @@ export class Run<_T extends t.BaseGraphState> {
         inputText,
         skipLanguage,
       }),
-    }).withConfig({ runName: 'ConvoTransform' });
+    }).withConfig({ runName: 'PrepareTitleInput' });
 
     const titleChain =
       titleMethod === TitleMethod.COMPLETION
@@ -1412,10 +1412,10 @@ export class Run<_T extends t.BaseGraphState> {
 
     /** Pipes `convoTemplate` -> `transformer` -> `titleChain` */
     const fullChain = convoTemplate
-      .withConfig({ runName: 'ConvoTemplate' })
+      .withConfig({ runName: 'FormatConversation' })
       .pipe(convoToTitleInput)
       .pipe(titleChain)
-      .withConfig({ runName: 'TitleChain' });
+      .withConfig({ runName: 'GenerateConversationTitle' });
 
     const invokeConfig = Object.assign({}, chainOptions, {
       run_id: this.id,

package/src/specs/langfuse-routing.integration.test.ts

@@ -469,7 +469,7 @@ describe('Langfuse per-run routing integration', () => {
       expectNamedSpansUseTraceId({
         starts,
         traceId: titleTraceId,
-        names: [`LibreChat Title: Parent ${tenantId}`, 'CompletionTitleChain'],
+        names: [`LibreChat Title: Parent ${tenantId}`, 'GenerateTitle'],
       });
       expectNoCrossTenantTrace({
         tenantId,