@librechat/agents 3.1.67-dev.4 → 3.1.68

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

@@ -1,190 +0,0 @@
-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

@@ -1,160 +0,0 @@
-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/specs/subagent.test.ts

@@ -1,305 +0,0 @@
-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
-    );
-  });
-});