@librechat/agents 3.1.95 → 3.1.97

package/src/tools/ToolNode.ts

@@ -41,6 +41,7 @@ import {
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { executeHooks } from '@/hooks';
 import { toLangChainContent } from '@/messages/langchain';
+import { withLangfuseToolOutputTracingConfig } from '@/langfuseToolOutputTracing';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
 import {
   buildReferenceKey,
@@ -394,6 +395,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private loadRuntimeTools?: t.ToolRefGenerator;
   handleToolErrors = true;
   trace = false;
+  private runLangfuse?: t.LangfuseConfig;
+  private agentLangfuse?: t.LangfuseConfig;
   toolCallStepIds?: Map<string, string>;
   errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
   private toolUsageCount: Map<string, number>;
@@ -473,6 +476,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     toolMap,
     name,
     tags,
+    trace,
+    runLangfuse,
+    agentLangfuse,
     errorHandler,
     toolCallStepIds,
     handleToolErrors,
@@ -495,6 +501,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     fileCheckpointer,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
+    this.trace = trace ?? this.trace;
+    this.runLangfuse = runLangfuse;
+    this.agentLangfuse = agentLangfuse;
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
     this.toolCallStepIds = toolCallStepIds;
     this.handleToolErrors = handleToolErrors ?? this.handleToolErrors;
@@ -545,6 +554,19 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     }
   }
 
+  override async invoke(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    input: any,
+    options?: Partial<RunnableConfig>
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any> {
+    return withLangfuseToolOutputTracingConfig(
+      this.runLangfuse,
+      () => super.invoke(input, options),
+      this.agentLangfuse
+    );
+  }
+
   /**
    * Returns the run-scoped tool output registry, or `undefined` when
    * the feature is disabled.
@@ -2140,13 +2162,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
         /**
          * `interrupt()` reads the current `RunnableConfig` from
-         * AsyncLocalStorage, but our `RunnableCallable` sets
-         * `trace = false` for ToolNode (intentional — avoids LangSmith
-         * tracing per tool call). Without the trace path, the upstream
-         * `runWithConfig` frame is never established, so we re-anchor
-         * here using the node's own `config` — Pregel hands us a
-         * config that already carries every checkpoint/scratchpad key
-         * `interrupt()` needs to suspend and resume.
+         * AsyncLocalStorage. ToolNode usually runs with tracing disabled
+         * (unless Langfuse explicitly enables it), so the upstream
+         * `runWithConfig` frame may not exist. Re-anchor here using the
+         * node's own `config` — Pregel hands us a config that already
+         * carries every checkpoint/scratchpad key `interrupt()` needs to
+         * suspend and resume.
          */
         const resumeValue = AsyncLocalStorageProviderSingleton.runWithConfig(
           config,

package/src/tools/__tests__/CodeApiAuthHeaders.test.ts

@@ -34,6 +34,8 @@ type FetchMock = jest.MockedFunction<
 
 type CodeApiRequestBody = {
   timeout?: number;
+  continuation_token?: string;
+  tool_results?: t.PTCToolResult[];
 };
 
 type TimeoutSchemaForTest = {
@@ -387,6 +389,58 @@ describe('CodeAPI auth header injection', () => {
     );
   });
 
+  it('normalizes JSON-looking bash programmatic tool results before continuation', async () => {
+    fetchMock
+      .mockResolvedValueOnce(
+        jsonResponse({
+          status: 'tool_call_required',
+          continuation_token: 'continue_123',
+          tool_calls: [{ id: 'call_001', name: 'lookup_user', input: {} }],
+        })
+      )
+      .mockResolvedValueOnce(completedResponse('done'));
+    const tool = createBashProgrammaticToolCallingTool();
+    const customToolMap = new Map([
+      [
+        'lookup_user',
+        {
+          name: 'lookup_user',
+          invoke: jest.fn(async () =>
+            JSON.stringify({
+              result: {
+                data: [{ id: 'user_123', name: 'Ada' }],
+              },
+            })
+          ),
+        },
+      ],
+    ]) as unknown as t.ToolMap;
+
+    await tool.invoke(
+      { code: 'lookup_user "{}"' },
+      {
+        toolCall: {
+          name: 'bash_programmatic_code_execution',
+          args: {},
+          toolMap: customToolMap,
+          toolDefs,
+        },
+      }
+    );
+
+    expect(requestBodyAt(1).tool_results).toEqual([
+      {
+        call_id: 'call_001',
+        result: {
+          result: {
+            data: [{ id: 'user_123', name: 'Ada' }],
+          },
+        },
+        is_error: false,
+      },
+    ]);
+  });
+
   it('reminds that failed bash programmatic executions do not register new files', async () => {
     fetchMock.mockResolvedValueOnce(
       jsonResponse({

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -16,7 +16,10 @@ import {
   normalizeToPythonIdentifier,
   unwrapToolResponse,
 } from '../ProgrammaticToolCalling';
-import { createBashProgrammaticToolCallingSchema } from '../BashProgrammaticToolCalling';
+import {
+  createBashProgrammaticToolCallingSchema,
+  normalizeBashToolResultsForReplay,
+} from '../BashProgrammaticToolCalling';
 import {
   createProgrammaticToolRegistry,
   createGetTeamMembersTool,
@@ -40,9 +43,11 @@ describe('ProgrammaticToolCalling', () => {
       const schema = createBashProgrammaticToolCallingSchema();
       const description = schema.properties.code.description;
 
-      expect(description).toContain('jq: use fromjson? // .');
-      expect(description).toContain('again on JSON-string fields');
-      expect(description).toContain('arrays may contain strings');
+      expect(description).toContain(
+        'Tool stdout is normalized to one compact JSON value'
+      );
+      expect(description).toContain('use fromjson? // .');
+      expect(description).toContain('only for JSON-string fields');
       expect(description).toContain('raw=$(tool');
       expect(description).toContain('direct tool > file may be empty');
       expect(description).toContain('/mnt/data/sf.json');
@@ -53,6 +58,69 @@ describe('ProgrammaticToolCalling', () => {
     });
   });
 
+  describe('normalizeBashToolResultsForReplay', () => {
+    it('decodes JSON-looking string results before bash replay', () => {
+      const results = normalizeBashToolResultsForReplay([
+        {
+          call_id: 'call_001',
+          result: JSON.stringify({
+            result: {
+              data: [{ station_id: 'USW00094725', winter_days: 91 }],
+            },
+          }),
+          is_error: false,
+        },
+      ]);
+
+      expect(results[0].result).toEqual({
+        result: {
+          data: [{ station_id: 'USW00094725', winter_days: 91 }],
+        },
+      });
+    });
+
+    it('decodes JSON-looking array string results before bash replay', () => {
+      const results = normalizeBashToolResultsForReplay([
+        {
+          call_id: 'call_001',
+          result: '[{"name":"tempAvg"},{"name":"snowDepth"}]',
+          is_error: false,
+        },
+      ]);
+
+      expect(results[0].result).toEqual([
+        { name: 'tempAvg' },
+        { name: 'snowDepth' },
+      ]);
+    });
+
+    it('preserves plain strings, invalid JSON strings, and error results', () => {
+      const errorJson = '{"message":"tool failed"}';
+      const results = normalizeBashToolResultsForReplay([
+        {
+          call_id: 'call_001',
+          result: 'plain text',
+          is_error: false,
+        },
+        {
+          call_id: 'call_002',
+          result: '{not json}',
+          is_error: false,
+        },
+        {
+          call_id: 'call_003',
+          result: errorJson,
+          is_error: true,
+          error_message: 'tool failed',
+        },
+      ]);
+
+      expect(results[0].result).toBe('plain text');
+      expect(results[1].result).toBe('{not json}');
+      expect(results[2].result).toBe(errorJson);
+    });
+  });
+
   describe('executeTools', () => {
     let toolMap: t.ToolMap;
 

package/src/tools/__tests__/SubagentExecutor.test.ts

@@ -424,6 +424,38 @@ describe('SubagentExecutor', () => {
     expect(clearHeavyState).toHaveBeenCalled();
   });
 
+  it('passes parent Langfuse config to the child graph', async () => {
+    const langfuse = {
+      enabled: true,
+      publicKey: 'pk-run',
+      secretKey: 'sk-run',
+      baseUrl: 'https://langfuse.test',
+      toolOutputTracing: { enabled: false },
+    };
+    let observedLangfuse: typeof langfuse | undefined;
+    const executor = createExecutor({
+      langfuse,
+      createChildGraph: (input): StandardGraph => {
+        observedLangfuse = input.langfuse as typeof langfuse;
+        return {
+          createWorkflow: (): { invoke: jest.Mock } => ({
+            invoke: jest.fn().mockResolvedValue({
+              messages: [new AIMessage('child done')],
+            }),
+          }),
+          clearHeavyState: jest.fn(),
+        } as unknown as StandardGraph;
+      },
+    });
+
+    await executor.execute({
+      description: 'Research this topic',
+      subagentType: 'researcher',
+    });
+
+    expect(observedLangfuse).toBe(langfuse);
+  });
+
   it('returns error message when child graph throws', async () => {
     const executor = createExecutor({
       createChildGraph: makeThrowingGraphFactory(

package/src/tools/__tests__/ToolNode.langfuse.test.ts

@@ -0,0 +1,41 @@
+const mockWithLangfuseToolOutputTracingConfig = jest.fn(
+  (_runLangfuse: unknown, action: () => unknown, _agentLangfuse: unknown) =>
+    action()
+);
+
+jest.mock('@/langfuseToolOutputTracing', () => ({
+  ...jest.requireActual('@/langfuseToolOutputTracing'),
+  withLangfuseToolOutputTracingConfig: mockWithLangfuseToolOutputTracingConfig,
+}));
+
+import { ToolNode } from '../ToolNode';
+
+describe('ToolNode Langfuse redaction context', () => {
+  beforeEach(() => {
+    mockWithLangfuseToolOutputTracingConfig.mockClear();
+  });
+
+  it('scopes ToolNode invocation with run and agent Langfuse config', async () => {
+    const runLangfuse = {
+      toolOutputTracing: { enabled: true },
+    };
+    const agentLangfuse = {
+      toolOutputTracing: { enabled: false },
+    };
+    const node = new ToolNode({
+      tools: [],
+      runLangfuse,
+      agentLangfuse,
+    });
+
+    await expect(node.invoke([])).rejects.toThrow(
+      'ToolNode only accepts AIMessages'
+    );
+
+    expect(mockWithLangfuseToolOutputTracingConfig).toHaveBeenCalledWith(
+      runLangfuse,
+      expect.any(Function),
+      agentLangfuse
+    );
+  });
+});

package/src/tools/subagent/SubagentExecutor.ts

@@ -213,6 +213,7 @@ export type SubagentExecutorOptions = {
   hookRegistry?: HookRegistry;
   parentRunId: string;
   parentAgentId?: string;
+  langfuse?: StandardGraphInput['langfuse'];
   tokenCounter?: TokenCounter;
   /** Remaining nesting budget. 0 or negative blocks execution. */
   maxDepth?: number;
@@ -243,6 +244,7 @@ export class SubagentExecutor {
   private readonly hookRegistry?: HookRegistry;
   private readonly parentRunId: string;
   private readonly parentAgentId?: string;
+  private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
   private readonly maxDepth: number;
   private readonly createChildGraph: ChildGraphFactory;
@@ -256,6 +258,7 @@ export class SubagentExecutor {
     this.hookRegistry = options.hookRegistry;
     this.parentRunId = options.parentRunId;
     this.parentAgentId = options.parentAgentId;
+    this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
     this.maxDepth = options.maxDepth ?? 1;
     this.createChildGraph = options.createChildGraph;
@@ -352,18 +355,20 @@ export class SubagentExecutor {
       runId: childRunId,
       signal: this.parentSignal,
       agents: [childInputs],
+      langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
     });
 
-    const forwarding = forwardingEnabled
-      ? this.createForwarderCallback({
+    let forwarding: ForwarderCallback | undefined;
+    if (forwardingEnabled) {
+      forwarding = this.createForwarderCallback({
         parentRegistry: parentRegistry!,
         subagentType,
         subagentAgentId: childAgentId,
         childRunId,
         parentToolCallId,
-      })
-      : undefined;
+      });
+    }
     const forwarder = forwarding?.handler;
 
     if (forwarder) {
@@ -444,7 +449,7 @@ export class SubagentExecutor {
       );
     } catch (error) {
       const errorMessage = truncateErrorMessage(error);
-      if (forwarder) {
+      if (forwarding) {
         await forwarding.drain();
         await this.emitSubagentUpdate(parentRegistry!, {
           childRunId,
@@ -491,7 +496,7 @@ export class SubagentExecutor {
       });
     }
 
-    if (forwarder) {
+    if (forwarding) {
       await forwarding.drain();
       await this.emitSubagentUpdate(parentRegistry!, {
         childRunId,

package/src/types/graph.ts

@@ -295,6 +295,7 @@ export type StandardGraphInput = {
   runId?: string;
   signal?: AbortSignal;
   agents: AgentInputs[];
+  langfuse?: LangfuseConfig;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
   calibrationRatio?: number;
@@ -408,11 +409,42 @@ export interface SubagentUpdateEvent {
   timestamp: string;
 }
 
+export type LangfuseToolOutputTracingConfig = {
+  /**
+   * Whether tool outputs should be exported to Langfuse. Defaults to
+   * `true`. Set to `false` to keep tool spans and redact their output.
+   */
+  enabled?: boolean;
+  /**
+   * Optional allowlist of tool names whose outputs should be redacted even
+   * when `enabled` is true.
+   */
+  redactedToolNames?: string[];
+  /**
+   * Match strategy for `redactedToolNames`. Defaults to `exact`; use
+   * `partial` to redact tools whose names contain a configured value.
+   */
+  redactedToolNameMatchMode?: 'exact' | 'partial';
+  /** Replacement text used for redacted tool outputs. */
+  redactionText?: string;
+};
+
+export type LangfuseToolNodeTracingConfig = {
+  /**
+   * Overrides ToolNode callback tracing. ToolNode spans are exported by the
+   * env-backed Langfuse callback, so this only enables tracing when that
+   * callback is configured.
+   */
+  enabled?: boolean;
+};
+
 export interface LangfuseConfig {
   enabled?: boolean;
   publicKey?: string;
   secretKey?: string;
   baseUrl?: string;
+  toolNodeTracing?: LangfuseToolNodeTracingConfig;
+  toolOutputTracing?: LangfuseToolOutputTracingConfig;
 }
 
 export interface AgentInputs {

package/src/types/run.ts

@@ -118,6 +118,12 @@ export type StandardGraphConfig = Omit<
 export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
+  /**
+   * Run-scoped Langfuse configuration. Per-agent `AgentInputs.langfuse`
+   * takes precedence for agent-specific spans; this object supplies defaults
+   * for run-wide tracing controls such as tool-output redaction.
+   */
+  langfuse?: g.LangfuseConfig;
   customHandlers?: Record<string, g.EventHandler>;
   /**
    * Pre-constructed hook registry for this run. Hooks fire at lifecycle

package/src/types/tools.ts

@@ -6,6 +6,7 @@ import type { HookRegistry } from '@/hooks';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { MessageContentComplex, ToolErrorData } from './stream';
 import type { HumanInTheLoopConfig } from './hitl';
+import type { LangfuseConfig } from './graph';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -69,6 +70,12 @@ export type EagerEventToolCallChunkState = {
 export type ToolNodeOptions = {
   name?: string;
   tags?: string[];
+  /** Enables LangChain/LangGraph tracing for this ToolNode. Defaults to false. */
+  trace?: boolean;
+  /** Run-level Langfuse config used to scope ToolNode trace redaction. */
+  runLangfuse?: LangfuseConfig;
+  /** Agent-level Langfuse config used to scope ToolNode trace redaction. */
+  agentLangfuse?: LangfuseConfig;
   handleToolErrors?: boolean;
   loadRuntimeTools?: ToolRefGenerator;
   toolCallStepIds?: Map<string, string>;