@librechat/agents 3.2.21 → 3.2.31

package/src/graphs/__tests__/MultiAgentGraph.test.ts

@@ -1,7 +1,7 @@
 // src/graphs/__tests__/MultiAgentGraph.test.ts
+import type * as t from '@/types';
 import { MultiAgentGraph } from '../MultiAgentGraph';
 import { Providers } from '@/common';
-import type * as t from '@/types';
 
 describe('MultiAgentGraph.validateEdgeAgents', () => {
   const makeAgent = (agentId: string): t.AgentInputs => ({

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

@@ -1,7 +1,7 @@
 import { HumanMessage, getBufferString } from '@langchain/core/messages';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
-import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';

package/src/hooks/__tests__/HookRegistry.test.ts

@@ -1,11 +1,11 @@
 // src/hooks/__tests__/HookRegistry.test.ts
-import { HookRegistry } from '../HookRegistry';
 import type {
   HookMatcher,
   HookCallback,
   PreToolUseHookOutput,
   PostToolUseHookOutput,
 } from '../types';
+import { HookRegistry } from '../HookRegistry';
 
 const noop: HookCallback<
   'PreToolUse'

package/src/hooks/__tests__/compactHooks.test.ts

@@ -1,13 +1,6 @@
 // src/hooks/__tests__/compactHooks.test.ts
-import { HumanMessage, AIMessage } from '@langchain/core/messages';
 import { FakeListChatModel } from '@langchain/core/utils/testing';
-import { HookRegistry } from '../HookRegistry';
-import { Run } from '@/run';
-import * as providers from '@/llm/providers';
-import { ToolEndHandler, ModelEndHandler } from '@/events';
-import { createTokenCounter } from '@/utils/tokens';
-import { Providers, GraphEvents } from '@/common';
-import type * as t from '@/types';
+import { HumanMessage, AIMessage } from '@langchain/core/messages';
 import type {
   HookCallback,
   PreCompactHookInput,
@@ -15,6 +8,13 @@ import type {
   PostCompactHookInput,
   PostCompactHookOutput,
 } from '../types';
+import type * as t from '@/types';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { createTokenCounter } from '@/utils/tokens';
+import { Providers, GraphEvents } from '@/common';
+import { HookRegistry } from '../HookRegistry';
+import * as providers from '@/llm/providers';
+import { Run } from '@/run';
 
 const SUMMARY_RESPONSE = '## Summary\nUser asked a question and got an answer.';
 

package/src/hooks/__tests__/createWorkspacePolicyHook.test.ts

@@ -2,12 +2,12 @@ import { tmpdir } from 'os';
 import { join, resolve } from 'path';
 import { mkdtemp, rm } from 'fs/promises';
 import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
-import { createWorkspacePolicyHook } from '../createWorkspacePolicyHook';
 import type {
   HookCallback,
   PreToolUseHookInput,
   PreToolUseHookOutput,
 } from '../types';
+import { createWorkspacePolicyHook } from '../createWorkspacePolicyHook';
 
 function call(
   hook: HookCallback<'PreToolUse'>,
@@ -49,13 +49,17 @@ describe('createWorkspacePolicyHook', () => {
 
   it('allows in-workspace relative paths', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,makeInput('read_file', { file_path: 'src/x.ts' }));
+    const out = await call(
+      hook,
+      makeInput('read_file', { file_path: 'src/x.ts' })
+    );
     expect(out.decision).toBe('allow');
   });
 
   it('allows in-workspace absolute paths', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: join(workspace, 'src/x.ts') })
     );
     expect(out.decision).toBe('allow');
@@ -66,7 +70,8 @@ describe('createWorkspacePolicyHook', () => {
       root: workspace,
       additionalRoots: [extra],
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: join(extra, 'lib/y.ts') })
     );
     expect(out.decision).toBe('allow');
@@ -74,7 +79,8 @@ describe('createWorkspacePolicyHook', () => {
 
   it('asks by default when path is outside the workspace (read tool)', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: '/etc/passwd' })
     );
     expect(out.decision).toBe('ask');
@@ -84,7 +90,8 @@ describe('createWorkspacePolicyHook', () => {
 
   it('asks by default when path is outside the workspace (write tool)', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('write_file', {
         file_path: '/etc/foo',
         content: 'malicious',
@@ -98,7 +105,8 @@ describe('createWorkspacePolicyHook', () => {
       root: workspace,
       outsideRead: 'deny',
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: '/etc/passwd' })
     );
     expect(out.decision).toBe('deny');
@@ -110,7 +118,8 @@ describe('createWorkspacePolicyHook', () => {
       root: workspace,
       outsideWrite: 'deny',
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('edit_file', {
         file_path: '/etc/foo',
         old_text: 'a',
@@ -125,7 +134,8 @@ describe('createWorkspacePolicyHook', () => {
       root: workspace,
       outsideRead: 'allow',
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: '/etc/passwd' })
     );
     expect(out.decision).toBe('allow');
@@ -133,7 +143,8 @@ describe('createWorkspacePolicyHook', () => {
 
   it('passes through when the tool has no extractor (e.g. bash)', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('bash', { command: 'cat /etc/passwd' })
     );
     expect(out.decision).toBe('allow');
@@ -141,7 +152,7 @@ describe('createWorkspacePolicyHook', () => {
 
   it('passes through when the path arg is missing/empty', async () => {
     const hook = createWorkspacePolicyHook({ root: workspace });
-    const out = await call(hook,makeInput('grep_search', { pattern: 'x' }));
+    const out = await call(hook, makeInput('grep_search', { pattern: 'x' }));
     expect(out.decision).toBe('allow');
   });
 
@@ -149,16 +160,17 @@ describe('createWorkspacePolicyHook', () => {
     const hook = createWorkspacePolicyHook({
       root: workspace,
       pathExtractors: {
-        my_custom_tool: (i) =>
-          typeof i.target === 'string' ? [i.target] : [],
+        my_custom_tool: (i) => (typeof i.target === 'string' ? [i.target] : []),
       },
     });
-    const inside = await call(hook,
+    const inside = await call(
+      hook,
       makeInput('my_custom_tool', { target: 'in/workspace.ts' })
     );
     expect(inside.decision).toBe('allow');
 
-    const outside = await call(hook,
+    const outside = await call(
+      hook,
       makeInput('my_custom_tool', { target: '/elsewhere/x.ts' })
     );
     // Unknown tools default to write-policy (stricter): 'ask'.
@@ -170,7 +182,8 @@ describe('createWorkspacePolicyHook', () => {
       root: workspace,
       reason: '{tool} blocked from {paths}',
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: '/somewhere/else.ts' })
     );
     expect(out.reason).toBe('read_file blocked from /somewhere/else.ts');
@@ -184,7 +197,8 @@ describe('createWorkspacePolicyHook', () => {
           Array.isArray(i.paths) ? (i.paths as string[]) : [],
       },
     });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('multi_file_tool', {
         paths: [join(workspace, 'a.ts'), '/etc/passwd'],
       })
@@ -196,7 +210,8 @@ describe('createWorkspacePolicyHook', () => {
 
   it('respects resolved root paths (relative root config)', async () => {
     const hook = createWorkspacePolicyHook({ root: '.' });
-    const out = await call(hook,
+    const out = await call(
+      hook,
       makeInput('read_file', { file_path: resolve('.', 'src/x.ts') })
     );
     expect(out.decision).toBe('allow');
@@ -206,10 +221,7 @@ describe('createWorkspacePolicyHook', () => {
     it('rejects a symlink inside the workspace that points outside', async () => {
       const fs = await import('fs/promises');
       await fs.writeFile(join(extra, 'secret.txt'), 'top-secret\n');
-      await fs.symlink(
-        join(extra, 'secret.txt'),
-        join(workspace, 'escape')
-      );
+      await fs.symlink(join(extra, 'secret.txt'), join(workspace, 'escape'));
       const hook = createWorkspacePolicyHook({
         root: workspace,
         outsideRead: 'deny',

package/src/hooks/__tests__/executeHooks.test.ts

@@ -1,7 +1,4 @@
 // src/hooks/__tests__/executeHooks.test.ts
-import { HookRegistry } from '../HookRegistry';
-import { executeHooks } from '../executeHooks';
-import { clearMatcherCache } from '../matchers';
 import type {
   HookCallback,
   HookMatcher,
@@ -14,6 +11,9 @@ import type {
   PostToolUseHookInput,
   PostToolUseHookOutput,
 } from '../types';
+import { clearMatcherCache } from '../matchers';
+import { HookRegistry } from '../HookRegistry';
+import { executeHooks } from '../executeHooks';
 
 function preToolUseInput(
   toolName: string,

package/src/hooks/__tests__/integration.test.ts

@@ -1,8 +1,5 @@
 // src/hooks/__tests__/integration.test.ts
 import { HumanMessage } from '@langchain/core/messages';
-import { HookRegistry } from '../HookRegistry';
-import { Run } from '@/run';
-import type * as t from '@/types';
 import type {
   HookCallback,
   RunStartHookInput,
@@ -12,7 +9,10 @@ import type {
   StopHookOutput,
   StopFailureHookOutput,
 } from '../types';
+import type * as t from '@/types';
+import { HookRegistry } from '../HookRegistry';
 import { Providers } from '@/common';
+import { Run } from '@/run';
 
 const llmConfig: t.LLMConfig = {
   provider: Providers.OPENAI,

package/src/hooks/__tests__/toolHooks.test.ts

@@ -1,15 +1,6 @@
 // src/hooks/__tests__/toolHooks.test.ts
-import { ToolCall } from '@langchain/core/messages/tool';
 import { HumanMessage } from '@langchain/core/messages';
-import { HookRegistry } from '../HookRegistry';
-import { Run } from '@/run';
-import {
-  GraphEvents,
-  Providers,
-  ToolEndHandler,
-  ModelEndHandler,
-} from '@/index';
-import type * as t from '@/types';
+import { ToolCall } from '@langchain/core/messages/tool';
 import type {
   HookCallback,
   PreToolUseHookOutput,
@@ -21,6 +12,15 @@ import type {
   PostToolUseHookInput,
   PostToolUseFailureHookInput,
 } from '../types';
+import type * as t from '@/types';
+import {
+  GraphEvents,
+  Providers,
+  ToolEndHandler,
+  ModelEndHandler,
+} from '@/index';
+import { HookRegistry } from '../HookRegistry';
+import { Run } from '@/run';
 
 const llmConfig: t.LLMConfig = {
   provider: Providers.OPENAI,

package/src/hooks/createWorkspacePolicyHook.ts

@@ -48,15 +48,15 @@
  */
 
 import { homedir } from 'os';
-import { isAbsolute, relative, resolve } from 'path';
 import { realpath } from 'fs/promises';
-import { Constants } from '@/common';
+import { isAbsolute, relative, resolve } from 'path';
 import type {
   HookCallback,
   PreToolUseHookInput,
   PreToolUseHookOutput,
   ToolDecision,
 } from './types';
+import { Constants } from '@/common';
 
 /**
  * What to do when a tool call references a path outside the workspace.
@@ -213,9 +213,7 @@ async function realpathOrSelf(absolutePath: string): Promise<string> {
   }
 }
 
-async function realpathOfPathOrAncestor(
-  absolutePath: string
-): Promise<string> {
+async function realpathOfPathOrAncestor(absolutePath: string): Promise<string> {
   let current = absolutePath;
   let suffix = '';
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -296,18 +294,27 @@ export function createWorkspacePolicyHook(
   const readPolicy: OutsideAccessPolicy = config.outsideRead ?? 'ask';
   const writePolicy: OutsideAccessPolicy = config.outsideWrite ?? 'ask';
 
-  const extractors: Record<string, PathExtractor> = {
+  const extractors: Record<string, PathExtractor | undefined> = {
     ...DEFAULT_EXTRACTORS,
     ...(config.pathExtractors ?? {}),
   };
 
+  /** Unknown tools are treated as writes (the stricter policy). */
+  const resolvePolicy = (toolName: string): OutsideAccessPolicy => {
+    if (WRITE_TOOLS.has(toolName)) {
+      return writePolicy;
+    }
+    if (READ_TOOLS.has(toolName)) {
+      return readPolicy;
+    }
+    return writePolicy;
+  };
+
   return async (input: PreToolUseHookInput): Promise<PreToolUseHookOutput> => {
     const extractor = extractors[input.toolName];
     if (extractor == null) return { decision: 'allow' };
 
-    const paths = extractor(
-      (input.toolInput ?? {}) as Record<string, unknown>
-    );
+    const paths = extractor(input.toolInput);
     if (paths.length === 0) return { decision: 'allow' };
 
     // Two-stage check:
@@ -336,11 +343,7 @@ export function createWorkspacePolicyHook(
     }
     if (outside.length === 0) return { decision: 'allow' };
 
-    const policy = WRITE_TOOLS.has(input.toolName)
-      ? writePolicy
-      : READ_TOOLS.has(input.toolName)
-        ? readPolicy
-        : writePolicy; // unknown tools — treat as write (stricter)
+    const policy = resolvePolicy(input.toolName);
     if (policy === 'allow') return { decision: 'allow' };
 
     const decision: ToolDecision = policy === 'deny' ? 'deny' : 'ask';

package/src/hooks/executeHooks.ts

@@ -1,6 +1,5 @@
 // src/hooks/executeHooks.ts
 import type { Logger } from 'winston';
-import type { HookRegistry } from './HookRegistry';
 import type {
   HookInput,
   HookEvent,
@@ -11,6 +10,7 @@ import type {
   HookCallback,
   AggregatedHookResult,
 } from './types';
+import type { HookRegistry } from './HookRegistry';
 import { matchesQuery } from './matchers';
 
 /** Default per-hook timeout when a matcher doesn't set its own. */

package/src/hooks/types.ts

@@ -39,11 +39,16 @@ export type StopDecision = 'continue' | 'block';
  * - `runId` identifies the current agent run and is always present.
  * - `threadId` identifies the conversation thread when the host has one.
  * - `agentId` is only set when the hook fires inside a subagent scope.
+ * - `executingAgentId` identifies the agent that owns the node emitting the hook,
+ *   whenever the graph knows it — including top-level agents in a multi-agent
+ *   graph (where `agentId` is intentionally undefined). Use this to attribute a
+ *   hook to a specific agent regardless of subagent scope.
  */
 export interface BaseHookInput {
   runId: string;
   threadId?: string;
   agentId?: string;
+  executingAgentId?: string;
 }
 
 export interface RunStartHookInput extends BaseHookInput {

package/src/instrumentation.ts

@@ -1,7 +1,18 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomBytes } from 'node:crypto';
 import { setLangfuseTracerProvider } from '@langfuse/tracing';
 import { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 import { context, ROOT_CONTEXT, createContextKey } from '@opentelemetry/api';
 import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import type {
+  IdGenerator,
+  ReadableSpan,
+  Span,
+  SpanProcessor,
+} from '@opentelemetry/sdk-trace-base';
+import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
+import type { Context } from '@opentelemetry/api';
+import type * as t from '@/types';
 import {
   hasLangfuseConfigCredentials,
   hasLangfuseEnvCredentials,
@@ -12,17 +23,6 @@ import {
   getContextLangfuseConfig,
 } from '@/langfuseToolOutputTracing';
 import { isPresent } from '@/utils/misc';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { createHash, randomBytes } from 'node:crypto';
-import type {
-  IdGenerator,
-  ReadableSpan,
-  Span,
-  SpanProcessor,
-} from '@opentelemetry/sdk-trace-base';
-import type { LangfuseSpanProcessorParams } from '@langfuse/otel';
-import type { Context } from '@opentelemetry/api';
-import type * as t from '@/types';
 
 /**
  * Per-run seed for deterministic Langfuse trace ids. When a run opts in

package/src/langfuse.ts

@@ -1,5 +1,9 @@
-import { getLangfuseTracerProvider } from '@langfuse/tracing';
 import { CallbackHandler } from '@langfuse/langchain';
+import {
+  getLangfuseTracerProvider,
+  propagateAttributes,
+} from '@langfuse/tracing';
+import type { PropagateAttributesParams } from '@langfuse/tracing';
 import type * as t from '@/types';
 import { isPresent } from '@/utils/misc';
 
@@ -19,6 +23,10 @@ type AgentLangfuseHandlerParams = LangfuseHandlerParams & {
   langfuse?: t.LangfuseConfig;
 };
 
+type LangfuseAttributeParams = AgentLangfuseHandlerParams & {
+  traceName?: string;
+};
+
 type FlushableTracerProvider = {
   forceFlush?: () => Promise<void> | void;
 };
@@ -158,6 +166,32 @@ export function createLangfuseHandler({
   });
 }
 
+function createPropagateAttributeParams({
+  userId,
+  sessionId,
+  traceMetadata,
+  traceName,
+  tags,
+}: LangfuseAttributeParams): PropagateAttributesParams {
+  return {
+    userId,
+    sessionId,
+    traceName,
+    tags,
+    metadata: traceMetadata,
+  };
+}
+
+export function withLangfuseAttributes<T>(
+  params: LangfuseAttributeParams,
+  action: () => T
+): T {
+  if (!shouldCreateLangfuseHandler(params.langfuse)) {
+    return action();
+  }
+  return propagateAttributes(createPropagateAttributeParams(params), action);
+}
+
 export function hasExplicitLangfuseConfig(
   contexts: Iterable<{ langfuse?: t.LangfuseConfig }>
 ): boolean {

package/src/langfuseToolOutputTracing.ts

@@ -1,7 +1,7 @@
-import { context, createContextKey } from '@opentelemetry/api';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
+import { context, createContextKey } from '@opentelemetry/api';
 import { LangfuseOtelSpanAttributes } from '@langfuse/tracing';
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type {
   ReadableSpan,
   Span,

package/src/llm/anthropic/index.ts

@@ -19,11 +19,11 @@ import type {
   AnthropicContextManagementConfigParam,
   AnthropicRequestOptions,
 } from '@/llm/anthropic/types';
-import { _makeMessageChunkFromAnthropicEvent } from './utils/message_outputs';
 import {
   _convertMessagesToAnthropicPayload,
   stripUnsupportedAssistantPrefill,
 } from './utils/message_inputs';
+import { _makeMessageChunkFromAnthropicEvent } from './utils/message_outputs';
 import { handleToolChoice } from './utils/tools';
 
 const DEFAULT_STREAM_DELAY = 25;

package/src/llm/anthropic/utils/message_inputs.ts

@@ -4,6 +4,7 @@
  * This util file contains functions for converting LangChain messages to Anthropic messages.
  */
 import { createHash } from 'node:crypto';
+import { ToolCall } from '@langchain/core/messages/tool';
 import {
   type BaseMessage,
   type SystemMessage,
@@ -18,7 +19,6 @@ import {
   convertToProviderContentBlock,
   parseBase64DataUrl,
 } from '@langchain/core/messages';
-import { ToolCall } from '@langchain/core/messages/tool';
 import {
   AnthropicImageBlockParam,
   AnthropicMessageCreateParams,

package/src/llm/anthropic/utils/message_outputs.ts

@@ -1,13 +1,11 @@
 /** This util file contains functions for converting Anthropic messages to LangChain messages. */
 import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
-
-import type Anthropic from '@anthropic-ai/sdk';
-import type { UsageMetadata } from '@langchain/core/messages';
 import type { ToolCallChunk } from '@langchain/core/messages/tool';
+import type { UsageMetadata } from '@langchain/core/messages';
 import type { ChatGeneration } from '@langchain/core/outputs';
-import type { MessageContentComplex } from '@/types';
+import type Anthropic from '@anthropic-ai/sdk';
 import type { AnthropicMessageResponse } from '../types';
-
+import type { MessageContentComplex } from '@/types';
 import { toLangChainContent } from '@/messages/langchain';
 import { extractToolCalls } from './output_parsers';
 

package/src/llm/anthropic/utils/output_parsers.ts

@@ -1,16 +1,16 @@
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 /* eslint-disable @typescript-eslint/no-empty-object-type */
-import {
-  BaseLLMOutputParser,
-  OutputParserException,
-} from '@langchain/core/output_parsers';
-import { JsonOutputKeyToolsParserParamsInterop } from '@langchain/core/output_parsers/openai_tools';
 import { ChatGeneration } from '@langchain/core/outputs';
 import { ToolCall } from '@langchain/core/messages/tool';
 import {
   interopSafeParseAsync,
   InteropZodType,
 } from '@langchain/core/utils/types';
+import {
+  BaseLLMOutputParser,
+  OutputParserException,
+} from '@langchain/core/output_parsers';
+import { JsonOutputKeyToolsParserParamsInterop } from '@langchain/core/output_parsers/openai_tools';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 interface AnthropicToolsOutputParserParams<T extends Record<string, any>>

package/src/llm/bedrock/index.ts

@@ -22,23 +22,23 @@
  */
 
 import { ChatBedrockConverse } from '@langchain/aws';
+import { AIMessageChunk } from '@langchain/core/messages';
+import { ChatGenerationChunk, ChatResult } from '@langchain/core/outputs';
 import {
   ConverseStreamCommand,
   type GuardrailConfiguration,
   type GuardrailStreamConfiguration,
 } from '@aws-sdk/client-bedrock-runtime';
-import { AIMessageChunk } from '@langchain/core/messages';
-import { ChatGenerationChunk, ChatResult } from '@langchain/core/outputs';
 import type { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
-import type { ChatBedrockConverseInput } from '@langchain/aws';
 import type { BaseMessage, ResponseMetadata } from '@langchain/core/messages';
-import { insertBedrockToolCachePoint } from './toolCache';
+import type { ChatBedrockConverseInput } from '@langchain/aws';
 import {
   convertToConverseMessages,
   handleConverseStreamContentBlockStart,
   handleConverseStreamContentBlockDelta,
   handleConverseStreamMetadata,
 } from './utils';
+import { insertBedrockToolCachePoint } from './toolCache';
 
 /**
  * Service tier type for Bedrock invocations.