🎒 fix: Carry Subagent Identity Past Streaming (#15795)

* fix: resolve saved subagent display identity

* fix: persist explicit subagent execution identity

Author: dustinhealy

api/server/controllers/agents/callbacks.js

@@ -29,6 +29,7 @@ const {
   getModelRefusalInfo,
   shouldSignalSandboxStart,
   getToolInputValidationDetails,
+  captureSubagentIdentity,
 } = require('@librechat/api');
 const { processFileCitations } = require('~/server/services/Files/Citations');
 const { processCodeOutput, runPreviewFinalize } = require('~/server/services/Files/Code/process');
@@ -764,6 +765,7 @@ function getDefaultHandlers({
           subagentAggregatorsByToolCallId.set(key, aggregator);
         }
         try {
+          captureSubagentIdentity(aggregator, data);
           feedSubagentAggregator(aggregator, data);
         } catch (err) {
           logger.warn(

api/server/controllers/agents/client.js

@@ -818,6 +818,9 @@ class AgentClient extends BaseClient {
       const aggregator = buffer.get(toolCall.id);
       if (!aggregator) continue;
       try {
+        if (aggregator.subagentIdentity != null) {
+          toolCall.subagentIdentity = aggregator.subagentIdentity;
+        }
         /** `createContentAggregator` returns a sparse array (undefined
          *  slots for indices that never received content). Strip those
          *  so the persisted shape is a clean `TMessageContentParts[]`. */

api/server/controllers/agents/client.test.js

@@ -8016,6 +8016,29 @@ describe('AgentClient - finalizeSubagentContent', () => {
     return map;
   };
 
+  it.each(['agent', 'graph'])(
+    'persists %s identity even when the child has no content',
+    async (subagentKind) => {
+      const identity = {
+        subagentKind,
+        subagentAgentId: subagentKind === 'graph' ? 'graph:agent-1' : 'agent-1',
+      };
+      const buffer = await runSubagentEvents([
+        { ...event('start', undefined), ...identity, subagentType: 'agent-1' },
+        { ...event('error', undefined), ...identity, subagentType: 'agent-1' },
+      ]);
+      const client = makeClient(buffer);
+      client.contentParts = [
+        { type: 'tool_call', tool_call: { id: 'unrelated', name: Constants.SUBAGENT } },
+        { type: 'tool_call', tool_call: { id: 'call_sub', name: Constants.SUBAGENT } },
+      ];
+      client.finalizeSubagentContent();
+      expect(client.contentParts[0].tool_call.subagentIdentity).toBeUndefined();
+      expect(client.contentParts[1].tool_call.subagentIdentity).toEqual(identity);
+      expect(buffer.size).toBe(0);
+    },
+  );
+
   it('attaches aggregated subagent_content to the matching subagent tool_call part', async () => {
     const buffer = await runSubagentEvents([
       event('run_step', {

client/src/components/Chat/Messages/Content/Part.tsx

@@ -306,6 +306,7 @@ const Part = memo(function Part({
               runStepStatus={toolCall.runStepStatus}
               attachments={attachments}
               persistedContent={persistedContent}
+              subagentIdentity={toolCall.subagentIdentity}
               hideAttachments={hideAttachments}
             />
           );

client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx

@@ -15,6 +15,7 @@ import {
   useSubagentProgress,
 } from '~/components/Chat/Subagents/state';
 import { adaptLivePersistedActivity } from '~/components/Chat/Subagents/adapters';
+import { resolveSubagentAgentId } from '~/components/Chat/Subagents/identity';
 import { useOpenSubagentPanel } from '~/components/Chat/Subagents/surface';
 import { MessageContext } from '~/Providers/MessageContext';
 import { useShareContext } from '~/Providers/ShareContext';
@@ -46,6 +47,7 @@ interface SubagentCallProps {
    *  runs recorded before the persistence path landed will not have this
    *  field; those fall back to the atom (or the raw `output` string). */
   persistedContent?: TMessageContentParts[];
+  subagentIdentity?: PartMetadata['subagentIdentity'];
   hideAttachments?: boolean;
 }
 
@@ -166,6 +168,7 @@ export default function SubagentCall({
   output,
   attachments,
   persistedContent,
+  subagentIdentity,
   hideAttachments = false,
 }: SubagentCallProps) {
   const localize = useLocalize();
@@ -187,12 +190,7 @@ export default function SubagentCall({
 
   const subagentType = progress?.subagentType ?? extractSubagentType(args);
   const isSelfSpawn = subagentType === 'self';
-  /** Avatar lookup for the header icon. We use the child's agent id when
-   *  present (explicit subagents); self-spawn falls back to the agents
-   *  map being unavailable → the Users SVG. The tool UI has a similar
-   *  icon-left-of-label pattern; this reuses `MessageIcon` so the agent's
-   *  configured avatar lands here without a separate image pipeline. */
-  const subagentAgentId = progress?.subagentAgentId;
+  const subagentAgentId = resolveSubagentAgentId(progress, subagentIdentity);
   const subagentAgent = subagentAgentId ? agentsMap?.[subagentAgentId] : undefined;
   /**
    * Tri-state status resolution, aligned with `ToolCall.tsx`:
@@ -326,6 +324,7 @@ export default function SubagentCall({
       toolCallId,
       partIndex,
       subagentType,
+      subagentIdentity,
       ...(prompt == null ? {} : { prompt }),
       ...(backgroundHandle == null ? { legacyOutput: output } : {}),
       ...(persistedContent == null ? {} : { persistedContent }),
@@ -356,6 +355,7 @@ export default function SubagentCall({
       runStepStatus,
       shareId,
       subagentType,
+      subagentIdentity,
       toolCallId,
     ],
   );

client/src/components/Chat/Messages/Content/Parts/__tests__/SubagentCall.test.tsx

@@ -3,7 +3,7 @@ import { RecoilRoot } from 'recoil';
 import { useAtomValue, useStore } from 'jotai';
 import { MemoryRouter } from 'react-router-dom';
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
-import type { SubagentUpdateEvent } from 'librechat-data-provider';
+import type { SubagentUpdateEvent, SubagentIdentity } from 'librechat-data-provider';
 import type {
   SubagentAggregatorState,
   SubagentContentPart,
@@ -61,8 +61,17 @@ jest.mock('lucide-react', () => ({
   Users: () => <span>users</span>,
 }));
 
-jest.mock('~/Providers', () => ({ useAgentsMapContext: () => ({}) }));
-jest.mock('~/components/Share/MessageIcon', () => ({ __esModule: true, default: () => null }));
+jest.mock('~/Providers', () => ({
+  useAgentsMapContext: () => ({
+    'agent-1': { id: 'agent-1', name: 'Analyst One', avatar: { filepath: '/analyst.png' } },
+  }),
+}));
+jest.mock('~/components/Share/MessageIcon', () => ({
+  __esModule: true,
+  default: ({ agent }: { agent: { name: string; avatar: { filepath: string } } }) => (
+    <img alt={agent.name} src={agent.avatar.filepath} />
+  ),
+}));
 jest.mock('~/hooks/MCP', () => ({ useMCPServerNames: () => mockMCPServerNames }));
 jest.mock('~/utils', () => ({
   ...jest.requireActual('~/utils/toolLabels'),
@@ -111,6 +120,7 @@ function renderWithState(args: {
   progress?: SubagentProgress | null;
   output?: string;
   toolArgs?: Record<string, unknown>;
+  subagentIdentity?: SubagentIdentity;
 }) {
   const setter = { current: null as null | ((next: SubagentProgress | null) => void) };
   let selection: ActiveSubagentPanel | null = null;
@@ -146,6 +156,7 @@ function renderWithState(args: {
               isSubmitting={args.isSubmitting ?? false}
               args={args.toolArgs ?? { subagent_type: 'self', description: 'compute' }}
               output={args.output}
+              subagentIdentity={args.subagentIdentity}
             />
           </MessageContext.Provider>
         </RecoilRoot>
@@ -174,6 +185,58 @@ const event = (
 });
 
 describe('SubagentCall', () => {
+  it('keeps the configured name and avatar after live progress is cleared', () => {
+    const { setProgress } = renderWithState({
+      toolCallId: 'identity',
+      initialProgress: 1,
+      toolArgs: { subagent_type: 'agent-1' },
+      subagentIdentity: { subagentKind: 'agent', subagentAgentId: 'agent-1' },
+      progress: progressFromEvents({
+        subagentRunId: 'child-run',
+        subagentType: 'agent-1',
+        subagentAgentId: 'agent-1',
+        status: 'stop',
+        events: [],
+      }),
+    });
+    expect(screen.getByText('Analyst One')).toBeInTheDocument();
+    expect(screen.getByRole('img', { hidden: true })).toHaveAttribute('src', '/analyst.png');
+    setProgress(null);
+    expect(screen.getByText('Analyst One')).toBeInTheDocument();
+    expect(screen.getByRole('img', { hidden: true })).toHaveAttribute('src', '/analyst.png');
+  });
+
+  it.each([undefined, { subagentKind: 'graph' as const, subagentAgentId: 'graph:agent-1' }])(
+    'does not infer a saved agent from an ambiguous graph or legacy type',
+    (subagentIdentity) => {
+      const { getSelection } = renderWithState({
+        toolCallId: 'graph-identity',
+        initialProgress: 1,
+        toolArgs: { subagent_type: 'agent-1' },
+        output: 'Graph result',
+        subagentIdentity,
+      });
+      expect(screen.queryByText('Analyst One')).not.toBeInTheDocument();
+      expect(screen.getByText('users')).toBeInTheDocument();
+      fireEvent.click(screen.getByRole('button', { name: 'Ran agent' }));
+      expect(getSelection()?.subagentIdentity).toEqual(subagentIdentity);
+    },
+  );
+
+  it.each(['agent-1', 'missing-agent', 'self'])(
+    'renders saved identity %s without streaming state',
+    (agentId) => {
+      renderWithState({
+        toolCallId: 'saved-identity',
+        initialProgress: 1,
+        toolArgs: { subagent_type: agentId },
+        subagentIdentity: { subagentKind: 'agent', subagentAgentId: agentId },
+      });
+      expect(screen.queryByText('Analyst One') != null).toBe(agentId === 'agent-1');
+      expect(screen.queryByText('users') != null).toBe(agentId !== 'agent-1');
+    },
+  );
+
   it.each([
     ['Running agent', 0.3, true, 'run_step'],
     ['Ran agent', 1, false, undefined],

client/src/components/Chat/Subagents/SubagentThreadPanel.test.tsx

@@ -106,13 +106,14 @@ jest.mock('~/hooks', () => ({
    *  runs before the panel's own React handler. Stubbing it made the panel's
    *  Escape assertions pass in both directions. */
   useFocusTrap: jest.requireActual('~/hooks/useFocusTrap').default,
-  useLocalize: () => (key: string) => key,
+  useLocalize: () => (key: string, values?: { 0: string }) =>
+    values == null ? key : `${key}: ${values[0]}`,
   useNavigateToConvo: () => ({ navigateToConvo: mockNavigateToConvo }),
 }));
 
 jest.mock('~/Providers', () => ({
   useAgentsMapContext: () => ({
-    'agent-1': { id: 'agent-1', name: 'Analyst One' },
+    'agent-1': { id: 'agent-1', name: 'Analyst One', avatar: { filepath: '/analyst.png' } },
     'agent-2': { id: 'agent-2', name: 'Analyst Two' },
   }),
 }));
@@ -468,6 +469,55 @@ describe('SubagentThreadPanel', () => {
     jest.restoreAllMocks();
   });
 
+  it.each(['agent-1', 'missing-agent', 'self'])(
+    'resolves the saved foreground identity %s in the panel',
+    (subagentType) => {
+      mockUseSubagentThreadQuery.mockReturnValue({ isLoading: false, isError: false });
+      const foregroundSelection = {
+        ...selection,
+        durable: undefined,
+        subagentType,
+        subagentIdentity: { subagentKind: 'agent' as const, subagentAgentId: subagentType },
+      };
+      render(
+        <Root>
+          <SubagentThreadPanel selection={foregroundSelection} />
+        </Root>,
+      );
+      const title =
+        subagentType === 'self'
+          ? 'com_ui_subagent_dialog_title_self'
+          : `com_ui_subagent_dialog_title: ${subagentType === 'agent-1' ? 'Analyst One' : subagentType}`;
+      expect(screen.getByRole('heading', { name: title })).toBeInTheDocument();
+      if (subagentType === 'agent-1') {
+        expect(screen.getByAltText('Analyst One avatar')).toHaveAttribute('src', '/analyst.png');
+      }
+    },
+  );
+
+  it.each([undefined, { subagentKind: 'graph' as const, subagentAgentId: 'graph:agent-1' }])(
+    'does not resolve graph or legacy panel types as saved agents',
+    (subagentIdentity) => {
+      mockUseSubagentThreadQuery.mockReturnValue({ isLoading: false, isError: false });
+      render(
+        <Root>
+          <SubagentThreadPanel
+            selection={{
+              ...selection,
+              durable: undefined,
+              subagentType: 'agent-1',
+              subagentIdentity,
+            }}
+          />
+        </Root>,
+      );
+      expect(
+        screen.getByRole('heading', { name: 'com_ui_subagent_dialog_title: agent-1' }),
+      ).toBeInTheDocument();
+      expect(screen.queryByAltText('Analyst One avatar')).not.toBeInTheDocument();
+    },
+  );
+
   it('renders a bounded read-only activity timeline and closes its selection', async () => {
     mockUseSubagentThreadQuery.mockReturnValue({
       data: completedView,

client/src/components/Chat/Subagents/SubagentThreadPanel.tsx

@@ -51,6 +51,7 @@ import { useFocusTrap, useLocalize, useNavigateToConvo } from '~/hooks';
 import { useParentSubagents } from './ParentSubagentsProvider';
 import SubagentConversation from './SubagentConversation';
 import { eventSubagentSelection } from './eventSelection';
+import { resolveSubagentAgentId } from './identity';
 import { useAgentsMapContext } from '~/Providers';
 import { isLiveSubagentStatus } from './status';
 import { renderAgentAvatar } from '~/utils';
@@ -144,10 +145,14 @@ export default function SubagentThreadPanel({ selection }: { selection: ActiveSu
       selection.partIndex,
     ),
   );
+  const foregroundAgentId = resolveSubagentAgentId(progress, selection.subagentIdentity);
+  const foregroundAgent = foregroundAgentId == null ? undefined : agentsMap?.[foregroundAgentId];
   const foregroundTitle =
     selection.subagentType === 'self'
       ? localize('com_ui_subagent_dialog_title_self')
-      : localize('com_ui_subagent_dialog_title', { 0: selection.subagentType });
+      : localize('com_ui_subagent_dialog_title', {
+          0: foregroundAgent?.name || selection.subagentType,
+        });
   const threadId = selection.durable?.threadId ?? '';
   const taskId = selection.durable?.taskId ?? '';
   const controlIdentity = subagentControlStateKey(selection.parentConversationId, threadId, taskId);
@@ -838,7 +843,8 @@ export default function SubagentThreadPanel({ selection }: { selection: ActiveSu
   }, [agentsMap, eventSiblings, selection.event, threadId]);
   const selectedActorLabel =
     actorOptions.find((option) => option.value === threadId)?.label ?? panelTitle;
-  const selectedActorAgentId = selectedEventActor?.agentId ?? threadView?.agentId;
+  const selectedActorAgentId =
+    selectedEventActor?.agentId ?? threadView?.agentId ?? foregroundAgentId;
   const selectedActorIcon = renderAgentAvatar(
     selectedActorAgentId == null ? undefined : agentsMap?.[selectedActorAgentId],
     { size: 'icon', showBorder: false },

client/src/components/Chat/Subagents/identity.test.ts

@@ -0,0 +1,15 @@
+import { resolveSubagentAgentId } from './identity';
+
+describe('resolveSubagentAgentId', () => {
+  const agent = { subagentKind: 'agent' as const, subagentAgentId: 'agent-1' };
+  const graph = { subagentKind: 'graph' as const, subagentAgentId: 'agent-1' };
+  it('prefers live identity and falls back to explicit saved identity', () => {
+    expect(resolveSubagentAgentId({ ...agent, subagentAgentId: 'agent-2' }, agent)).toBe('agent-2');
+    expect(resolveSubagentAgentId(null, agent)).toBe('agent-1');
+    expect(resolveSubagentAgentId(null, undefined)).toBeUndefined();
+  });
+  it('never resolves a graph as a saved agent even when their IDs collide', () => {
+    expect(resolveSubagentAgentId(graph, agent)).toBeUndefined();
+    expect(resolveSubagentAgentId(null, graph)).toBeUndefined();
+  });
+});

client/src/components/Chat/Subagents/identity.ts

@@ -0,0 +1,10 @@
+import type { SubagentIdentity } from 'librechat-data-provider';
+
+export function resolveSubagentAgentId(
+  progress: Partial<SubagentIdentity> | null | undefined,
+  persisted: SubagentIdentity | undefined,
+): string | undefined {
+  if (progress?.subagentKind === 'graph') return undefined;
+  if (progress?.subagentAgentId) return progress.subagentAgentId;
+  return persisted?.subagentKind === 'agent' ? persisted.subagentAgentId : undefined;
+}