@librechat/agents 3.1.68 → 3.1.71-dev.0

package/src/specs/subagent.test.ts

@@ -0,0 +1,305 @@
+import { HumanMessage } from '@langchain/core/messages';
+import { FakeListChatModel } from '@langchain/core/utils/testing';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Run } from '@/run';
+import {
+  Constants,
+  GraphEvents,
+  Providers,
+  ToolEndHandler,
+  ModelEndHandler,
+  StandardGraph,
+} from '@/index';
+import * as providers from '@/llm/providers';
+
+const CHILD_RESPONSE = 'Research result: Paris is the capital of France.';
+
+const callerConfig: Partial<RunnableConfig> & {
+  version: 'v1' | 'v2';
+  streamMode: string;
+} = {
+  configurable: { thread_id: 'subagent-test-thread' },
+  streamMode: 'values',
+  version: 'v2' as const,
+};
+
+const createParentAgent = (): t.AgentInputs => ({
+  agentId: 'parent',
+  provider: Providers.OPENAI,
+  clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+  instructions:
+    'You are a supervisor. Delegate research tasks using the subagent tool.',
+  maxContextTokens: 8000,
+  subagentConfigs: [
+    {
+      type: 'researcher',
+      name: 'Research Agent',
+      description: 'Researches and summarizes information',
+      agentInputs: {
+        agentId: 'researcher',
+        provider: Providers.OPENAI,
+        clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+        instructions: 'You are a research agent. Answer concisely.',
+        maxContextTokens: 8000,
+      },
+    },
+  ],
+});
+
+describe('Subagent Integration', () => {
+  jest.setTimeout(30000);
+
+  let getChatModelClassSpy: jest.SpyInstance;
+  const originalGetChatModelClass = providers.getChatModelClass;
+
+  beforeEach(() => {
+    getChatModelClassSpy = jest
+      .spyOn(providers, 'getChatModelClass')
+      .mockImplementation(((provider: Providers) => {
+        if (provider === Providers.OPENAI) {
+          return class extends FakeListChatModel {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            constructor(_options: any) {
+              super({ responses: [CHILD_RESPONSE] });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          } as any;
+        }
+        return originalGetChatModelClass(provider);
+      }) as typeof providers.getChatModelClass);
+  });
+
+  afterEach(() => {
+    getChatModelClassSpy.mockRestore();
+  });
+
+  it('should create subagent tool on agent context', async () => {
+    const run = await Run.create<t.IState>({
+      runId: `subagent-test-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    expect(run.Graph).toBeDefined();
+    const parentContext = (run.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    expect(parentContext).toBeDefined();
+    expect(parentContext?.graphTools).toBeDefined();
+
+    const subagentTool = (parentContext?.graphTools as t.GenericTool[]).find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should execute subagent and return filtered result to parent', async () => {
+    const customHandlers: Record<string, t.EventHandler> = {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `subagent-exec-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [createParentAgent()],
+      },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+    });
+
+    const subagentToolCall: ToolCall = {
+      id: 'call_subagent_1',
+      name: Constants.SUBAGENT,
+      args: {
+        description: 'What is the capital of France?',
+        subagent_type: 'researcher',
+      },
+      type: 'tool_call',
+    };
+
+    run.Graph?.overrideTestModel(
+      [
+        'Let me delegate this research task.',
+        `Based on the research: ${CHILD_RESPONSE}`,
+      ],
+      10,
+      [subagentToolCall]
+    );
+
+    const result = await run.processStream(
+      { messages: [new HumanMessage('What is the capital of France?')] },
+      callerConfig
+    );
+
+    expect(result).toBeDefined();
+
+    const runMessages = run.getRunMessages();
+    expect(runMessages).toBeDefined();
+    expect(runMessages!.length).toBeGreaterThan(0);
+
+    const toolMessages = runMessages!.filter(
+      (msg) => msg._getType() === 'tool'
+    );
+    const subagentResult = toolMessages.find(
+      (msg) => 'name' in msg && msg.name === Constants.SUBAGENT
+    );
+    expect(subagentResult).toBeDefined();
+    expect(String(subagentResult!.content)).toContain('Paris');
+  });
+
+  it('should not create subagent tool when no subagentConfigs', async () => {
+    const agentWithoutSubagents: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Plain agent without subagents.',
+      maxContextTokens: 8000,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `no-subagent-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagents],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get('plain');
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should handle self-spawn subagent config', async () => {
+    const agentWithSelfSpawn: t.AgentInputs = {
+      agentId: 'self-parent',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions: 'Agent with self-spawn for context isolation.',
+      maxContextTokens: 8000,
+      subagentConfigs: [
+        {
+          type: 'isolated',
+          name: 'Isolated Worker',
+          description: 'Runs a task with isolated context',
+          self: true,
+        },
+      ],
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `self-spawn-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSelfSpawn],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'self-parent'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeDefined();
+  });
+
+  it('should not create subagent tool when maxSubagentDepth is 0', async () => {
+    const agentWithZeroDepth: t.AgentInputs = {
+      ...createParentAgent(),
+      agentId: 'zero-depth',
+      maxSubagentDepth: 0,
+    };
+
+    const run = await Run.create<t.IState>({
+      runId: `zero-depth-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithZeroDepth],
+      },
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const context = (run.Graph as StandardGraph).agentContexts.get(
+      'zero-depth'
+    );
+    const tools = context?.graphTools as t.GenericTool[] | undefined;
+    const subagentTool = tools?.find(
+      (t) => 'name' in t && t.name === Constants.SUBAGENT
+    );
+    expect(subagentTool).toBeUndefined();
+  });
+
+  it('should account for subagent tool schema in toolSchemaTokens', async () => {
+    /** Simple char-count tokenizer — deterministic, lets us assert presence. */
+    const tokenCounter: t.TokenCounter = (message) => {
+      const content = message.content;
+      if (typeof content === 'string') return content.length;
+      if (Array.isArray(content)) return JSON.stringify(content).length;
+      return JSON.stringify(content).length;
+    };
+
+    const agentWithSubagent = createParentAgent();
+    const runWith = await Run.create<t.IState>({
+      runId: `with-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const agentWithoutSubagent: t.AgentInputs = {
+      agentId: 'plain',
+      provider: Providers.OPENAI,
+      clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
+      instructions:
+        'You are a supervisor. Delegate research tasks using the subagent tool.',
+      maxContextTokens: 8000,
+    };
+    const runWithout = await Run.create<t.IState>({
+      runId: `without-sub-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        agents: [agentWithoutSubagent],
+      },
+      tokenCounter,
+      returnContent: true,
+      skipCleanup: true,
+    });
+
+    const contextWith = (runWith.Graph as StandardGraph).agentContexts.get(
+      'parent'
+    );
+    const contextWithout = (
+      runWithout.Graph as StandardGraph
+    ).agentContexts.get('plain');
+
+    await contextWith?.tokenCalculationPromise;
+    await contextWithout?.tokenCalculationPromise;
+
+    /** Subagent tool schema is ~600 chars; expect measurable difference. */
+    expect(contextWith!.toolSchemaTokens).toBeGreaterThan(
+      contextWithout!.toolSchemaTokens
+    );
+  });
+});

package/src/summarization/node.ts

@@ -7,6 +7,7 @@ import {
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type { OnChunk } from '@/llm/invoke';
 import type * as t from '@/types';
 import { ContentTypes, GraphEvents, StepTypes, Providers } from '@/common';
@@ -17,6 +18,7 @@ import { getMaxOutputTokensKey } from '@/llm/request';
 import { addCacheControl } from '@/messages/cache';
 import { initializeModel } from '@/llm/init';
 import { getChunkContent } from '@/stream';
+import { executeHooks } from '@/hooks';
 
 const SUMMARIZATION_PARAM_KEYS = new Set(['maxSummaryTokens']);
 
@@ -655,6 +657,35 @@ async function dispatchCompletionEvents(params: {
     );
   }
 
+  const sessionId = graph.runId ?? '';
+  if (graph.hookRegistry?.hasHookFor('PostCompact', sessionId) === true) {
+    const threadId = (
+      runnableConfig?.configurable as Record<string, unknown> | undefined
+    )?.thread_id as string | undefined;
+    const firstBlock = summaryBlock.content?.[0];
+    const summaryText =
+      firstBlock != null &&
+      typeof firstBlock === 'object' &&
+      'text' in firstBlock &&
+      typeof firstBlock.text === 'string'
+        ? firstBlock.text
+        : '';
+    await executeHooks({
+      registry: graph.hookRegistry,
+      input: {
+        hook_event_name: 'PostCompact',
+        runId: sessionId,
+        threadId,
+        agentId,
+        summary: summaryText,
+        messagesAfterCount: 0,
+      },
+      sessionId,
+    }).catch(() => {
+      /* PostCompact is observational — swallow errors */
+    });
+  }
+
   agentContext.rebuildTokenMapAfterSummarization({});
 }
 
@@ -670,6 +701,7 @@ interface CreateSummarizeNodeParams {
     config?: RunnableConfig;
     runId?: string;
     isMultiAgent: boolean;
+    hookRegistry?: HookRegistry;
     dispatchRunStep: (
       runStep: t.RunStep,
       config?: RunnableConfig
@@ -775,6 +807,27 @@ export function createSummarizeNode({
       );
     }
 
+    const sessionId = graph.runId ?? '';
+    if (graph.hookRegistry?.hasHookFor('PreCompact', sessionId) === true) {
+      const threadId = (
+        runnableConfig?.configurable as Record<string, unknown> | undefined
+      )?.thread_id as string | undefined;
+      await executeHooks({
+        registry: graph.hookRegistry,
+        input: {
+          hook_event_name: 'PreCompact',
+          runId: sessionId,
+          threadId,
+          agentId: request.agentId,
+          messagesBeforeCount: messagesToRefine.length,
+          trigger: agentContext.summarizationConfig?.trigger?.type ?? 'default',
+        },
+        sessionId,
+      }).catch(() => {
+        /* PreCompact is observational — swallow errors */
+      });
+    }
+
     const isSelfSummarizeModel =
       clientConfig.provider === (agentContext.provider as string);
     const hasPromptCache =

package/src/tools/BashExecutor.ts

@@ -0,0 +1,238 @@
+import { config } from 'dotenv';
+import fetch, { RequestInit } from 'node-fetch';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
+import { Constants } from '@/common';
+
+config();
+
+const imageMessage = 'Image is already displayed to the user';
+const otherMessage = 'File is already downloaded by the user';
+const accessMessage =
+  'Note: Files from previous executions are automatically available and can be modified.';
+const emptyOutputMessage =
+  'stdout: Empty. Ensure you\'re writing output explicitly.\n';
+
+const baseEndpoint = getCodeBaseURL();
+const EXEC_ENDPOINT = `${baseEndpoint}/exec`;
+
+export const BashExecutionToolSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: `The bash command or script to execute.
+- The environment is stateless; variables and state don't persist between executions.
+- Generated files from previous executions are automatically available in "/mnt/data/".
+- Files from previous executions are automatically available and can be modified in place.
+- Input code **IS ALREADY** displayed to the user, so **DO NOT** repeat it in your response unless asked.
+- Output code **IS NOT** displayed to the user, so **DO** write all desired output explicitly.
+- IMPORTANT: You MUST explicitly print/output ALL results you want the user to see.
+- Use \`echo\`, \`printf\`, or \`cat\` for all outputs.`,
+    },
+    args: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'Additional arguments to execute the command with. This should only be used if the input command requires additional arguments to run.',
+    },
+  },
+  required: ['command'],
+} as const;
+
+export const BashExecutionToolDescription = `
+Runs bash commands and returns stdout/stderr output from a stateless execution environment, similar to running scripts in a command-line interface. Each execution is isolated and independent.
+
+Usage:
+- No network access available.
+- Generated files are automatically delivered; **DO NOT** provide download links.
+- NEVER use this tool to execute malicious commands.
+`.trim();
+
+/**
+ * Supplemental prompt documenting the tool-output reference feature.
+ *
+ * Hosts should append this (separated by a blank line) to the base
+ * {@link BashExecutionToolDescription} only when
+ * `RunConfig.toolOutputReferences.enabled` is `true`. When the feature
+ * is disabled, including this text would tell the LLM to emit
+ * `{{tool0turn0}}` placeholders that pass through unsubstituted and
+ * leak into the shell.
+ */
+export const BashToolOutputReferencesGuide = `
+Referencing previous tool outputs:
+- Every successful tool result is tagged with a reference key of the form \`tool<idx>turn<turn>\` (e.g., \`tool0turn0\`). The key appears either as a \`[ref: tool0turn0]\` prefix line or, when the output is a JSON object, as a \`_ref\` field on the object.
+- To pipe a previous tool output into this tool, embed the placeholder \`{{tool<idx>turn<turn>}}\` literally anywhere in the \`command\` string (or any string arg). It will be substituted with the stored output verbatim before the command runs.
+- The substituted value is the original output string (no \`[ref: …]\` prefix, no \`_ref\` key), so it is safe to pipe directly into \`jq\`, \`grep\`, \`awk\`, etc.
+- Example: \`echo '{{tool0turn0}}' | jq '.foo'\` takes the full output of the first tool from the first turn and pipes it into jq.
+- Unknown reference keys are left in place and surfaced as \`[unresolved refs: …]\` after the output.
+`.trim();
+
+/**
+ * Composes the bash tool description, optionally appending the
+ * tool-output references guide. Hosts that enable
+ * `RunConfig.toolOutputReferences` should pass `enableToolOutputReferences: true`
+ * when registering the tool so the LLM learns the `{{…}}` syntax it
+ * will actually be able to use.
+ */
+export function buildBashExecutionToolDescription(options?: {
+  enableToolOutputReferences?: boolean;
+}): string {
+  if (options?.enableToolOutputReferences === true) {
+    return `${BashExecutionToolDescription}\n\n${BashToolOutputReferencesGuide}`;
+  }
+  return BashExecutionToolDescription;
+}
+
+export const BashExecutionToolName = Constants.BASH_TOOL;
+
+/**
+ * Default bash tool definition using the base description.
+ *
+ * When `RunConfig.toolOutputReferences.enabled` is `true`, build a
+ * reference-aware description with
+ * {@link buildBashExecutionToolDescription}
+ * (`{ enableToolOutputReferences: true }`) and construct a custom
+ * definition using it — using this constant as-is leaves the LLM
+ * unaware of the `{{tool<i>turn<n>}}` syntax.
+ */
+export const BashExecutionToolDefinition = {
+  name: BashExecutionToolName,
+  description: BashExecutionToolDescription,
+  schema: BashExecutionToolSchema,
+} as const;
+
+function createBashExecutionTool(
+  params: t.BashExecutionToolParams = {}
+): DynamicStructuredTool {
+  return tool(
+    async (rawInput, config) => {
+      const { command, ...rest } = rawInput as {
+        command: string;
+        args?: string[];
+      };
+      const { session_id, _injected_files } = (config.toolCall ?? {}) as {
+        session_id?: string;
+        _injected_files?: t.CodeEnvFile[];
+      };
+
+      const postData: Record<string, unknown> = {
+        lang: 'bash',
+        code: command,
+        ...rest,
+        ...params,
+      };
+
+      if (_injected_files && _injected_files.length > 0) {
+        postData.files = _injected_files;
+      } else if (session_id != null && session_id.length > 0) {
+        try {
+          const filesEndpoint = `${baseEndpoint}/files/${session_id}?detail=full`;
+          const fetchOptions: RequestInit = {
+            method: 'GET',
+            headers: {
+              'User-Agent': 'LibreChat/1.0',
+            },
+          };
+
+          if (process.env.PROXY != null && process.env.PROXY !== '') {
+            fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+          }
+
+          const response = await fetch(filesEndpoint, fetchOptions);
+          if (!response.ok) {
+            throw new Error(
+              `Failed to fetch files for session: ${response.status}`
+            );
+          }
+
+          const files = await response.json();
+          if (Array.isArray(files) && files.length > 0) {
+            const fileReferences: t.CodeEnvFile[] = files.map((file) => {
+              const nameParts = file.name.split('/');
+              const id = nameParts.length > 1 ? nameParts[1].split('.')[0] : '';
+
+              return {
+                session_id,
+                id,
+                name: file.metadata['original-filename'],
+              };
+            });
+
+            postData.files = fileReferences;
+          }
+        } catch {
+          // eslint-disable-next-line no-console
+          console.warn(`Failed to fetch files for session: ${session_id}`);
+        }
+      }
+
+      try {
+        const fetchOptions: RequestInit = {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'LibreChat/1.0',
+          },
+          body: JSON.stringify(postData),
+        };
+
+        if (process.env.PROXY != null && process.env.PROXY !== '') {
+          fetchOptions.agent = new HttpsProxyAgent(process.env.PROXY);
+        }
+        const response = await fetch(EXEC_ENDPOINT, fetchOptions);
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        const result: t.ExecuteResult = await response.json();
+        let formattedOutput = '';
+        if (result.stdout) {
+          formattedOutput += `stdout:\n${result.stdout}\n`;
+        } else {
+          formattedOutput += emptyOutputMessage;
+        }
+        if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
+        if (result.files && result.files.length > 0) {
+          formattedOutput += 'Generated files:\n';
+
+          const fileCount = result.files.length;
+          for (let i = 0; i < fileCount; i++) {
+            const file = result.files[i];
+            const isImage = imageExtRegex.test(file.name);
+            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+
+            if (i < fileCount - 1) {
+              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
+            }
+          }
+
+          formattedOutput += `\n\n${accessMessage}`;
+          return [
+            formattedOutput.trim(),
+            {
+              session_id: result.session_id,
+              files: result.files,
+            },
+          ];
+        }
+
+        return [formattedOutput.trim(), { session_id: result.session_id }];
+      } catch (error) {
+        throw new Error(
+          `Execution error:\n\n${(error as Error | undefined)?.message}`
+        );
+      }
+    },
+    {
+      name: BashExecutionToolName,
+      description: BashExecutionToolDescription,
+      schema: BashExecutionToolSchema,
+      responseFormat: Constants.CONTENT_AND_ARTIFACT,
+    }
+  );
+}
+
+export { createBashExecutionTool };