@librechat/agents 3.4.1 → 3.4.3

package/src/tools/ToolNode.ts

@@ -205,6 +205,22 @@ type RunToolBatchContext<T = unknown> = {
   errorOwnership?: ToolErrorOwnership;
 };
 
+function withSubagentReplayBatch(
+  config: RunnableConfig,
+  replayBatchKey: string | undefined
+): RunnableConfig {
+  if (replayBatchKey == null) {
+    return config;
+  }
+  return {
+    ...config,
+    configurable: {
+      ...config.configurable,
+      [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: replayBatchKey,
+    },
+  };
+}
+
 type SettledDirectToolResult = {
   output: BaseMessage | Command;
   additionalContexts: string[];
@@ -1632,15 +1648,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       this.toolMap.get(call.name) as ReplayableSubagentTool | undefined
     )?.[SUBAGENT_REPLAY_CONTROLLER];
     const replayConfig =
-      replayController == null || batchContext.replayBatchKey == null
+      replayController == null
         ? config
-        : {
-          ...config,
-          configurable: {
-            ...config.configurable,
-            [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: batchContext.replayBatchKey,
-          },
-        };
+        : withSubagentReplayBatch(config, batchContext.replayBatchKey);
     const settledOutput = await replayController?.getSettledOutput(
       call,
       replayConfig
@@ -4166,8 +4176,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           SubagentResumeManifest['executions'][number]
         >();
         for (const controller of controllers) {
-          const manifest =
-            await controller.getResumeManifest?.(parentToolCallIds);
+          const manifest = await controller.getResumeManifest?.(
+            parentToolCallIds,
+            withSubagentReplayBatch(config, baseContext.replayBatchKey)
+          );
           if (manifest != null) {
             for (const execution of manifest.executions) {
               executionsByParentCall.set(execution.parentToolCallId, execution);

package/src/tools/__tests__/SubagentExecutor.test.ts

@@ -4,7 +4,9 @@ import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
 import type { BaseMessage } from '@langchain/core/messages';
 import type {
   AgentInputs,
+  GraphSubagentConfig,
   ResolvedSubagentConfig,
+  ResolvedSingleAgentSubagentConfig,
   StandardGraphInput,
   SubagentUpdateEvent,
   SubagentUsageEvent,
@@ -14,6 +16,7 @@ import type {
 import type { StandardGraph } from '@/graphs/Graph';
 import {
   SubagentExecutor,
+  filterGraphSubagentResult,
   filterSubagentResult,
   resolveSubagentConfigs,
   buildChildInputs,
@@ -39,8 +42,8 @@ const makeChildInputs = (agentId = 'child-agent'): AgentInputs => ({
 
 const makeConfig = (
   type = 'researcher',
-  overrides: Partial<ResolvedSubagentConfig> = {}
-): ResolvedSubagentConfig => ({
+  overrides: Partial<ResolvedSingleAgentSubagentConfig> = {}
+): ResolvedSingleAgentSubagentConfig => ({
   type,
   name: 'Test Researcher',
   description: 'Researches things',
@@ -49,6 +52,18 @@ const makeConfig = (
 });
 
 describe('filterSubagentResult', () => {
+  it('treats a result member with no new AI message as textless completion', () => {
+    expect(
+      filterGraphSubagentResult(
+        {
+          messages: [new AIMessage('worker output')],
+          subagentResult: { agentId: 'result' },
+        },
+        'result'
+      )
+    ).toBe('Task completed');
+  });
+
   it('extracts text from last AIMessage string content', () => {
     const messages: BaseMessage[] = [
       new HumanMessage('task'),
@@ -220,7 +235,8 @@ describe('resolveSubagentConfigs', () => {
     const parentContext = AgentContext.fromConfig(parentInputs);
     const resolved = resolveSubagentConfigs([config], parentContext);
     expect(resolved).toHaveLength(1);
-    expect(resolved[0].agentInputs.agentId).toBe('child-agent');
+    const resolvedConfig = resolved[0];
+    expect(resolvedConfig.agentInputs.agentId).toBe('child-agent');
   });
 
   it('resolves self-spawn from parent _sourceInputs', () => {
@@ -233,8 +249,9 @@ describe('resolveSubagentConfigs', () => {
     const parentContext = AgentContext.fromConfig(parentInputs);
     const resolved = resolveSubagentConfigs([selfConfig], parentContext);
     expect(resolved).toHaveLength(1);
-    expect(resolved[0].agentInputs.provider).toBe(Providers.OPENAI);
-    expect(resolved[0].agentInputs.instructions).toBe(
+    const resolvedConfig = resolved[0];
+    expect(resolvedConfig.agentInputs.provider).toBe(Providers.OPENAI);
+    expect(resolvedConfig.agentInputs.instructions).toBe(
       'You are a parent agent.'
     );
   });
@@ -496,6 +513,55 @@ describe('SubagentExecutor', () => {
     expect(result.messages).toEqual([]);
   });
 
+  it('fails graph HITL before factories, hooks, events, or usage can run', async () => {
+    const graphConfig: GraphSubagentConfig = {
+      kind: 'graph',
+      type: 'graph-team',
+      name: 'Graph Team',
+      description: 'Runs a graph.',
+      agents: [makeChildInputs('graph-member')],
+      edges: [],
+      entryAgentId: 'graph-member',
+      resultAgentId: 'graph-member',
+    };
+    const createChildGraph = jest.fn(makeNoopGraphFactory());
+    const createChildGraphByKind = jest.fn(
+      (): StandardGraph => makeNoopGraphFactory()()
+    );
+    const hook = jest.fn(async (): Promise<Record<string, never>> => ({}));
+    const hookRegistry = new HookRegistry();
+    hookRegistry.register('SubagentStart', { hooks: [hook] });
+    const update = jest.fn();
+    const handlerRegistry = new HandlerRegistry();
+    handlerRegistry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+      handle: update,
+    });
+    const usageSink = jest.fn();
+    const executor = createExecutor({
+      configs: new Map([[graphConfig.type, graphConfig]]),
+      humanInTheLoop: { enabled: true },
+      createChildGraph,
+      createChildGraphByKind,
+      hookRegistry,
+      parentHandlerRegistry: handlerRegistry,
+      usageSink,
+    });
+
+    const result = await executor.execute({
+      description: 'Do not run.',
+      subagentType: graphConfig.type,
+    });
+
+    expect(result.content).toBe(
+      'Error: Human-in-the-loop execution is not yet supported for graph subagents.'
+    );
+    expect(createChildGraph).not.toHaveBeenCalled();
+    expect(createChildGraphByKind).not.toHaveBeenCalled();
+    expect(hook).not.toHaveBeenCalled();
+    expect(update).not.toHaveBeenCalled();
+    expect(usageSink).not.toHaveBeenCalled();
+  });
+
   it('fails closed when resumable execution has no parent tool call ID', async () => {
     const createChildGraph = jest.fn(makeNoopGraphFactory());
     const executor = createExecutor({
@@ -2558,6 +2624,107 @@ describe('SubagentExecutor', () => {
       expect(phases[phases.length - 1]).toBe('stop');
     });
 
+    it('does not let a stalled observational update handler block child completion', async () => {
+      jest.useFakeTimers();
+      try {
+        const registry = new HandlerRegistry();
+        const updateHandler = jest.fn(
+          (): Promise<void> => new Promise<void>(() => {})
+        );
+        registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+          handle: updateHandler,
+        });
+        const { factory } = makeStubGraphFactory({
+          messages: [new AIMessage('ok')],
+        });
+        const executor = createExecutor({
+          createChildGraph: factory,
+          parentHandlerRegistry: registry,
+        });
+
+        const execution = executor.execute({
+          description: 'Task',
+          subagentType: 'researcher',
+        });
+        const outcome = Promise.race([
+          execution.then(({ content }) => content),
+          new Promise<string>((resolve) =>
+            setTimeout(() => resolve('stalled'), 20_000)
+          ),
+        ]);
+
+        await jest.advanceTimersByTimeAsync(20_000);
+
+        await expect(outcome).resolves.toBe('ok');
+        expect(updateHandler).toHaveBeenCalledTimes(2);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    it('does not let a stalled queued update block the terminal stop envelope', async () => {
+      jest.useFakeTimers();
+      try {
+        const phases: SubagentUpdateEvent['phase'][] = [];
+        const registry = new HandlerRegistry();
+        registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
+          handle: (_event, rawData): void | Promise<void> => {
+            const update = rawData as SubagentUpdateEvent;
+            phases.push(update.phase);
+            if (update.phase === 'run_step') {
+              return new Promise<void>(() => {});
+            }
+          },
+        });
+        const factory: () => StandardGraph = (): StandardGraph =>
+          ({
+            createWorkflow: (): { invoke: jest.Mock } => ({
+              invoke: jest.fn().mockImplementation(async (_state, options) => {
+                const opts = options as { callbacks?: unknown[] };
+                const forwarder = (opts.callbacks ?? [])[0] as {
+                  handleCustomEvent?: (
+                    eventName: string,
+                    data: unknown
+                  ) => Promise<void> | void;
+                };
+                for (let index = 0; index < 80; index++) {
+                  await forwarder.handleCustomEvent?.(GraphEvents.ON_RUN_STEP, {
+                    id: `step_${index}`,
+                    type: StepTypes.MESSAGE_CREATION,
+                    agentId: 'researcher',
+                    index,
+                  });
+                }
+                return { messages: [new AIMessage('ok')] };
+              }),
+            }),
+            clearHeavyState: jest.fn(),
+          }) as unknown as StandardGraph;
+        const executor = createExecutor({
+          createChildGraph: factory,
+          parentHandlerRegistry: registry,
+        });
+
+        const execution = executor.execute({
+          description: 'Task',
+          subagentType: 'researcher',
+        });
+        const outcome = Promise.race([
+          execution.then(({ content }) => content),
+          new Promise<string>((resolve) =>
+            setTimeout(() => resolve('stalled'), 20_000)
+          ),
+        ]);
+
+        await jest.advanceTimersByTimeAsync(20_000);
+
+        await expect(outcome).resolves.toBe('ok');
+        expect(phases).toEqual(['start', 'run_step', 'stop']);
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
     it('allowlists forwarded run step payloads before wrapping them in ON_SUBAGENT_UPDATE', async () => {
       const subagentUpdates: SubagentUpdateEvent[] = [];
       const registry = new HandlerRegistry();
@@ -2685,18 +2852,32 @@ describe('SubagentExecutor', () => {
       expect(serialized).not.toContain('nested-completed-secret');
     });
 
-    it('does not drop non-droppable updates when the forwarding queue overflows', async () => {
+    it('bounds queued updates under overload while preserving lifecycle envelopes', async () => {
+      const phases: SubagentUpdateEvent['phase'][] = [];
       const completedIds: string[] = [];
+      let releaseFirstCompleted!: () => void;
+      const firstCompletedBlocked = new Promise<void>((resolve) => {
+        releaseFirstCompleted = resolve;
+      });
+      let markAllEmitted!: () => void;
+      const allEmitted = new Promise<void>((resolve) => {
+        markAllEmitted = resolve;
+      });
+      let blockedFirstCompleted = false;
       const registry = new HandlerRegistry();
       registry.register(GraphEvents.ON_SUBAGENT_UPDATE, {
         handle: async (_event, rawData): Promise<void> => {
           const update = rawData as SubagentUpdateEvent;
+          phases.push(update.phase);
           if (update.phase === 'run_step_completed') {
             const data = update.data as { result?: { id?: string } };
             if (data.result?.id != null) {
               completedIds.push(data.result.id);
             }
-            await new Promise((resolve) => setTimeout(resolve, 1));
+            if (!blockedFirstCompleted) {
+              blockedFirstCompleted = true;
+              await firstCompletedBlocked;
+            }
           }
         },
       });
@@ -2731,6 +2912,7 @@ describe('SubagentExecutor', () => {
                   }
                 );
               }
+              markAllEmitted();
               return { messages: [new AIMessage('ok')] };
             }),
           }),
@@ -2742,14 +2924,21 @@ describe('SubagentExecutor', () => {
         parentHandlerRegistry: registry,
       });
 
-      await executor.execute({
+      const execution = executor.execute({
         description: 'Task',
         subagentType: 'researcher',
       });
+      await allEmitted;
+      releaseFirstCompleted();
+      await execution;
 
-      expect(completedIds).toHaveLength(80);
+      expect(completedIds).toHaveLength(65);
       expect(completedIds[0]).toBe('step_0');
+      expect(completedIds).not.toContain('step_1');
+      expect(completedIds).toContain('step_16');
       expect(completedIds[completedIds.length - 1]).toBe('step_79');
+      expect(phases[0]).toBe('start');
+      expect(phases[phases.length - 1]).toBe('stop');
     });
 
     it('does NOT forward ON_TOOL_EXECUTE when the parent registry has no handler (safe fallback)', async () => {

package/src/tools/__tests__/SubagentReplay.test.ts

@@ -9,6 +9,8 @@ describe('SubagentReplay manifest', () => {
   const execution = {
     parentToolCallId: 'call_parent',
     childRunId: 'child-run',
+    subagentType: 'researcher',
+    configId: 'researcher@v1',
     approvalExecutionScope: 'child-approval-scope',
     checkpoints: [
       {
@@ -82,6 +84,33 @@ describe('SubagentReplay manifest', () => {
     });
   });
 
+  it('accepts legacy executions without a bound subagent type', () => {
+    const { subagentType: _subagentType, ...legacyExecution } = execution;
+    const manifest = { version: 1 as const, executions: [legacyExecution] };
+    const payload = attachSubagentResumeManifest(
+      { type: 'tool_approval' },
+      manifest
+    );
+
+    expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+  });
+
+  it.each(['', 42, { type: 'researcher' }])(
+    'rejects malformed bound subagent type %#',
+    (subagentType) => {
+      const manifest = {
+        version: 1 as const,
+        executions: [{ ...execution, subagentType }],
+      };
+
+      expect(
+        getSubagentResumeManifest({
+          __librechat_subagent_resume_manifest: manifest,
+        })
+      ).toBeUndefined();
+    }
+  );
+
   it.each([
     ['string', 'approve this child'],
     ['number', 42],

package/src/tools/__tests__/directToolHITLResumeScope.test.ts

@@ -138,9 +138,21 @@ describe('direct-path HITL: resume scope', () => {
     };
     const replayableTool = directTool as StructuredToolInterface &
       ReplayableSubagentTool;
+    const getResumeManifest = jest.fn(
+      async (
+        _parentToolCallIds?: ReadonlySet<string>,
+        _config?: RunnableConfig
+      ) => manifest
+    );
+    const getSettledOutput = jest.fn(
+      async (
+        _call: ToolCall,
+        _config: RunnableConfig
+      ): Promise<SettledSubagentToolOutput | undefined> => undefined
+    );
     replayableTool[SUBAGENT_REPLAY_CONTROLLER] = {
-      getResumeManifest: async () => manifest,
-      getSettledOutput: async () => undefined,
+      getResumeManifest,
+      getSettledOutput,
       persistSettledOutput: async () => {},
     };
     const node = new ToolNode({
@@ -166,6 +178,20 @@ describe('direct-path HITL: resume scope', () => {
       throw new Error('expected primitive child interrupt');
     }
     const internalPayload = interrupted.__interrupt__[0].value;
+    const replayBatchKey =
+      getSettledOutput.mock.calls[0]?.[1].configurable?.[
+        SUBAGENT_PARENT_BATCH_CONFIG_KEY
+      ];
+    expect(replayBatchKey).toEqual(expect.any(String));
+    expect(getResumeManifest).toHaveBeenCalledWith(
+      new Set(['call_primitive']),
+      expect.objectContaining({
+        configurable: expect.objectContaining({
+          thread_id: 'parent-thread',
+          [SUBAGENT_PARENT_BATCH_CONFIG_KEY]: replayBatchKey,
+        }),
+      })
+    );
     expect(getSubagentResumeManifest(internalPayload)).toEqual(manifest);
     expect(stripSubagentResumeManifest(internalPayload)).toBe('confirm child');
   });

package/src/tools/__tests__/subagentHooks.test.ts

@@ -496,6 +496,60 @@ describe('Subagent hook integration (end-to-end via Run)', () => {
     expect(captured!.messages.length).toBeGreaterThan(0);
   });
 
+  it('propagates a caller-only Run signal into lazy subagent resolution', async () => {
+    const callerAbort = new AbortController();
+    let resolverSignal: AbortSignal | undefined;
+    let markResolverStarted = (): void => undefined;
+    const resolverStarted = new Promise<void>((resolve) => {
+      markResolverStarted = resolve;
+    });
+    let releaseResolver = (): void => undefined;
+    const resolverRelease = new Promise<void>((resolve) => {
+      releaseResolver = resolve;
+    });
+    const parent = createParentAgent();
+    const eagerChild = parent.subagentConfigs?.[0]?.agentInputs;
+    if (eagerChild == null) {
+      throw new Error('Expected eager child inputs.');
+    }
+    parent.subagentConfigs = [
+      {
+        type: 'researcher',
+        name: 'Researcher',
+        description: 'Researches topics',
+        configId: 'caller-signal-researcher@v1',
+        resolveAgentInputs: async (context) => {
+          resolverSignal = context.signal;
+          markResolverStarted();
+          await resolverRelease;
+          return eagerChild;
+        },
+      },
+    ];
+    const run = await Run.create<t.IState>({
+      runId: `subagent-caller-signal-${Date.now()}`,
+      graphConfig: { type: 'standard', agents: [parent] },
+      returnContent: true,
+      skipCleanup: true,
+    });
+    run.Graph!.overrideTestModel(['Delegating...', 'Caller cancelled.'], 5, [
+      makeSubagentToolCall('call_caller_signal'),
+    ]);
+
+    const processing = run.processStream(
+      { messages: [new HumanMessage('cancel this delegation')] },
+      { ...callerConfig, signal: callerAbort.signal }
+    );
+    await resolverStarted;
+    callerAbort.abort(new Error('caller cancelled'));
+    await Promise.resolve();
+    const resolverWasAborted = resolverSignal?.aborted === true;
+    releaseResolver();
+    await processing.catch(() => undefined);
+
+    expect(resolverWasAborted).toBe(true);
+  });
+
   it('SubagentStart deny blocks subagent execution and returns blocked message', async () => {
     const registry = new HookRegistry();
     const denyHook: HookCallback<
@@ -1084,14 +1138,37 @@ describe('Subagent hook integration (end-to-end via Run)', () => {
         schema: z.object({}),
       }
     );
+    const resolutionContexts: t.SubagentResolveContext[] = [];
+    const createLazyParent = (): t.AgentInputs => {
+      const parent = createParentAgentWithPrimitiveInterruptTool(
+        primitiveInterruptTool
+      );
+      const child = parent.subagentConfigs?.[0];
+      const childInputs = child?.agentInputs;
+      if (child == null || childInputs == null) {
+        throw new Error('Expected a child agent configuration.');
+      }
+      return {
+        ...parent,
+        subagentConfigs: [
+          {
+            ...child,
+            agentInputs: undefined,
+            configId: 'primitive-interrupt-child@v1',
+            resolveAgentInputs: async (context) => {
+              resolutionContexts.push(context);
+              return childInputs;
+            },
+          },
+        ],
+      };
+    };
     const createRun = (currentRunId: string): Promise<Run<t.IState>> =>
       Run.create<t.IState>({
         runId: currentRunId,
         graphConfig: {
           type: 'standard',
-          agents: [
-            createParentAgentWithPrimitiveInterruptTool(primitiveInterruptTool),
-          ],
+          agents: [createLazyParent()],
           compileOptions: { checkpointer },
         },
         returnContent: true,
@@ -1140,6 +1217,16 @@ describe('Subagent hook integration (end-to-end via Run)', () => {
     );
 
     expect(rebuiltRun.getInterrupt()).toBeUndefined();
+    expect(resolutionContexts).toHaveLength(2);
+    expect(resolutionContexts[0].executionId).toBe(
+      resolutionContexts[1].executionId
+    );
+    expect(resolutionContexts[0].descriptor.configId).toBe(
+      'primitive-interrupt-child@v1'
+    );
+    expect(resolutionContexts[1].descriptor.configId).toBe(
+      'primitive-interrupt-child@v1'
+    );
     expect(resumedValues).toEqual(['approved after restart']);
     expect(JSON.stringify(rebuiltContent)).toContain('Final answer.');
     expect(JSON.stringify(rebuiltContent)).not.toContain('host edit on resume');