@librechat/agents 3.1.67 → 3.1.68-dev.1

package/src/scripts/multi-agent-subagent.ts

@@ -0,0 +1,246 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Manual verification script for the subagent primitive.
+ *
+ * Configures a supervisor agent with two subagent types (researcher, coder),
+ * sends a query, and confirms:
+ * 1. The parent agent delegates to a subagent via the `subagent` tool
+ * 2. The child executes with isolated context (fresh message history)
+ * 3. Only the filtered text result returns to the parent
+ * 4. The parent incorporates the result and responds
+ *
+ * Usage:
+ *   OPENAI_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts
+ *
+ * Or with Anthropic:
+ *   ANTHROPIC_API_KEY=... npx ts-node -r tsconfig-paths/register src/scripts/multi-agent-subagent.ts --provider anthropic
+ */
+
+const useAnthropic =
+  process.argv.includes('--provider') &&
+  process.argv[process.argv.indexOf('--provider') + 1] === 'anthropic';
+
+const provider = useAnthropic ? Providers.ANTHROPIC : Providers.OPENAI;
+const apiKey = useAnthropic
+  ? process.env.ANTHROPIC_API_KEY
+  : process.env.OPENAI_API_KEY;
+const modelName = useAnthropic ? 'claude-sonnet-4-20250514' : 'gpt-5.4';
+
+if (!apiKey) {
+  console.error(
+    `Missing ${useAnthropic ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY'} environment variable`
+  );
+  process.exit(1);
+}
+
+async function testSubagentPrimitive() {
+  console.log('=== Subagent Primitive Manual Verification ===\n');
+  console.log(`Provider: ${provider}`);
+  console.log(`Model: ${modelName}\n`);
+
+  const { aggregateContent } = createContentAggregator();
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider,
+    clientOptions: { modelName, apiKey },
+    instructions: `You are a supervisor agent. You have access to specialized subagents.
+
+When the user asks a research question, delegate it to the "researcher" subagent.
+When the user asks for code, delegate it to the "coder" subagent.
+
+After receiving the subagent's result, synthesize it into a clear final answer for the user.
+Always use a subagent for research or coding tasks — do not answer directly.`,
+    maxContextTokens: 16000,
+    subagentConfigs: [
+      {
+        type: 'researcher',
+        name: 'Research Specialist',
+        description:
+          'Researches topics and provides detailed summaries with sources.',
+        agentInputs: {
+          agentId: 'researcher',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a research specialist working in an isolated context.
+You receive a single task description and must answer it thoroughly.
+Be concise but comprehensive. Include key facts and details.`,
+          maxContextTokens: 8000,
+        },
+      },
+      {
+        type: 'coder',
+        name: 'Coding Specialist',
+        description:
+          'Writes, reviews, and explains code in any programming language.',
+        agentInputs: {
+          agentId: 'coder',
+          provider,
+          clientOptions: { modelName, apiKey },
+          instructions: `You are a coding specialist working in an isolated context.
+You receive a single task description and must provide working code.
+Include brief explanations. Use clean, idiomatic code.`,
+          maxContextTokens: 8000,
+        },
+      },
+    ],
+  };
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStep,
+        });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.RunStepDeltaEvent,
+        });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (event: string, data: t.StreamEventData): void => {
+        aggregateContent({
+          event: event as GraphEvents,
+          data: data as t.MessageDeltaEvent,
+        });
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-manual-${Date.now()}`,
+    graphConfig: {
+      type: 'standard',
+      agents: [parentAgent],
+    },
+    returnContent: true,
+    customHandlers,
+  });
+
+  console.log('--- Run created ---');
+  console.log(
+    `Subagent tool present: ${
+      (
+        (run.Graph as import('@/graphs/Graph').StandardGraph).agentContexts.get(
+          'supervisor'
+        )?.graphTools as t.GenericTool[] | undefined
+      )?.some((t) => 'name' in t && t.name === Constants.SUBAGENT) ?? false
+    }\n`
+  );
+
+  const conversationHistory: BaseMessage[] = [];
+
+  // Turn 1: Research question (should delegate to researcher subagent)
+  console.log('=== Turn 1: Research Question ===\n');
+  console.log(
+    'User: What are the three laws of thermodynamics? Explain briefly.\n'
+  );
+
+  const userMessage = new HumanMessage(
+    'What are the three laws of thermodynamics? Explain briefly.'
+  );
+  conversationHistory.push(userMessage);
+
+  const callerConfig = {
+    configurable: { thread_id: 'subagent-verify' },
+    streamMode: 'values' as const,
+    version: 'v2' as const,
+  };
+
+  console.log('--- Streaming response ---\n');
+  const result = await run.processStream(
+    { messages: conversationHistory },
+    callerConfig
+  );
+
+  const runMessages = run.getRunMessages();
+  console.log('\n\n--- Run Messages ---\n');
+
+  if (runMessages) {
+    for (const msg of runMessages) {
+      const type = msg._getType();
+      if (type === 'tool') {
+        const name = 'name' in msg ? msg.name : 'unknown';
+        const rawContent =
+          typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content);
+        const content = rawContent.slice(0, 200);
+        const truncated = rawContent.length > 200 ? '...' : '';
+        console.log(`[ToolMessage] name=${name}`);
+        console.log(`  content: ${content}${truncated}\n`);
+      } else if (type === 'ai') {
+        const content =
+          typeof msg.content === 'string'
+            ? msg.content.slice(0, 300)
+            : JSON.stringify(msg.content).slice(0, 300);
+        const toolCalls = 'tool_calls' in msg ? msg.tool_calls : undefined;
+        console.log(`[AIMessage]`);
+        if (toolCalls && Array.isArray(toolCalls) && toolCalls.length > 0) {
+          for (const tc of toolCalls) {
+            console.log(
+              `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 100)}...)`
+            );
+          }
+        }
+        console.log(
+          `  content: ${content}${content.length >= 300 ? '...' : ''}\n`
+        );
+      }
+    }
+
+    const subagentToolMessages = runMessages.filter(
+      (msg) =>
+        msg._getType() === 'tool' &&
+        'name' in msg &&
+        msg.name === Constants.SUBAGENT
+    );
+    console.log(`\n--- Verification ---`);
+    console.log(`Subagent tool calls found: ${subagentToolMessages.length}`);
+    console.log(`Total run messages: ${runMessages.length}`);
+    console.log(`Result content parts: ${result?.length ?? 0}`);
+
+    if (subagentToolMessages.length > 0) {
+      console.log(
+        '\nSUCCESS: Subagent was invoked and returned a filtered result.'
+      );
+      console.log(
+        'The child context was isolated — only the final text came back.'
+      );
+    } else {
+      console.log('\nNOTE: No subagent tool calls detected.');
+      console.log('The LLM may have answered directly without delegating.');
+    }
+  }
+
+  console.log('\n=== Done ===');
+}
+
+testSubagentPrimitive().catch(console.error);

package/src/scripts/programmatic_exec.ts

@@ -94,15 +94,6 @@ async function main(): Promise<void> {
   console.log('==============================================');
   console.log('Demonstrating runtime toolMap injection\n');
 
-  const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
-  if (!apiKey) {
-    console.error(
-      'Error: LIBRECHAT_CODE_API_KEY environment variable is not set.'
-    );
-    console.log('Please set it in your .env file or environment.');
-    process.exit(1);
-  }
-
   console.log('Creating mock tools...');
   const mockTools: StructuredToolInterface[] = [
     createGetTeamMembersTool(),
@@ -119,7 +110,7 @@ async function main(): Promise<void> {
   );
 
   console.log('\nCreating PTC tool (without toolMap)...');
-  const ptcTool = createProgrammaticToolCallingTool({ apiKey });
+  const ptcTool = createProgrammaticToolCallingTool();
   console.log('PTC tool created successfully!');
   console.log(
     'Note: toolMap will be passed at runtime with each invocation.\n'

package/src/scripts/subagent-event-driven-debug.ts

@@ -0,0 +1,190 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Repro for LibreChat's actual setup: event-driven tools via `toolDefinitions`
+ * + an ON_TOOL_EXECUTE handler that runs the tool. Self-spawn subagent must
+ * be able to drive the SAME tool pipeline.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+// Simulate LibreChat: tool definitions only, execution routed via event.
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression. Use for any arithmetic.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: "A JS math expression, e.g. '42 * 58'",
+      },
+    },
+    required: ['expression'],
+  },
+};
+
+async function main() {
+  console.log('=== Subagent Event-Driven Tool Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question, spawn the "self" subagent with the math task.
+The subagent MUST use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    toolDefinitions: [calculatorDef],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  let toolCallCount = 0;
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_TOOL_EXECUTE]: {
+      handle: (_event, rawData): void => {
+        const data = rawData as t.ToolExecuteBatchRequest;
+        console.log(
+          `[PARENT ON_TOOL_EXECUTE] agentId=${data.agentId} calls=${data.toolCalls
+            .map((c) => c.name)
+            .join(',')}`
+        );
+        const results: t.ToolExecuteResult[] = data.toolCalls.map((call) => {
+          toolCallCount += 1;
+          const args = call.args as { expression?: string };
+          const expression = args.expression ?? '';
+          let content: string;
+          try {
+            // eslint-disable-next-line no-eval
+            const result = eval(expression);
+            content = `${expression} = ${result}`;
+          } catch (err) {
+            content = `Error: ${String(err)}`;
+          }
+          return {
+            toolCallId: call.id!,
+            status: 'success',
+            content,
+          };
+        });
+        data.resolve(results);
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event, data): void => {
+        const d = data as { type?: string; runId?: string; agentId?: string };
+        console.log(
+          `[PARENT ${event}] type=${d.type} agentId=${d.agentId ?? '-'} runId=${d.runId ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        const r = (
+          data as { result: { type: string; tool_call?: { name?: string } } }
+        ).result;
+        console.log(
+          `[PARENT ${event}] type=${r.type} tool=${r.tool_call?.name ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_SUBAGENT_UPDATE]: {
+      handle: (_event, rawData): void => {
+        const d = rawData as t.SubagentUpdateEvent;
+        console.log(
+          `[SUBAGENT ${d.phase}] [${d.subagentType}] tool_call_id=${d.parentToolCallId ?? '-'} ${d.label ?? ''}`
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `sub-evt-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ** 3). Use the self subagent, and have it use the calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `sub-evt` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentMsgs = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentMsgs.length}`);
+  console.log(
+    `ON_TOOL_EXECUTE dispatched (parent saw): ${toolCallCount} (expected >= 1 if subagent used calculator)`
+  );
+  if (subagentMsgs[0]) {
+    console.log(
+      `\nsubagent result:\n${(subagentMsgs[0].content as string).slice(0, 600)}`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});

package/src/scripts/subagent-tools-debug.ts

@@ -0,0 +1,160 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Diagnostic: verify a self-spawned subagent can call parent's real tools.
+ * Expected before-fix: parent delegates to self; child cannot invoke calculator.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+const calculator = tool(
+  async ({ expression }) => {
+    const result = eval(expression); // don't do this in prod
+    return `${expression} = ${result}`;
+  },
+  {
+    name: 'calculator',
+    description: 'Evaluate a math expression. Use for any arithmetic.',
+    schema: z.object({
+      expression: z.string().describe("A JS math expression, e.g. '42 * 58'"),
+    }),
+  }
+);
+
+async function main() {
+  console.log('=== Subagent Tool-Access Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question that would bloat your context, spawn the "self" subagent with the math task.
+The subagent must use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    tools: [calculator],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-debug-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ^ 3). Spawn the self subagent to do this, and have IT use calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `subagent-debug` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+  const calculatorCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === 'calculator'
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentCalls.length}`);
+  console.log(
+    `calculator tool calls seen (parent): ${calculatorCalls.length} (expected: 0 if subagent did the math)`
+  );
+  if (subagentCalls.length > 0) {
+    const subResult = subagentCalls[0].content as string;
+    console.log(`\nsubagent result snippet:\n${subResult.slice(0, 600)}\n`);
+    if (/\berror\b/i.test(subResult) && /tool/i.test(subResult)) {
+      console.log('⚠️  BUG CONFIRMED: subagent result mentions tool error');
+    } else if (!/\d/.test(subResult)) {
+      console.log('⚠️  POSSIBLY BUGGY: subagent result has no numbers');
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});

package/src/scripts/test_code_api.ts

@@ -11,16 +11,10 @@ config();
 import fetch, { RequestInit } from 'node-fetch';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 
-const API_KEY = process.env.LIBRECHAT_CODE_API_KEY ?? '';
 const BASE_URL =
   process.env.LIBRECHAT_CODE_BASEURL ?? 'https://api.librechat.ai/v1';
 const PROXY = process.env.PROXY;
 
-if (!API_KEY) {
-  console.error('LIBRECHAT_CODE_API_KEY not set');
-  process.exit(1);
-}
-
 interface FileRef {
   id: string;
   name: string;
@@ -53,7 +47,6 @@ async function makeRequest(
     headers: {
       'Content-Type': 'application/json',
       'User-Agent': 'LibreChat/1.0',
-      'X-API-Key': API_KEY,
     },
   };
 

package/src/scripts/tool_search.ts

@@ -66,15 +66,6 @@ async function main(): Promise<void> {
   console.log('================================');
   console.log('Demonstrating runtime tool registry injection\n');
 
-  const apiKey = process.env.LIBRECHAT_CODE_API_KEY;
-  if (!apiKey) {
-    console.error(
-      'Error: LIBRECHAT_CODE_API_KEY environment variable is not set.'
-    );
-    console.log('Please set it in your .env file or environment.');
-    process.exit(1);
-  }
-
   console.log('Creating sample tool registry...');
   const toolRegistry = createToolSearchToolRegistry();
   console.log(
@@ -82,7 +73,7 @@ async function main(): Promise<void> {
   );
 
   console.log('\nCreating Tool Search Regex tool WITH registry for testing...');
-  const searchTool = createToolSearch({ apiKey, toolRegistry });
+  const searchTool = createToolSearch({ toolRegistry });
   console.log('Tool created successfully!');
   console.log(
     'Note: In production, ToolNode injects toolRegistry via params when invoked through the graph.\n'