@librechat/agents 3.1.66-dev.0 → 3.1.67-dev.0

package/src/graphs/Graph.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-console */
 import { nanoid } from 'nanoid';
+import { tool } from '@langchain/core/tools';
 import { ToolNode } from '@langchain/langgraph/prebuilt';
 import { Runnable, RunnableConfig } from '@langchain/core/runnables';
 import { ToolMessage, AIMessageChunk } from '@langchain/core/messages';
@@ -39,6 +40,8 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
+import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
+import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
@@ -1152,6 +1155,90 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       throw new Error(`Agent context not found for agentId: ${agentId}`);
     }
 
+    /**
+     * Depth countdown across graph boundaries: the parent's `maxSubagentDepth`
+     * becomes this executor's `maxDepth`. When the child graph is constructed,
+     * `buildChildInputs()` decrements `maxSubagentDepth` on the child's
+     * `AgentInputs` (only when `allowNested: true`; otherwise subagentConfigs
+     * are stripped entirely). The child graph's own `createAgentNode()` then
+     * reads the decremented value here and creates a narrower executor —
+     * recursion is bounded even though each graph has its own separate
+     * executor instance.
+     */
+    const effectiveSubagentDepth = agentContext.maxSubagentDepth ?? 1;
+    if (
+      agentContext.subagentConfigs != null &&
+      agentContext.subagentConfigs.length > 0 &&
+      effectiveSubagentDepth > 0
+    ) {
+      const resolvedConfigs = resolveSubagentConfigs(
+        agentContext.subagentConfigs,
+        agentContext
+      );
+      if (resolvedConfigs.length > 0) {
+        const executor = new SubagentExecutor({
+          configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
+          parentSignal: this.signal,
+          hookRegistry: this.hookRegistry,
+          parentRunId: this.runId ?? '',
+          parentAgentId: agentContext.agentId,
+          tokenCounter: agentContext.tokenCounter,
+          maxDepth: effectiveSubagentDepth,
+          createChildGraph: (input): StandardGraph => new StandardGraph(input),
+        });
+
+        const subagentTool = tool(async (rawInput, config) => {
+          const input = rawInput as {
+            description?: string;
+            subagent_type?: string;
+          };
+          const description =
+            typeof input.description === 'string' &&
+            input.description.trim().length > 0
+              ? input.description
+              : 'No task description provided';
+          const subagentType =
+            typeof input.subagent_type === 'string' ? input.subagent_type : '';
+          const threadId = config.configurable?.thread_id as string | undefined;
+          const result = await executor.execute({
+            description,
+            subagentType,
+            threadId,
+          });
+          return result.content;
+        }, buildSubagentToolParams(resolvedConfigs));
+
+        if (!agentContext.graphTools) {
+          agentContext.graphTools = [];
+        }
+        (agentContext.graphTools as t.GenericTool[]).push(subagentTool);
+
+        /**
+         * Refresh toolSchemaTokens to include the subagent tool's schema.
+         * `calculateInstructionTokens()` was kicked off in `fromConfig()`
+         * before graphTools was populated, so its result did not count this
+         * tool. Without this retrigger, token-budget/pruning logic
+         * underestimates prompt overhead.
+         */
+        if (agentContext.tokenCounter) {
+          const { tokenCounter, baseIndexTokenCountMap } = agentContext;
+          agentContext.tokenCalculationPromise = agentContext
+            .calculateInstructionTokens(tokenCounter)
+            .then(() => {
+              agentContext.updateTokenMapWithInstructions(
+                baseIndexTokenCountMap
+              );
+            })
+            .catch((err) => {
+              console.error(
+                'Error recalculating instruction tokens after subagent tool injection:',
+                err
+              );
+            });
+        }
+      }
+    }
+
     const agentNode = `${AGENT}${agentId}` as const;
     const toolNode = `${TOOLS}${agentId}` as const;
     const summarizeNode = `${SUMMARIZE}${agentId}` as const;
@@ -1207,6 +1294,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             },
             runId: this.runId,
             isMultiAgent: this.isMultiAgentGraph(),
+            hookRegistry: this.hookRegistry,
             dispatchRunStep: async (runStep, nodeConfig) => {
               this.contentData.push(runStep);
               this.contentIndexMap.set(runStep.id, runStep.index);

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

@@ -0,0 +1,214 @@
+// 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 type {
+  HookCallback,
+  PreCompactHookInput,
+  PreCompactHookOutput,
+  PostCompactHookInput,
+  PostCompactHookOutput,
+} from '../types';
+
+const SUMMARY_RESPONSE = '## Summary\nUser asked a question and got an answer.';
+
+const callerConfig = {
+  configurable: { thread_id: 'compact-test' },
+  streamMode: 'values' as const,
+  version: 'v2' as const,
+};
+
+let getChatModelClassSpy: jest.SpyInstance;
+const originalGetChatModelClass = providers.getChatModelClass;
+
+function mockSummarizationModel(): void {
+  getChatModelClassSpy = jest
+    .spyOn(providers, 'getChatModelClass')
+    .mockImplementation(((provider: Providers) => {
+      if (provider === Providers.OPENAI) {
+        return class extends FakeListChatModel {
+          constructor(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            _options: any
+          ) {
+            super({ responses: [SUMMARY_RESPONSE] });
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        } as any;
+      }
+      return originalGetChatModelClass(provider);
+    }) as typeof providers.getChatModelClass);
+}
+
+function buildConversation(): t.IState {
+  const messages: import('@langchain/core/messages').BaseMessage[] = [];
+  for (let i = 0; i < 20; i++) {
+    messages.push(new HumanMessage(`Question ${i}: ` + 'padding '.repeat(50)));
+    messages.push(new AIMessage(`Answer ${i}: ` + 'response '.repeat(50)));
+  }
+  return { messages };
+}
+
+async function createCompactingRun(
+  tokenCounter: t.TokenCounter,
+  hooks?: HookRegistry,
+  runId = 'compact-run'
+): Promise<Run<t.IState>> {
+  const conversation = buildConversation();
+  const indexTokenCountMap: Record<string, number> = {};
+  for (let i = 0; i < conversation.messages.length; i++) {
+    indexTokenCountMap[String(i)] = tokenCounter(conversation.messages[i]);
+  }
+  return Run.create<t.IState>({
+    runId,
+    graphConfig: {
+      type: 'standard',
+      llmConfig: {
+        provider: Providers.OPENAI,
+        streaming: true,
+        streamUsage: false,
+      },
+      instructions: 'Be concise.',
+      maxContextTokens: 200,
+      summarizationEnabled: true,
+      summarizationConfig: {
+        provider: Providers.OPENAI,
+      },
+    },
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers: {
+      [GraphEvents.TOOL_END]: new ToolEndHandler(),
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    },
+    hooks,
+    tokenCounter,
+    indexTokenCountMap,
+  });
+}
+
+describe('Compaction hook integration', () => {
+  jest.setTimeout(30_000);
+
+  let tokenCounter: t.TokenCounter;
+
+  beforeAll(async () => {
+    tokenCounter = await createTokenCounter();
+  });
+
+  beforeEach(() => {
+    mockSummarizationModel();
+  });
+
+  afterEach(() => {
+    getChatModelClassSpy.mockRestore();
+  });
+
+  describe('PreCompact', () => {
+    it('fires with messagesBeforeCount and trigger', async () => {
+      const registry = new HookRegistry();
+      let captured: PreCompactHookInput | undefined;
+      const hook: HookCallback<'PreCompact'> = async (
+        input
+      ): Promise<PreCompactHookOutput> => {
+        captured = input;
+        return {};
+      };
+      registry.register('PreCompact', { hooks: [hook] });
+
+      const run = await createCompactingRun(tokenCounter, registry);
+      run.Graph!.overrideTestModel(['Final answer after compaction.']);
+      const inputs = buildConversation();
+      await run.processStream(inputs, callerConfig);
+
+      expect(captured).toBeDefined();
+      expect(captured!.hook_event_name).toBe('PreCompact');
+      expect(captured!.messagesBeforeCount).toBeGreaterThan(0);
+      expect(captured!.runId).toBe('compact-run');
+      expect(captured!.threadId).toBe('compact-test');
+      expect(captured!.trigger).toBe('default');
+      expect(captured!.agentId).toBeDefined();
+    });
+  });
+
+  describe('PostCompact', () => {
+    it('fires with summary text after compaction', async () => {
+      const registry = new HookRegistry();
+      let captured: PostCompactHookInput | undefined;
+      const hook: HookCallback<'PostCompact'> = async (
+        input
+      ): Promise<PostCompactHookOutput> => {
+        captured = input;
+        return {};
+      };
+      registry.register('PostCompact', { hooks: [hook] });
+
+      const run = await createCompactingRun(tokenCounter, registry);
+      run.Graph!.overrideTestModel(['Final answer after compaction.']);
+      const inputs = buildConversation();
+      await run.processStream(inputs, callerConfig);
+
+      expect(captured).toBeDefined();
+      expect(captured!.hook_event_name).toBe('PostCompact');
+      expect(captured!.threadId).toBe('compact-test');
+      expect(captured!.summary).toBe(SUMMARY_RESPONSE);
+      expect(captured!.messagesAfterCount).toBe(0);
+      expect(captured!.agentId).toBeDefined();
+    });
+  });
+
+  describe('error resilience', () => {
+    it('throwing PreCompact hook does not crash compaction', async () => {
+      const registry = new HookRegistry();
+      const throwingHook: HookCallback<
+        'PreCompact'
+      > = async (): Promise<PreCompactHookOutput> => {
+        throw new Error('pre hook crash');
+      };
+      registry.register('PreCompact', { hooks: [throwingHook] });
+
+      const run = await createCompactingRun(tokenCounter, registry);
+      run.Graph!.overrideTestModel(['Answer after compaction.']);
+      const inputs = buildConversation();
+
+      await expect(
+        run.processStream(inputs, callerConfig)
+      ).resolves.not.toThrow();
+    });
+
+    it('throwing PostCompact hook does not crash compaction', async () => {
+      const registry = new HookRegistry();
+      const throwingHook: HookCallback<
+        'PostCompact'
+      > = async (): Promise<PostCompactHookOutput> => {
+        throw new Error('post hook crash');
+      };
+      registry.register('PostCompact', { hooks: [throwingHook] });
+
+      const run = await createCompactingRun(tokenCounter, registry);
+      run.Graph!.overrideTestModel(['Answer after compaction.']);
+      const inputs = buildConversation();
+
+      await expect(
+        run.processStream(inputs, callerConfig)
+      ).resolves.not.toThrow();
+    });
+  });
+
+  describe('no-hooks baseline', () => {
+    it('summarization works identically without hooks', async () => {
+      const run = await createCompactingRun(tokenCounter);
+      run.Graph!.overrideTestModel(['Answer.']);
+      const inputs = buildConversation();
+      const result = await run.processStream(inputs, callerConfig);
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/hooks/index.ts

@@ -2,8 +2,10 @@
 //
 // Hook lifecycle system for `@librechat/agents`. Re-exported from
 // `src/index.ts` and consumed by `Run.processStream` (RunStart,
-// UserPromptSubmit, Stop, StopFailure) and `ToolNode.dispatchToolEvents`
-// (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied).
+// UserPromptSubmit, Stop, StopFailure), `ToolNode.dispatchToolEvents`
+// (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied),
+// `createSummarizeNode` (PreCompact, PostCompact), and
+// `SubagentExecutor.execute` (SubagentStart, SubagentStop).
 export { HookRegistry } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
 export {

package/src/hooks/types.ts

@@ -139,12 +139,28 @@ export interface StopFailureHookInput extends BaseHookInput {
 export interface PreCompactHookInput extends BaseHookInput {
   hook_event_name: 'PreCompact';
   messagesBeforeCount: number;
-  trigger: 'threshold' | 'manual' | 'error';
+  /**
+   * What triggered compaction. Matches `SummarizationTrigger.type` from the
+   * agent's summarization config. `'default'` means no trigger was
+   * configured and compaction fired because messages were pruned.
+   */
+  trigger:
+    | 'token_ratio'
+    | 'remaining_tokens'
+    | 'messages_to_refine'
+    | 'default'
+    | (string & {});
 }
 
 export interface PostCompactHookInput extends BaseHookInput {
   hook_event_name: 'PostCompact';
   summary: string;
+  /**
+   * Number of messages remaining after compaction. The summarize node
+   * returns a `removeAll` signal that clears all messages from state;
+   * the summary itself is injected into the system prompt, not as a
+   * message. This is `0` at the point of hook dispatch.
+   */
   messagesAfterCount: number;
 }
 

package/src/index.ts

@@ -18,6 +18,8 @@ export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/BashProgrammaticToolCalling';
 export * from './tools/SkillTool';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
 export * from './tools/ReadFile';
 export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';

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);