Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪆 feat: Subagent configuration in Agent Builder (#12725)
Danny Avilad83cb84f599b
diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.jsindex 160df4ea95..c54293f9f6 100644--- a/api/server/controllers/agents/callbacks.js+++ b/api/server/controllers/agents/callbacks.js@@ -6,6 +6,7 @@ const {GraphNodeKeys,ToolEndHandler,CODE_EXECUTION_TOOLS,+ createContentAggregator,} = require('@librechat/agents');const {sendEvent,@@ -114,6 +115,48 @@ async function emitEvent(res, streamId, eventData) {}}+/**+ * Maps a {@link SubagentUpdateEvent} phase to the corresponding+ * {@link GraphEvents} name that the SDK's `createContentAggregator`+ * knows how to consume. Phases that don't carry content (`start`, `stop`,+ * `error`) or whose payload doesn't match a handled event (`run_step`+ * with an `ON_TOOL_EXECUTE`-shaped batch request rather than a RunStep)+ * return `null` so the caller skips them.+ * @param {SubagentUpdateEvent} event+ * @returns {string | null}+ */+function subagentPhaseToGraphEvent(event) {+ switch (event?.phase) {+ case 'run_step':+ /** `ON_RUN_STEP` and `ON_TOOL_EXECUTE` both forward with phase+ * `run_step`; only the former matches the aggregator's RunStep+ * schema. Detect by presence of `stepDetails`. */+ return event.data?.stepDetails ? GraphEvents.ON_RUN_STEP : null;+ case 'run_step_delta':+ return GraphEvents.ON_RUN_STEP_DELTA;+ case 'run_step_completed':+ return GraphEvents.ON_RUN_STEP_COMPLETED;+ case 'message_delta':+ return GraphEvents.ON_MESSAGE_DELTA;+ case 'reasoning_delta':+ return GraphEvents.ON_REASONING_DELTA;+ default:+ return null;+ }+}++/**+ * Folds a single {@link SubagentUpdateEvent} into the given content+ * aggregator. Silent no-op for phases outside the aggregator's domain.+ * @param {{ aggregateContent: Function }} aggregator+ * @param {SubagentUpdateEvent} event+ */+function feedSubagentAggregator(aggregator, event) {+ const graphEvent = subagentPhaseToGraphEvent(event);+ if (!graphEvent) return;+ aggregator.aggregateContent({ event: graphEvent, data: event.data });+}+/*** @typedef {Object} ToolExecuteOptions* @property {(toolNames: string[]) => Promise<{loadedTools: StructuredTool[]}>} loadTools - Function to load tools by name@@ -140,6 +183,7 @@ function getDefaultHandlers({streamId = null,toolExecuteOptions = null,summarizationOptions = null,+ subagentAggregatorsByToolCallId = null,}) {if (!res || !aggregateContent) {throw new Error(@@ -252,6 +296,55 @@ function getDefaultHandlers({handlers[GraphEvents.ON_TOOL_EXECUTE] = createToolExecuteHandler(toolExecuteOptions);}+ handlers[GraphEvents.ON_SUBAGENT_UPDATE] = {+ /**+ * Forwards subagent progress envelopes to the client stream, and+ * (when a caller-owned aggregator map is provided) also folds each+ * event into a per-tool-call `createContentAggregator`. The+ * resulting `contentParts` are attached to the parent's `subagent`+ * tool_call at message-save time so the child's reasoning / tool+ * calls / final text survive a page refresh — in-memory Recoil+ * atoms alone wouldn't persist that.+ *+ * Aggregation runs regardless of stream visibility (persistence ++ * dialog depend on it), but the SSE forward respects+ * `hide_sequential_outputs` the same way `ON_RUN_STEP`,+ * `ON_MESSAGE_DELTA`, etc. do — so intermediate agents in a+ * sequential chain don't leak their subagent activity when the+ * chain is configured to suppress intermediates.+ */+ handle: async (event, data, metadata) => {+ const isLastAgent = checkIfLastAgent(metadata?.last_agent_id, metadata?.langgraph_node);+ const visible = isLastAgent || !metadata?.hide_sequential_outputs;+ /**+ * Gate BOTH aggregation (persistence) AND streaming on the same+ * visibility rule. If we aggregated for a hidden intermediate+ * agent, `finalizeSubagentContent` would still attach its+ * child's reasoning / tool output to the saved message — so a+ * page refresh would reveal activity that was intentionally+ * suppressed live. Treat hide_sequential_outputs as a+ * consistent "don't record" rule for subagent traces.+ */+ if (!visible) return;+ if (subagentAggregatorsByToolCallId && data?.parentToolCallId) {+ const key = data.parentToolCallId;+ let aggregator = subagentAggregatorsByToolCallId.get(key);+ if (!aggregator) {+ aggregator = createContentAggregator();+ subagentAggregatorsByToolCallId.set(key, aggregator);+ }+ try {+ feedSubagentAggregator(aggregator, data);+ } catch (err) {+ logger.warn(+ `[ON_SUBAGENT_UPDATE] Failed to aggregate phase "${data?.phase}" for tool_call ${key}: ${err?.message ?? err}`,+ );+ }+ }+ await emitEvent(res, streamId, { event, data });+ },+ };+if (summarizationOptions?.enabled !== false) {handlers[GraphEvents.ON_SUMMARIZE_START] = {handle: async (_event, data) => {diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex cf48a8d87b..7d59bd7bec 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -82,6 +82,7 @@ class AgentClient extends BaseClient {collectedUsage,artifactPromises,maxContextTokens,+ subagentAggregatorsByToolCallId,...clientOptions} = options;@@ -93,6 +94,12 @@ class AgentClient extends BaseClient {this.collectedUsage = collectedUsage;/** @type {ArtifactPromises} */this.artifactPromises = artifactPromises;+ /** Per-request map of `createContentAggregator` instances keyed by+ * the parent's `tool_call_id`. `ON_SUBAGENT_UPDATE` events stream+ * into each aggregator as they arrive; `finalizeSubagentContent`+ * harvests `contentParts` onto the matching `subagent` tool_call+ * so the child's full activity survives a page refresh. */+ this.subagentAggregatorsByToolCallId = subagentAggregatorsByToolCallId ?? new Map();/** @type {AgentClientOptions} */this.options = Object.assign({ endpoint: options.endpoint }, clientOptions);/** @type {string} */@@ -118,6 +125,45 @@ class AgentClient extends BaseClient {return this.contentParts;}+ /**+ * Harvest the `contentParts` from each per-subagent `createContentAggregator`+ * instance and attach them onto the matching parent `subagent` tool_call+ * as `subagent_content`. Runs once per message save (from+ * `sendCompletion`'s `finally`) so the child's full reasoning / tool+ * calls / final text survive a page refresh — the client-side Recoil+ * atom is session-only. Aggregators keyed by a tool_call_id that never+ * appeared in `contentParts` are discarded (no home to attach to).+ */+ finalizeSubagentContent() {+ const buffer = this.subagentAggregatorsByToolCallId;+ if (!buffer || buffer.size === 0 || !Array.isArray(this.contentParts)) {+ return;+ }+ for (const part of this.contentParts) {+ if (part?.type !== ContentTypes.TOOL_CALL) continue;+ const toolCall = part[ContentTypes.TOOL_CALL];+ if (!toolCall || toolCall.name !== Constants.SUBAGENT || !toolCall.id) continue;+ const aggregator = buffer.get(toolCall.id);+ if (!aggregator) continue;+ try {+ /** `createContentAggregator` returns a sparse array (undefined+ * slots for indices that never received content). Strip those+ * so the persisted shape is a clean `TMessageContentParts[]`. */+ const parts = Array.isArray(aggregator.contentParts)+ ? aggregator.contentParts.filter((p) => p != null)+ : [];+ if (parts.length > 0) {+ toolCall.subagent_content = parts;+ }+ } catch (err) {+ logger.warn(+ `[AgentClient] Failed to attach subagent content for tool_call ${toolCall.id}: ${err?.message ?? err}`,+ );+ }+ }+ buffer.clear();+ }+setOptions(_options) {}/**@@ -1017,6 +1063,8 @@ class AgentClient extends BaseClient {this.contextMeta = undefined;}+ this.finalizeSubagentContent();+try {const attachments = await this.awaitMemoryWithTimeout(memoryPromise);if (attachments && attachments.length > 0) {diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.jsindex 1595f652f7..69c90689ef 100644--- a/api/server/controllers/agents/client.test.js+++ b/api/server/controllers/agents/client.test.js@@ -2265,3 +2265,247 @@ describe('AgentClient - titleConvo', () => {});});});++describe('AgentClient - finalizeSubagentContent', () => {+ /** Verifies the backend persistence path: per-subagent+ * `createContentAggregator` instances (populated by the callbacks+ * ON_SUBAGENT_UPDATE handler) have their `contentParts` harvested+ * onto the matching parent `subagent` tool_call at message-save time+ * so a page refresh shows the same activity the user saw live. */+ const { createContentAggregator, GraphEvents } = jest.requireActual('@librechat/agents');+ const { getDefaultHandlers } = require('./callbacks');++ const makeClient = (subagentAggregatorsByToolCallId) => {+ const client = new AgentClient({+ req: { user: { id: 'u' }, body: {}, config: { endpoints: {} } },+ res: {},+ agent: {+ id: 'agent',+ endpoint: EModelEndpoint.openAI,+ provider: EModelEndpoint.openAI,+ model_parameters: { model: 'gpt-4' },+ },+ contentParts: [],+ subagentAggregatorsByToolCallId,+ });+ return client;+ };++ const event = (phase, data, parentToolCallId = 'call_sub') => ({+ runId: 'parent-run',+ subagentRunId: 'child-run',+ subagentType: 'self',+ subagentAgentId: 'child',+ parentToolCallId,+ phase,+ data,+ timestamp: '2026-04-17T00:00:00Z',+ });++ /** Feeds a SubagentUpdateEvent sequence through the real+ * `ON_SUBAGENT_UPDATE` handler so we exercise the same get-or-create+ * aggregator logic the live request uses, rather than constructing+ * aggregators directly in the test. */+ const runSubagentEvents = async (events) => {+ const map = new Map();+ const handlers = getDefaultHandlers({+ res: { write: jest.fn(), writableEnded: false },+ aggregateContent: jest.fn(),+ toolEndCallback: jest.fn(),+ collectedUsage: [],+ subagentAggregatorsByToolCallId: map,+ });+ const handler = handlers[GraphEvents.ON_SUBAGENT_UPDATE];+ for (const e of events) {+ await handler.handle(GraphEvents.ON_SUBAGENT_UPDATE, e);+ }+ return map;+ };++ it('attaches aggregated subagent_content to the matching subagent tool_call part', async () => {+ const buffer = await runSubagentEvents([+ event('run_step', {+ id: 'step_msg',+ index: 0,+ stepDetails: { type: 'message_creation' },+ }),+ event('message_delta', {+ id: 'step_msg',+ delta: { content: [{ type: 'text', text: 'Hello ' }] },+ }),+ event('message_delta', {+ id: 'step_msg',+ delta: { content: [{ type: 'text', text: 'world!' }] },+ }),+ event('run_step', {+ id: 'step_tool',+ index: 1,+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'inner_1', name: 'calculator', args: '{}' }],+ },+ }),+ event('run_step_completed', {+ id: 'step_tool',+ index: 1,+ result: {+ id: 'step_tool',+ type: 'tool_call',+ tool_call: {+ id: 'inner_1',+ name: 'calculator',+ output: '4',+ progress: 1,+ },+ },+ }),+ ]);++ const client = makeClient(buffer);+ client.contentParts = [+ {+ type: 'tool_call',+ tool_call: {+ id: 'call_sub',+ name: Constants.SUBAGENT,+ args: '{}',+ output: 'final text',+ progress: 1,+ },+ },+ ];++ client.finalizeSubagentContent();++ const attached = client.contentParts[0].tool_call.subagent_content;+ expect(Array.isArray(attached)).toBe(true);+ expect(attached).toHaveLength(2);+ expect(attached[0].type).toBe('text');+ expect(attached[0].text).toBe('Hello world!');+ expect(attached[1].type).toBe('tool_call');+ expect(attached[1].tool_call.name).toBe('calculator');+ expect(attached[1].tool_call.output).toBe('4');+ /** Buffer drained so a second call (e.g. resumable retry) doesn't+ * double-append. */+ expect(buffer.size).toBe(0);+ });++ it('ignores tool_call parts whose name is not SUBAGENT', async () => {+ const buffer = await runSubagentEvents([+ event(+ 'run_step',+ {+ id: 'step_msg',+ index: 0,+ stepDetails: { type: 'message_creation' },+ },+ 'call_regular',+ ),+ event(+ 'message_delta',+ {+ id: 'step_msg',+ delta: { content: [{ type: 'text', text: 'x' }] },+ },+ 'call_regular',+ ),+ ]);+ const client = makeClient(buffer);+ client.contentParts = [+ {+ type: 'tool_call',+ tool_call: { id: 'call_regular', name: 'calculator', args: '{}' },+ },+ ];+ client.finalizeSubagentContent();+ expect(client.contentParts[0].tool_call.subagent_content).toBeUndefined();+ });++ it('is a safe no-op when the aggregator map is empty or missing', () => {+ const client = makeClient(undefined);+ client.contentParts = [+ {+ type: 'tool_call',+ tool_call: { id: 'call_sub', name: Constants.SUBAGENT, args: '{}' },+ },+ ];+ expect(() => client.finalizeSubagentContent()).not.toThrow();+ expect(client.contentParts[0].tool_call.subagent_content).toBeUndefined();+ });++ it('discards aggregators keyed by a tool_call_id not present in contentParts', async () => {+ const buffer = await runSubagentEvents([+ event(+ 'run_step',+ {+ id: 'step_msg',+ index: 0,+ stepDetails: { type: 'message_creation' },+ },+ 'call_missing',+ ),+ event(+ 'message_delta',+ {+ id: 'step_msg',+ delta: { content: [{ type: 'text', text: 'x' }] },+ },+ 'call_missing',+ ),+ ]);+ const client = makeClient(buffer);+ client.contentParts = [+ {+ type: 'tool_call',+ tool_call: { id: 'call_other', name: Constants.SUBAGENT, args: '{}' },+ },+ ];+ client.finalizeSubagentContent();+ expect(client.contentParts[0].tool_call.subagent_content).toBeUndefined();+ });++ it('keeps per-parent tool_call aggregators isolated for parallel subagents', async () => {+ const buffer = await runSubagentEvents([+ event(+ 'run_step',+ {+ id: 'step_a',+ index: 0,+ stepDetails: { type: 'message_creation' },+ },+ 'call_a',+ ),+ event(+ 'message_delta',+ { id: 'step_a', delta: { content: [{ type: 'text', text: 'A' }] } },+ 'call_a',+ ),+ event(+ 'run_step',+ {+ id: 'step_b',+ index: 0,+ stepDetails: { type: 'message_creation' },+ },+ 'call_b',+ ),+ event(+ 'message_delta',+ { id: 'step_b', delta: { content: [{ type: 'text', text: 'B' }] } },+ 'call_b',+ ),+ ]);+ const client = makeClient(buffer);+ client.contentParts = [+ { type: 'tool_call', tool_call: { id: 'call_a', name: Constants.SUBAGENT, args: '{}' } },+ { type: 'tool_call', tool_call: { id: 'call_b', name: Constants.SUBAGENT, args: '{}' } },+ ];+ client.finalizeSubagentContent();+ expect(client.contentParts[0].tool_call.subagent_content).toEqual([+ expect.objectContaining({ type: 'text', text: 'A' }),+ ]);+ expect(client.contentParts[1].tool_call.subagent_content).toEqual([+ expect.objectContaining({ type: 'text', text: 'B' }),+ ]);+ });+});diff --git a/api/server/controllers/agents/v1.js b/api/server/controllers/agents/v1.jsindex 5bddb9aac3..23c8341839 100644--- a/api/server/controllers/agents/v1.js+++ b/api/server/controllers/agents/v1.js@@ -26,6 +26,8 @@ const {EToolResources,PermissionBits,actionDelimiter,+ AgentCapabilities,+ EModelEndpoint,removeNullishValues,} = require('librechat-data-provider');const {@@ -55,25 +57,28 @@ const MAX_SEARCH_LEN = 100;const escapeRegex = (str = '') => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');/**- * Validates that the requesting user has VIEW access to every agent referenced in edges.- * Agents that do not exist in the database are skipped — at create time, the `from` field- * often references the agent being built, which has no DB record yet.- * @param {import('librechat-data-provider').GraphEdge[]} edges+ * Looks up each referenced agent id in Mongo, splits them into three+ * buckets the caller needs for validation: ids that don't exist at all,+ * ids the user lacks VIEW permission on, and ids that are fully+ * accessible. Missing ids are intentionally NOT treated as unauthorized+ * — for `edges`, a self-referential `from` can legitimately name the+ * agent being created (no DB record yet); callers that should reject+ * missing ids (like the subagent path) read the `missing` bucket+ * instead.+ * @param {Iterable<string>} agentIds* @param {string} userId- * @param {string} userRole - Used for group/role principal resolution- * @returns {Promise<string[]>} Agent IDs the user cannot VIEW (empty if all accessible)+ * @param {string} userRole+ * @returns {Promise<{ missing: string[], unauthorized: string[] }>}*/-const validateEdgeAgentAccess = async (edges, userId, userRole) => {- const edgeAgentIds = collectEdgeAgentIds(edges);- if (edgeAgentIds.size === 0) {- return [];- }+const classifyAgentReferences = async (agentIds, userId, userRole) => {+ const ids = [...new Set(agentIds)];+ if (ids.length === 0) return { missing: [], unauthorized: [] };- const agents = await db.getAgents({ id: { $in: [...edgeAgentIds] } });+ const agents = await db.getAgents({ id: { $in: ids } });+ const foundIds = new Set(agents.map((a) => a.id));+ const missing = ids.filter((id) => !foundIds.has(id));- if (agents.length === 0) {- return [];- }+ if (agents.length === 0) return { missing, unauthorized: [] };const permissionsMap = await getResourcePermissionsMap({userId,@@ -82,12 +87,57 @@ const validateEdgeAgentAccess = async (edges, userId, userRole) => {resourceIds: agents.map((a) => a._id),});- return agents+ const unauthorized = agents.filter((a) => {const bits = permissionsMap.get(a._id.toString()) ?? 0;return (bits & PermissionBits.VIEW) === 0;}).map((a) => a.id);++ return { missing, unauthorized };+};++/**+ * Validates VIEW access for every agent referenced in `edges`.+ * Missing ids are NOT errors here — at create time a self-referential+ * `from` often names the agent being built, which has no DB record+ * yet. Only unauthorized (existing but unviewable) ids are returned.+ */+const validateEdgeAgentAccess = async (edges, userId, userRole) => {+ const { unauthorized } = await classifyAgentReferences(+ collectEdgeAgentIds(edges),+ userId,+ userRole,+ );+ return unauthorized;+};++/**+ * Validates `subagents.agent_ids` more strictly than edges: both+ * missing AND unauthorized ids are errors. `subagents.agent_ids`+ * can't self-reference (subagents spawn *other* agents), so a+ * missing id is always a typo or a reference to a deleted agent —+ * `initializeClient` would silently drop it at runtime, leaving the+ * persisted config out of sync with actual spawn targets (Codex P2).+ * Returning the split lets the caller report each bucket with the+ * appropriate status.+ */+const validateSubagentReferences = (subagents, userId, userRole) =>+ classifyAgentReferences(subagents?.agent_ids ?? [], userId, userRole);++/**+ * Returns true when the agents-endpoint `subagents` capability is+ * enabled in this request's resolved app config. When disabled,+ * `initializeClient` already strips the `subagents` block at runtime+ * so persisted `agent_ids` are inert — gating the ACL check on this+ * keeps stale references in legacy records from blocking unrelated+ * edits after a capability-off rollback (Codex P2).+ * @param {Express.Request} req+ */+const isSubagentsCapabilityEnabled = (req) => {+ const capabilities = req.config?.endpoints?.[EModelEndpoint.agents]?.capabilities;+ if (!Array.isArray(capabilities)) return false;+ return capabilities.includes(AgentCapabilities.subagents);};/**@@ -199,6 +249,44 @@ const createAgentHandler = async (req, res) => {}}+ /**+ * Only validate subagent ACL when the feature is actually enabled+ * on BOTH the endpoint (capability flag in appConfig) AND the+ * agent payload. Runtime (`initializeClient` + `run.ts`) checks+ * `subagents?.enabled` as a truthy predicate — so `undefined` /+ * `null` / missing `enabled` all disable the feature. The ACL+ * check must match exactly: only enforce when `enabled === true`.+ * Otherwise a payload that omits `enabled` (e.g. API clients, or+ * legacy records that never set the field) could 403 here while+ * runtime would happily no-op on the subagent tool. Disable-path+ * is also untouched: toggling `enabled: false` always passes the+ * gate, so a user who lost VIEW on a child can still save the+ * disable edit.+ */+ if (+ isSubagentsCapabilityEnabled(req) &&+ agentData.subagents?.enabled === true &&+ agentData.subagents?.agent_ids?.length+ ) {+ const { missing, unauthorized } = await validateSubagentReferences(+ agentData.subagents,+ userId,+ userRole,+ );+ if (missing.length > 0) {+ return res.status(400).json({+ error: 'One or more agents referenced in subagents do not exist',+ agent_ids: missing,+ });+ }+ if (unauthorized.length > 0) {+ return res.status(403).json({+ error: 'You do not have access to one or more agents referenced in subagents',+ agent_ids: unauthorized,+ });+ }+ }+agentData.id = `agent_${nanoid()}`;agentData.author = userId;agentData.tools = [];@@ -371,6 +459,38 @@ const updateAgentHandler = async (req, res) => {}}+ /** Same guard as the create path: capability on the endpoint,+ * AND `subagents.enabled === true` on the payload (runtime's+ * truthy check treats `undefined` / `null` / `false` as+ * disabled, so the ACL check must too). Missing or explicitly-+ * disabled payloads always pass the gate — that preserves the+ * "can always save a disable edit" behavior a user might need+ * after losing VIEW on a referenced child. */+ if (+ isSubagentsCapabilityEnabled(req) &&+ updateData.subagents?.enabled === true &&+ updateData.subagents?.agent_ids?.length+ ) {+ const { id: userId, role: userRole } = req.user;+ const { missing, unauthorized } = await validateSubagentReferences(+ updateData.subagents,+ userId,+ userRole,+ );+ if (missing.length > 0) {+ return res.status(400).json({+ error: 'One or more agents referenced in subagents do not exist',+ agent_ids: missing,+ });+ }+ if (unauthorized.length > 0) {+ return res.status(403).json({+ error: 'You do not have access to one or more agents referenced in subagents',+ agent_ids: unauthorized,+ });+ }+ }+// Convert OCR to context in incoming updateDataconvertOcrToContextInPlace(updateData);diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.jsindex 3baf6b8554..367a8adb45 100644--- a/api/server/services/Endpoints/agents/initialize.js+++ b/api/server/services/Endpoints/agents/initialize.js@@ -192,6 +192,18 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {const summarizationOptions =appConfig?.summarization?.enabled === false ? { enabled: false } : { enabled: true };+ /**+ * Per-request map of per-subagent `createContentAggregator` instances+ * keyed by the parent's `tool_call_id`. The handler in `callbacks.js`+ * lazily creates an aggregator for each distinct `parentToolCallId`+ * and folds every `ON_SUBAGENT_UPDATE` event into it as they stream+ * in. `AgentClient` pulls each aggregator's `contentParts` at message+ * save time and attaches them to the matching `subagent` tool_call so+ * the child's reasoning / tool calls / final text survive a page+ * refresh — the client-side Recoil atom is best-effort live-only.+ */+ const subagentAggregatorsByToolCallId = new Map();+const eventHandlers = getDefaultHandlers({res,toolExecuteOptions,@@ -200,6 +212,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {toolEndCallback,collectedUsage,streamId,+ subagentAggregatorsByToolCallId,});if (!endpointOption.agent) {@@ -312,6 +325,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {agentConfigs: discoveredConfigs,edges: discoveredEdges,userMCPAuthMap: discoveredMCPAuthMap,+ skippedAgentIds: discoveredSkippedIds,} = await discoverConnectedAgents({req,@@ -438,6 +452,262 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {// further normalization is needed before handing this to `createRun`.primaryConfig.edges = edges;+ // Subagents: load any explicit subagent configs. Subagents run in isolated+ // context windows and are invoked via a dedicated spawn tool (not handoff+ // edges). An agent that is ONLY referenced as a subagent is dropped from+ // `agentConfigs` so the LangGraph pipeline doesn't treat it as a+ // parallel/handoff node, but it is KEPT in `agentToolContexts` — the child's+ // `ON_TOOL_EXECUTE` dispatches resolve tool execution context (agent,+ // tool_resources, skill ACLs, ...) from that map, so removing it would leave+ // action tools skipped and resource-scoped tools running without their+ // configured resources.+ const subagentsCapabilityEnabled = enabledCapabilities.has(AgentCapabilities.subagents);+ /** Track skipped ids locally so repeated failures short-circuit within+ * the subagent loading loop. Seeded from the discovery helper's skip+ * list so agents that already failed handoff loading don't get retried. */+ const skippedAgentIds = new Set(discoveredSkippedIds ?? []);++ /** All agent ids referenced on any edge (source OR target). Used by+ * `loadSubagentsFor` to decide whether an agent that's only a subagent+ * can be safely dropped from `agentConfigs` — LangGraph doesn't treat+ * pure subagents as parallel/handoff nodes. */+ const edgeAgentIds = new Set([primaryConfig.id]);+ for (const edge of edges ?? []) {+ const sources = Array.isArray(edge.from) ? edge.from : [edge.from];+ const targets = Array.isArray(edge.to) ? edge.to : [edge.to];+ for (const id of sources) {+ if (typeof id === 'string') edgeAgentIds.add(id);+ }+ for (const id of targets) {+ if (typeof id === 'string') edgeAgentIds.add(id);+ }+ }++ /** Lazy per-id agent loader used for subagents that weren't reachable+ * via the handoff edge graph (so `discoverConnectedAgents` didn't+ * initialize them). Mirrors the helper's internal `processAgent`:+ * DB lookup + VIEW check + `initializeAgent`, then inserts into+ * `agentConfigs` and `agentToolContexts`. Returns `null` on any+ * failure so the caller can skip gracefully. */+ const loadAgentById = async (agentId) => {+ if (skippedAgentIds.has(agentId)) return null;+ const existing = agentConfigs.get(agentId);+ if (existing) return existing;++ try {+ const agent = await db.getAgent({ id: agentId });+ if (!agent) {+ skippedAgentIds.add(agentId);+ return null;+ }+ const userId = req.user?.id;+ if (!userId) {+ skippedAgentIds.add(agentId);+ return null;+ }+ const hasAccess = await checkPermission({+ userId,+ role: req.user?.role,+ resourceType: ResourceType.AGENT,+ resourceId: agent._id,+ requiredPermission: PermissionBits.VIEW,+ });+ if (!hasAccess) {+ logger.warn(+ `[processAgent] User ${userId} lacks VIEW access to subagent ${agentId}, skipping`,+ );+ skippedAgentIds.add(agentId);+ return null;+ }+ const validation = await validateAgentModel({+ req,+ res,+ agent,+ modelsConfig,+ logViolation,+ });+ if (!validation.isValid) {+ logger.warn(+ `[processAgent] Subagent ${agentId} failed model validation: ${validation.error?.message}`,+ );+ skippedAgentIds.add(agentId);+ return null;+ }+ const config = await initializeAgent(+ {+ req,+ res,+ agent,+ loadTools,+ requestFiles,+ conversationId,+ parentMessageId,+ endpointOption: { ...endpointOption, endpoint: EModelEndpoint.agents },+ allowedProviders,+ accessibleSkillIds: scopeSkillIds(+ accessibleSkillIds,+ ephemeralSkillsToggle ? undefined : agent.skills,+ ),+ skillStates,+ defaultActiveOnShare,+ },+ {+ getAgent: db.getAgent,+ checkPermission,+ logViolation,+ db: {+ getFiles: db.getFiles,+ getUserKey: db.getUserKey,+ getMessages: db.getMessages,+ getConvoFiles: db.getConvoFiles,+ updateFilesUsage: db.updateFilesUsage,+ getUserKeyValues: db.getUserKeyValues,+ getUserCodeFiles: db.getUserCodeFiles,+ getToolFilesByIds: db.getToolFilesByIds,+ getCodeGeneratedFiles: db.getCodeGeneratedFiles,+ filterFilesByAgentAccess,+ listSkillsByAccess: db.listSkillsByAccess,+ listAlwaysApplySkills: db.listAlwaysApplySkills,+ getSkillByName: db.getSkillByName,+ },+ },+ );+ agentConfigs.set(agentId, config);+ agentToolContexts.set(agentId, {+ agent,+ toolRegistry: config.toolRegistry,+ userMCPAuthMap: config.userMCPAuthMap,+ tool_resources: config.tool_resources,+ actionsEnabled: config.actionsEnabled,+ accessibleSkillIds: config.accessibleSkillIds,+ skillPrimedIdsByName: buildSkillPrimedIdsByName(+ config.manualSkillPrimes,+ config.alwaysApplySkillPrimes,+ ),+ });+ return config;+ } catch (err) {+ logger.error(`[processAgent] Error processing subagent ${agentId}:`, err);+ skippedAgentIds.add(agentId);+ return null;+ }+ };++ /** Collected during resolution; applied to `agentConfigs` only after+ * every config has had its subagents resolved. Eager pruning would+ * hide pure-subagent ids from the subsequent `loadSubagentsFor`+ * loop, which would leave *their* `subagentAgentConfigs` empty and+ * silently break nested delegation like A → B → C where B is only+ * a subagent of A. */+ const pureSubagentIds = new Set();++ /**+ * Loads `subagentAgentConfigs` for a single agent config. Shared+ * between the primary agent and handoff-target agents (and pure+ * subagents, transitively) so an agent used via handoff or+ * nested-subagent that has its own explicit `subagents.agent_ids`+ * gets them honored at runtime. Self-spawn works regardless (no DB+ * lookup needed). Pruning decisions are deferred to `pureSubagentIds`.+ */+ const loadSubagentsFor = async (config) => {+ const sub = config.subagents;+ if (!subagentsCapabilityEnabled || !sub?.enabled) {+ config.subagentAgentConfigs = [];+ return;+ }++ /** Dedupe and filter in one pass — a crafted payload could+ * legitimately include the same ID twice; the backend shouldn't+ * create duplicate SubagentConfig entries for the LLM to see as+ * separate spawn targets. */+ const explicitSubagentIds = Array.from(+ new Set(+ Array.isArray(sub.agent_ids)+ ? sub.agent_ids.filter((id) => typeof id === 'string' && id && id !== config.id)+ : [],+ ),+ );++ /** @type {Array<Object>} */+ const resolved = [];+ for (const subagentId of explicitSubagentIds) {+ if (skippedAgentIds.has(subagentId)) continue;++ /** Cycle guard: a configuration like A ↔ B (B lists A as its+ * subagent) would otherwise trigger `loadAgentById` on the+ * primary — inserting a second config for the same primary id,+ * which downstream duplicates in the agent array. Reuse the+ * existing primary config when a subagent ref points back at it. */+ if (subagentId === primaryConfig.id) {+ resolved.push(primaryConfig);+ continue;+ }++ const subagentConfig = await loadAgentById(subagentId);+ if (!subagentConfig) continue;++ resolved.push(subagentConfig);++ if (!edgeAgentIds.has(subagentId)) {+ pureSubagentIds.add(subagentId);+ }+ }++ config.subagentAgentConfigs = resolved;+ };++ /** BFS across the primary's subagent tree so nested chains like+ * A → B → C get resolved before any pruning. Each config is+ * visited once. */+ const visitedConfigIds = new Set();+ const pending = [primaryConfig];+ while (pending.length > 0) {+ const cfg = pending.shift();+ if (!cfg || visitedConfigIds.has(cfg.id)) continue;+ visitedConfigIds.add(cfg.id);+ await loadSubagentsFor(cfg);+ for (const child of cfg.subagentAgentConfigs ?? []) {+ if (child?.id && !visitedConfigIds.has(child.id)) {+ pending.push(child);+ }+ }+ }+ /** Handoff targets still in the map that weren't visited via the+ * primary's subagent tree also need their subagents resolved. */+ for (const [id, cfg] of agentConfigs.entries()) {+ if (id === primaryConfig.id || visitedConfigIds.has(id)) continue;+ visitedConfigIds.add(id);+ await loadSubagentsFor(cfg);+ for (const child of cfg.subagentAgentConfigs ?? []) {+ if (child?.id && !visitedConfigIds.has(child.id)) {+ visitedConfigIds.add(child.id);+ await loadSubagentsFor(child);+ }+ }+ }++ /** Drop pure-subagent entries now that every reachable config has+ * had its subagents resolved. They stay in `agentToolContexts` so+ * their tools still execute with the right scoping. */+ for (const id of pureSubagentIds) {+ agentConfigs.delete(id);+ }++ primaryConfig.subagents = subagentsCapabilityEnabled ? primaryConfig.subagents : undefined;++ /** If the capability is off at the endpoint level, strip `subagents` on+ * every loaded config — not just the primary. `run.ts` calls+ * `buildSubagentConfigs` for every agent in the array, so a handoff+ * agent with `subagents.enabled: true` persisted on its document would+ * otherwise still expose self-spawn at runtime even though the admin+ * has disabled the capability globally. */+ if (!subagentsCapabilityEnabled) {+ for (const config of agentConfigs.values()) {+ config.subagents = undefined;+ config.subagentAgentConfigs = undefined;+ }+ }+let endpointConfig = appConfig.endpoints?.[primaryConfig.endpoint];if (!isAgentsEndpoint(primaryConfig.endpoint) && !endpointConfig) {try {@@ -497,6 +767,7 @@ const initializeClient = async ({ req, res, signal, endpointOption }) => {resendFiles: primaryConfig.resendFiles ?? true,maxContextTokens: primaryConfig.maxContextTokens,endpoint: isEphemeralAgentId(primaryConfig.id) ? primaryConfig.endpoint : EModelEndpoint.agents,+ subagentAggregatorsByToolCallId,});if (streamId) {diff --git a/api/server/services/Endpoints/agents/initialize.spec.js b/api/server/services/Endpoints/agents/initialize.spec.jsindex 8027744965..ca44be8122 100644--- a/api/server/services/Endpoints/agents/initialize.spec.js+++ b/api/server/services/Endpoints/agents/initialize.spec.js@@ -27,14 +27,22 @@ jest.mock('@librechat/api', () => ({createSequentialChainEdges: jest.fn(),}));+/** Captured by the `getDefaultHandlers` mock so tests can drive the+ * `ON_TOOL_EXECUTE` pipeline with a real subagent id and observe whether+ * the tool context (agent, tool_resources, skill ACLs) was preserved. */+let capturedToolExecuteOptions;jest.mock('~/server/controllers/agents/callbacks', () => ({createToolEndCallback: jest.fn(() => jest.fn()),- getDefaultHandlers: jest.fn(() => ({})),+ getDefaultHandlers: jest.fn((opts) => {+ capturedToolExecuteOptions = opts?.toolExecuteOptions;+ return {};+ }),}));+const mockLoadToolsForExecution = jest.fn();jest.mock('~/server/services/ToolService', () => ({loadAgentTools: jest.fn(),- loadToolsForExecution: jest.fn(),+ loadToolsForExecution: (...args) => mockLoadToolsForExecution(...args),}));jest.mock('~/server/controllers/ModelController', () => ({@@ -199,3 +207,384 @@ describe('initializeClient — processAgent ACL gate', () => {expect(agentClientArgs.agent.edges[0].to).toBe(AUTHORIZED_ID);});});++describe('initializeClient — subagent loading', () => {+ const SUBAGENT_ID = 'agent_subagent_1';+ const DUPLICATE_SUBAGENT_ID = 'agent_subagent_dup';+ const HANDOFF_AND_SUB_ID = 'agent_handoff_and_sub';++ let mongoServer;+ let testUser;++ beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+ });++ afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer.stop();+ });++ beforeEach(async () => {+ await mongoose.connection.dropDatabase();+ jest.clearAllMocks();+ agentClientArgs = undefined;+ capturedToolExecuteOptions = undefined;+ mockLoadToolsForExecution.mockReset();+ mockLoadToolsForExecution.mockResolvedValue({ loadedTools: [] });++ testUser = await User.create({+ email: '[email protected]',+ name: 'Subagent User',+ username: 'subuser',+ role: 'USER',+ });++ mockValidateAgentModel.mockResolvedValue({ isValid: true });+ });++ /** Grant the test user VIEW on an agent so processAgent loads it. */+ const grantView = async (agentDoc) => {+ await AclEntry.create({+ principalType: PrincipalType.USER,+ principalId: testUser._id,+ principalModel: PrincipalModel.USER,+ resourceType: ResourceType.AGENT,+ resourceId: agentDoc._id,+ permBits: PermissionBits.VIEW,+ grantedBy: testUser._id,+ });+ };++ /** Build a request with the `subagents` capability enabled. */+ const makeSubagentReq = () => ({+ user: { id: testUser._id.toString(), role: 'USER' },+ body: { conversationId: 'conv_sub', files: [] },+ config: {+ endpoints: {+ agents: {+ capabilities: ['subagents'],+ },+ },+ },+ _resumableStreamId: null,+ });++ const makeEndpointOption = () => ({+ agent: Promise.resolve({+ id: PRIMARY_ID,+ name: 'Primary',+ provider: 'openai',+ model: 'gpt-4',+ tools: [],+ }),+ model_parameters: { model: 'gpt-4' },+ endpoint: 'agents',+ });++ const makePrimaryConfig = ({ edges = [], subagents, agent_ids }) => ({+ id: PRIMARY_ID,+ endpoint: 'agents',+ edges,+ toolDefinitions: [],+ toolRegistry: new Map(),+ userMCPAuthMap: null,+ tool_resources: {},+ resendFiles: true,+ maxContextTokens: 4096,+ subagents,+ agent_ids,+ });++ const makeSubagentConfig = (id) => ({+ id,+ endpoint: 'agents',+ edges: [],+ toolDefinitions: [{ name: 'web', description: 'web', parameters: {} }],+ toolRegistry: new Map([['web', { name: 'web' }]]),+ userMCPAuthMap: null,+ tool_resources: { file_search: { file_ids: ['file_1'] } },+ accessibleSkillIds: ['skill_1'],+ actionsEnabled: true,+ resendFiles: false,+ maxContextTokens: 4096,+ });++ it('loads a configured subagent, populates `subagentAgentConfigs`, and keeps it out of `agentConfigs`', async () => {+ const subAgent = await createAgent({+ id: SUBAGENT_ID,+ name: 'Explicit Subagent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: ['web'],+ });+ await grantView(subAgent);++ const primaryConfig = makePrimaryConfig({+ subagents: { enabled: true, allowSelf: true, agent_ids: [SUBAGENT_ID] },+ });+ const subagentConfig = makeSubagentConfig(SUBAGENT_ID);++ let call = 0;+ mockInitializeAgent.mockImplementation(() =>+ Promise.resolve(++call === 1 ? primaryConfig : subagentConfig),+ );++ await initializeClient({+ req: makeSubagentReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ expect(mockInitializeAgent).toHaveBeenCalledTimes(2);++ /** The subagent's AgentConfig is attached to the primary for run.ts to+ * turn into `SubagentConfig[]` on the parent's `AgentInputs`. */+ expect(agentClientArgs.agent.subagentAgentConfigs).toHaveLength(1);+ expect(agentClientArgs.agent.subagentAgentConfigs[0].id).toBe(SUBAGENT_ID);++ /** Subagent-only agents must NOT appear in `agentConfigs` — otherwise the+ * graph would treat them as a parallel/handoff node. */+ expect(agentClientArgs.agentConfigs).toBeDefined();+ expect(agentClientArgs.agentConfigs.has(SUBAGENT_ID)).toBe(false);+ });++ it('preserves subagent tool context for ON_TOOL_EXECUTE (Codex P1 regression guard)', async () => {+ /** Verifies the Codex P1 fix: `agentToolContexts.delete(subagentId)` is+ * NOT called for subagent-only agents, so when the child dispatches+ * `ON_TOOL_EXECUTE` the parent can still resolve its tool context+ * (agent, tool_resources, skill ACLs, actionsEnabled) to run tools+ * with the right scope. We drive the real `loadTools` closure that+ * `initializeClient` wires into `toolExecuteOptions`. */+ const subAgent = await createAgent({+ id: SUBAGENT_ID,+ name: 'Explicit Subagent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: ['web'],+ });+ await grantView(subAgent);++ const primaryConfig = makePrimaryConfig({+ subagents: { enabled: true, allowSelf: false, agent_ids: [SUBAGENT_ID] },+ });+ const subagentConfig = makeSubagentConfig(SUBAGENT_ID);++ let call = 0;+ mockInitializeAgent.mockImplementation(() =>+ Promise.resolve(++call === 1 ? primaryConfig : subagentConfig),+ );++ await initializeClient({+ req: makeSubagentReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ expect(capturedToolExecuteOptions?.loadTools).toBeInstanceOf(Function);++ /** Invoke the real closure with the subagent's id. If `agentToolContexts`+ * had been deleted (as in the pre-fix code), this would call+ * `loadToolsForExecution` with `agent: undefined` — actions/resource-+ * scoped tools would silently drop. */+ await capturedToolExecuteOptions.loadTools(['web'], SUBAGENT_ID);++ expect(mockLoadToolsForExecution).toHaveBeenCalledTimes(1);+ const arg = mockLoadToolsForExecution.mock.calls[0][0];+ expect(arg.agent).toBeDefined();+ expect(arg.agent.id).toBe(SUBAGENT_ID);+ expect(arg.toolRegistry).toBeInstanceOf(Map);+ expect(arg.tool_resources).toEqual({ file_search: { file_ids: ['file_1'] } });+ expect(arg.actionsEnabled).toBe(true);+ });++ it('deduplicates repeated ids in subagents.agent_ids', async () => {+ const subAgent = await createAgent({+ id: DUPLICATE_SUBAGENT_ID,+ name: 'Dup Subagent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: [],+ });+ await grantView(subAgent);++ const primaryConfig = makePrimaryConfig({+ subagents: {+ enabled: true,+ allowSelf: false,+ /** Same id three times — the backend must not load the agent+ * repeatedly and must not emit three SubagentConfig entries. */+ agent_ids: [DUPLICATE_SUBAGENT_ID, DUPLICATE_SUBAGENT_ID, DUPLICATE_SUBAGENT_ID],+ },+ });+ const subagentConfig = makeSubagentConfig(DUPLICATE_SUBAGENT_ID);++ let initCalls = 0;+ mockInitializeAgent.mockImplementation(() => {+ initCalls += 1;+ return Promise.resolve(initCalls === 1 ? primaryConfig : subagentConfig);+ });++ await initializeClient({+ req: makeSubagentReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ /** One call for primary, one for the subagent — not four. */+ expect(mockInitializeAgent).toHaveBeenCalledTimes(2);+ expect(agentClientArgs.agent.subagentAgentConfigs).toHaveLength(1);+ });++ it('keeps an agent in `agentConfigs` when it is BOTH a handoff target and a subagent', async () => {+ /** Overlap case: the same child is used both via handoff edges (needs to+ * be in agentConfigs) and as a subagent (needs to be in+ * subagentAgentConfigs, and its tool context preserved). The pipeline+ * shouldn't silently drop it from the handoff map. */+ const shared = await createAgent({+ id: HANDOFF_AND_SUB_ID,+ name: 'Shared Agent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: [],+ });+ await grantView(shared);++ const edges = [{ from: PRIMARY_ID, to: HANDOFF_AND_SUB_ID, edgeType: 'handoff' }];+ const primaryConfig = makePrimaryConfig({+ edges,+ subagents: {+ enabled: true,+ allowSelf: false,+ agent_ids: [HANDOFF_AND_SUB_ID],+ },+ });+ const sharedConfig = makeSubagentConfig(HANDOFF_AND_SUB_ID);++ let call = 0;+ mockInitializeAgent.mockImplementation(() =>+ Promise.resolve(++call === 1 ? primaryConfig : sharedConfig),+ );++ await initializeClient({+ req: makeSubagentReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ expect(agentClientArgs.agent.subagentAgentConfigs).toHaveLength(1);+ /** Shared agent must stay in agentConfigs — it's still the handoff target. */+ expect(agentClientArgs.agentConfigs.has(HANDOFF_AND_SUB_ID)).toBe(true);+ });++ it('clears subagents config on primary when the capability is disabled', async () => {+ /** Admin can turn subagents off at the endpoint level even if an agent was+ * configured for them. The primary's `subagents` field should be+ * suppressed so run.ts never builds a SubagentConfig. */+ const primaryConfig = makePrimaryConfig({+ subagents: { enabled: true, allowSelf: true, agent_ids: [] },+ });+ mockInitializeAgent.mockResolvedValue(primaryConfig);++ const req = makeSubagentReq();+ /** Remove the capability from the admin config. */+ req.config.endpoints.agents.capabilities = [];++ await initializeClient({+ req,+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ expect(agentClientArgs.agent.subagents).toBeUndefined();+ expect(agentClientArgs.agent.subagentAgentConfigs).toEqual([]);+ });++ it('clears subagents on handoff agents too when capability is disabled (Codex P2 regression)', async () => {+ /** Codex P2: the capability gate must suppress `subagents` on EVERY+ * loaded config, not just the primary. `run.ts` iterates all agents+ * and calls `buildSubagentConfigs` per agent, so a handoff target+ * with `subagents.enabled: true` persisted on its document would+ * otherwise still expose self-spawn even when the admin has disabled+ * the capability globally. */+ const authorized = await createAgent({+ id: AUTHORIZED_ID,+ name: 'Handoff Agent',+ provider: 'openai',+ model: 'gpt-4',+ author: new mongoose.Types.ObjectId(),+ tools: [],+ });+ await grantView(authorized);++ const edges = [{ from: PRIMARY_ID, to: AUTHORIZED_ID, edgeType: 'handoff' }];+ const primaryConfig = makePrimaryConfig({+ edges,+ subagents: { enabled: true, allowSelf: true, agent_ids: [] },+ });+ const handoffConfig = {+ id: AUTHORIZED_ID,+ endpoint: 'agents',+ edges: [],+ toolDefinitions: [],+ toolRegistry: new Map(),+ userMCPAuthMap: null,+ tool_resources: {},+ /** Handoff agent document has subagents enabled of its own accord. */+ subagents: { enabled: true, allowSelf: true, agent_ids: [] },+ };++ let callCount = 0;+ mockInitializeAgent.mockImplementation(() =>+ Promise.resolve(++callCount === 1 ? primaryConfig : handoffConfig),+ );++ const req = makeSubagentReq();+ /** Capability OFF at endpoint level. */+ req.config.endpoints.agents.capabilities = [];++ await initializeClient({+ req,+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ /** Primary cleared. */+ expect(agentClientArgs.agent.subagents).toBeUndefined();+ /** Handoff target must ALSO be cleared — otherwise its self-spawn+ * would still fire when run.ts iterates agentConfigs. */+ const handoffLoaded = agentClientArgs.agentConfigs.get(AUTHORIZED_ID);+ expect(handoffLoaded).toBeDefined();+ expect(handoffLoaded.subagents).toBeUndefined();+ expect(handoffLoaded.subagentAgentConfigs).toBeUndefined();+ });++ it('skips subagent loading entirely when the feature is disabled on the agent', async () => {+ const primaryConfig = makePrimaryConfig({+ subagents: { enabled: false, allowSelf: true, agent_ids: [SUBAGENT_ID] },+ });+ mockInitializeAgent.mockResolvedValue(primaryConfig);++ await initializeClient({+ req: makeSubagentReq(),+ res: {},+ signal: new AbortController().signal,+ endpointOption: makeEndpointOption(),+ });++ /** Only one initializeAgent call — for the primary. No subagent loaded. */+ expect(mockInitializeAgent).toHaveBeenCalledTimes(1);+ expect(agentClientArgs.agent.subagentAgentConfigs).toEqual([]);+ });+});diff --git a/client/src/common/agents-types.ts b/client/src/common/agents-types.tsindex cd3e5e0f49..8a018e8fcb 100644--- a/client/src/common/agents-types.ts+++ b/client/src/common/agents-types.ts@@ -1,6 +1,7 @@import { AgentCapabilities, ArtifactModes } from 'librechat-data-provider';import type {AgentModelParameters,+ AgentSubagentsConfig,AgentToolOptions,SupportContact,AgentProvider,@@ -43,6 +44,7 @@ export type AgentForm = {/** @deprecated Use edges instead */agent_ids?: string[];edges?: GraphEdge[];+ subagents?: AgentSubagentsConfig;[AgentCapabilities.artifacts]?: ArtifactModes | string;recursion_limit?: number;support_contact?: SupportContact;diff --git a/client/src/components/Chat/Messages/Content/Part.tsx b/client/src/components/Chat/Messages/Content/Part.tsxindex 7478afbd0c..1876434271 100644--- a/client/src/components/Chat/Messages/Content/Part.tsx+++ b/client/src/components/Chat/Messages/Content/Part.tsx@@ -19,6 +19,7 @@ import {SkillCall,ReadFileCall,BashCall,+ SubagentCall,} from './Parts';import { ErrorMessage } from './MessageContent';import RetrievalCall from './RetrievalCall';@@ -169,6 +170,29 @@ const Part = memo(function Part({attachments={attachments}/>);+ } else if (isToolCall && toolCall.name === Constants.SUBAGENT) {+ /** `subagent_content` is the aggregated content-parts array the+ * backend writes onto the tool_call at message-save time so the+ * child's activity survives a page refresh. Not present on older+ * runs recorded before the persistence path existed — those fall+ * back to the Recoil atom (live session) or the raw tool output+ * inside `SubagentCall`. */+ const persistedContent = (+ toolCall as unknown as {+ subagent_content?: TMessageContentParts[];+ }+ ).subagent_content;+ return (+ <SubagentCall+ toolCallId={toolCall.id ?? ''}+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ persistedContent={persistedContent}+ />+ );} else if (isToolCall && toolCall.name === 'read_file') {return (<ReadFileCalldiff --git a/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx b/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsxnew file mode 100644index 0000000000..7b2171e5a4--- /dev/null+++ b/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx@@ -0,0 +1,762 @@+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';+import { useRecoilValue } from 'recoil';+import { ArrowDown, ChevronRight, Users } from 'lucide-react';+import { OGDialog, OGDialogContent, OGDialogTitle, OGDialogDescription } from '@librechat/client';+import { ContentTypes, EModelEndpoint } from 'librechat-data-provider';+import type { TAttachment, TMessage, TMessageContentParts } from 'librechat-data-provider';+import ToolCall from '~/components/Chat/Messages/Content/ToolCall';+import ToolCallGroup from '~/components/Chat/Messages/Content/ToolCallGroup';+import Container from '~/components/Chat/Messages/Content/Container';+import type { PartWithIndex } from '~/components/Chat/Messages/Content/ParallelContent';+import MessageIcon from '~/components/Share/MessageIcon';+import { useAgentsMapContext } from '~/Providers';+import Text from './Text';+import Reasoning from './Reasoning';+import { AttachmentGroup } from './Attachment';+import { MessageContext } from '~/Providers/MessageContext';+import { useLocalize } from '~/hooks';+import { subagentProgressByToolCallId } from '~/store';+import type { SubagentTickerLine } from '~/utils/subagentContent';+import { cn, groupSequentialToolCalls, parseToolName } from '~/utils';++interface SubagentCallProps {+ toolCallId: string;+ initialProgress: number;+ /** True while the parent run is still streaming. Used — along with the+ * tool_call's `progress` and any terminal subagent envelope — to decide+ * whether the subagent is `running`, `cancelled`, or `finished`. */+ isSubmitting?: boolean;+ args?: string | Record<string, unknown>;+ output?: string | null;+ attachments?: TAttachment[];+ /** Aggregated content parts the backend attached to the tool_call at+ * message-save time. Takes precedence over the in-memory Recoil atom+ * so a page refresh shows the same history the user saw live. Older+ * 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[];+}++const TICKER_MAX_LINES = 3;+/** Trailing-edge throttle window for the live preview. Tuned down from+ * the original 1.2s so the ticker feels snappy when the container is+ * already full and frames are scrolling. */+const TICKER_THROTTLE_MS = 800;+/** Below this live-buffer length we skip throttling entirely. Without+ * this the user would see "Reasoning: I" for ~1s while the model+ * streams the rest of the sentence — the pass-through lets early+ * tokens appear right away, and throttling only kicks in once the+ * preview is long enough to "fill the container". */+const TICKER_PASSTHROUGH_CHARS = 120;+/** Distance from the dialog scroller's bottom that still counts as+ * "following along". Inside this window new content auto-scrolls; past+ * it we pause so the user can read. Slightly looser than the main+ * messages view since the dialog is a smaller scroller. */+const DIALOG_AT_BOTTOM_THRESHOLD_PX = 120;++/**+ * Trailing-edge throttle. Forwards `value` at most once per `intervalMs`+ * when `enabled` is true; pass-through when false so the final frame+ * lands without waiting out the interval.+ *+ * Uses refs + `useReducer` for the re-render trigger instead of+ * `useState(value)`: storing the throttled value as state would drive+ * an infinite update loop whenever the upstream `value` is a new+ * reference each render (e.g. a `useMemo` whose deps are stable by+ * content but not by identity), because `setState` with a new-reference+ * input always schedules another render.+ *+ * Ref mutations happen during render (idempotent — same value on+ * re-invoke under Strict/Concurrent rendering), but `setTimeout` is+ * confined to a `useEffect` so discarded renders don't leave orphan+ * timers firing against stale trees.+ */+function useThrottledValue<T>(value: T, intervalMs: number, enabled: boolean): T {+ const [, forceUpdate] = useReducer((x) => x + 1, 0);+ const throttledRef = useRef<T>(value);+ const latestValueRef = useRef<T>(value);+ /** Negative-infinity sentinel so the very first render always falls+ * through the "past the window" branch and the caller sees the+ * initial value synchronously — no dead 1.2s while the first frame+ * sits in the throttle. */+ const lastFireAtRef = useRef<number>(Number.NEGATIVE_INFINITY);+ const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);++ latestValueRef.current = value;++ /** Render-time computation: pick the value the caller should see, and+ * commit refs if we're past the throttle window. Ref writes are+ * idempotent under Strict Mode double-invoke. No `setTimeout` here —+ * that lives in the effect below so replayed renders don't strand+ * timers. */+ let effectiveValue: T;+ if (!enabled) {+ effectiveValue = value;+ } else {+ const now = performance.now();+ const sinceLast = now - lastFireAtRef.current;+ if (sinceLast >= intervalMs) {+ throttledRef.current = value;+ lastFireAtRef.current = now;+ effectiveValue = value;+ } else {+ effectiveValue = throttledRef.current;+ }+ }++ /** Schedule the trailing-edge timer after commit. Runs whenever the+ * throttled frame is stale relative to the latest value; the timer+ * callback fires `forceUpdate` so the next render's render-time+ * check commits the now-latest value. */+ useEffect(() => {+ if (!enabled) {+ if (timerRef.current != null) {+ clearTimeout(timerRef.current);+ timerRef.current = null;+ }+ return;+ }+ if (Object.is(throttledRef.current, latestValueRef.current)) return;+ if (timerRef.current != null) return;+ const sinceLast = performance.now() - lastFireAtRef.current;+ const delay = Math.max(0, intervalMs - sinceLast);+ timerRef.current = setTimeout(() => {+ timerRef.current = null;+ forceUpdate();+ }, delay);+ }, [value, intervalMs, enabled]);++ /** Cleanup on unmount. */+ useEffect(+ () => () => {+ if (timerRef.current != null) clearTimeout(timerRef.current);+ },+ [],+ );++ return effectiveValue;+}++/**+ * Renders the parent's `subagent` tool call as a compact "what the child is+ * doing right now" ticker. The collapsed view shows short, user-readable+ * status lines — streaming text/reasoning previews plus tool-call lifecycle+ * markers — built from the `SubagentUpdateEvent` stream. Clicking opens a+ * dialog that renders the child's aggregated content parts through the same+ * `<Part />` pipeline the main conversation uses, so tool calls, reasoning+ * blocks, and the final response all look like a regular assistant message.+ *+ * Progress is sourced from the `subagentProgressByToolCallId` Recoil atom+ * family, populated by `useStepHandler` as `ON_SUBAGENT_UPDATE` SSE+ * envelopes arrive. The atom is keyed by the parent's `tool_call_id`.+ */+export default function SubagentCall({+ toolCallId,+ initialProgress,+ isSubmitting = false,+ args,+ output,+ attachments,+ persistedContent,+}: SubagentCallProps) {+ const localize = useLocalize();+ const progress = useRecoilValue(subagentProgressByToolCallId(toolCallId));+ const agentsMap = useAgentsMapContext();+ const [open, setOpen] = useState(false);++ 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 subagentAgent = subagentAgentId ? agentsMap?.[subagentAgentId] : undefined;+ /**+ * Tri-state status resolution, aligned with `ToolCall.tsx`:+ *+ * - `finished`: the tool_call's own progress reached 1 (backend wrote a+ * result) OR the subagent explicitly emitted a `stop` / `error` phase.+ * - `cancelled`: the stream has ended (`!isSubmitting`) before either+ * condition was met — e.g. user stop, dropped connection, backend+ * crash. Without this check, an interrupted run would render as+ * permanently "working…".+ * - `running`: the parent is still streaming and no terminal signal has+ * arrived yet.+ */+ const hasError = progress?.status === 'error';+ const finished = initialProgress >= 1 || progress?.status === 'stop' || hasError;+ const cancelled = !isSubmitting && !finished;+ const running = !finished && !cancelled;++ /**+ * Content parts for the dialog. Preference order:+ *+ * 1. **Persisted** `subagent_content` on the parent `tool_call`+ * when available. Written by the backend at message-save time+ * and refreshed on sync / reconnect — the canonical record of+ * the run. After a disconnect the client's live atom may have+ * missed events, so trusting `persistedContent` prevents the+ * dialog from showing a stale/partial view of a completed+ * subagent.+ * 2. **Live atom** incrementally built by `foldSubagentEvent` as+ * each `ON_SUBAGENT_UPDATE` arrives. Used while the subagent+ * is mid-run (before the parent message saves, the persisted+ * snapshot is empty) and as a fallback for older runs recorded+ * before the persistence path landed.+ */+ const liveParts = progress?.contentParts as TMessageContentParts[] | undefined;+ const contentParts = useMemo<TMessageContentParts[]>(() => {+ if (persistedContent && persistedContent.length > 0) return persistedContent;+ if (liveParts && liveParts.length > 0) return liveParts;+ return [];+ }, [liveParts, persistedContent]);++ /** Last `TICKER_MAX_LINES` lines from the atom's incrementally-built+ * ticker state, so history isn't lost to any event trimming. */+ const tickerLines = useMemo<SubagentTickerLine[]>(() => {+ const lines = progress?.tickerState?.lines ?? [];+ return lines.slice(-TICKER_MAX_LINES);+ }, [progress?.tickerState?.lines]);++ /** Only throttle once the running buffer is wide enough to "fill the+ * container" — pre-threshold updates pass through so the user sees+ * early tokens immediately, not a static "Reasoning: I" while more+ * text piles up behind the throttle. */+ const shouldThrottleTicker = useMemo(() => {+ if (!running) return false;+ const liveBody = tickerLines.reduce((max, line) => {+ if (line.kind === 'writing' || line.kind === 'reasoning') {+ return Math.max(max, line.body.length);+ }+ return max;+ }, 0);+ return liveBody >= TICKER_PASSTHROUGH_CHARS;+ }, [running, tickerLines]);++ const displayedTickerLines = useThrottledValue(+ tickerLines,+ TICKER_THROTTLE_MS,+ shouldThrottleTicker,+ );++ const description = typeof args === 'string' ? tryDescription(args) : extractDescription(args);++ /** Base verb-only label ("Running agent" / "Ran agent"). The agent name+ * is rendered separately as a muted sub-label so "agent" stays a+ * constant visual anchor regardless of name length. */+ const headerText = hasError+ ? localize('com_ui_subagent_errored')+ : cancelled+ ? localize('com_ui_subagent_cancelled')+ : running+ ? localize('com_ui_subagent_running')+ : localize('com_ui_subagent_complete');+ /** Muted sub-label shown to the right of the base label: the+ * configured agent name for named subagents. Self-spawns omit it+ * (redundant — the header already says "agent") as do cases where+ * the name isn't resolvable (agent map miss). */+ const subagentNameLabel = !isSelfSpawn && subagentAgent?.name ? subagentAgent.name : '';++ /**+ * Minimal `MessageContext` for the dialog's `<Part />` tree. Subagent+ * content rendering needs the same context the main conversation uses+ * (reasoning expand state, latest-message cursor, etc.) — synthesizing+ * a scoped context lets us reuse the real part renderers without+ * pulling the full `ChatView` / `MessagesView` tree into the dialog.+ */+ const dialogMessageContext = useMemo(+ () => ({+ messageId: `subagent-${toolCallId}`,+ isExpanded: true,+ isSubmitting: running,+ isLatestMessage: running,+ conversationId: null,+ }),+ [toolCallId, running],+ );++ const lastPartIndex = contentParts.length - 1;++ /**+ * Dialog renderer used by {@link ToolCallGroup} (for grouped tool_call+ * batches) and by the per-part map (for single parts). Mirrors the+ * main `<Part />` dispatch table but stays scoped to the three types+ * a subagent run emits — avoiding the import cycle that would come+ * from routing through `Parts/index`.+ */+ const renderDialogPart = useCallback(+ (part: TMessageContentParts, idx: number, isLastPart: boolean): JSX.Element | null => {+ return (+ <SubagentDialogPart+ key={`${toolCallId}-part-${idx}`}+ part={part}+ isSubmitting={running}+ showCursor={running && isLastPart}+ isLast={isLastPart}+ />+ );+ },+ [toolCallId, running],+ );++ /**+ * Apply the same consecutive-tool-call batching the main `ContentParts`+ * uses so the dialog renders with visual parity: grouped tools collapse+ * into a single `Used N tools` header, single parts wrap in `Container`+ * for the same `gap-3` flex column spacing the main conversation has.+ */+ const groupedParts = useMemo(() => {+ const withIdx: PartWithIndex[] = contentParts.map((part, idx) => ({ part, idx }));+ return groupSequentialToolCalls(withIdx);+ }, [contentParts]);++ /**+ * Auto-scroll the dialog's content area as new parts / delta chunks+ * stream in. Same pattern as `MessagesView` but with a dialog-tuned+ * threshold — the user can scroll up to read back without auto-scroll+ * snatching control. Explicit "jump to bottom" button lets them resume+ * following along without having to scroll all the way down.+ */+ const scrollRef = useRef<HTMLDivElement | null>(null);+ const contentRef = useRef<HTMLDivElement | null>(null);+ const [isAtBottom, setIsAtBottom] = useState(true);++ /** React `onScroll` prop instead of manual `addEventListener` so the+ * handler attaches as part of DOM commit — no race with Radix's+ * portal-mount timing that would leave `scrollRef.current` null when+ * the effect runs and silently skip the listener. */+ const handleScroll = useCallback((event: React.UIEvent<HTMLDivElement>) => {+ const el = event.currentTarget;+ const distance = el.scrollHeight - el.scrollTop - el.clientHeight;+ setIsAtBottom(distance <= DIALOG_AT_BOTTOM_THRESHOLD_PX);+ }, []);++ /** Snap to bottom every time the dialog opens so a freshly-opened+ * dialog starts parked on the live cursor. */+ useEffect(() => {+ if (!open) return;+ const el = scrollRef.current;+ if (!el) return;+ el.scrollTop = el.scrollHeight;+ setIsAtBottom(true);+ }, [open]);++ /** Keep the view pinned to the bottom while the user is at/near it —+ * including during delta streams that grow the last TEXT/THINK part+ * without changing `contentParts.length`. A `ResizeObserver` on the+ * inner content div catches every height change, whether structural+ * (new tool call) or incremental (writing text grows in-place), so+ * auto-scroll doesn't desync just because tokens are piling into an+ * existing part. */+ useEffect(() => {+ if (!open) return;+ const scrollEl = scrollRef.current;+ const contentEl = contentRef.current;+ if (!scrollEl || !contentEl) return;+ if (typeof ResizeObserver === 'undefined') return;+ const observer = new ResizeObserver(() => {+ if (!isAtBottom) return;+ scrollEl.scrollTop = scrollEl.scrollHeight;+ });+ observer.observe(contentEl);+ return () => observer.disconnect();+ }, [open, isAtBottom]);++ const scrollDialogToBottom = useCallback(() => {+ const el = scrollRef.current;+ if (!el) return;+ el.scrollTo({ top: el.scrollHeight, behavior: 'smooth' });+ setIsAtBottom(true);+ }, []);++ return (+ <>+ <button+ type="button"+ onClick={() => setOpen(true)}+ className={cn(+ 'group my-1.5 flex w-full flex-col gap-1 rounded-lg border border-border-light bg-surface-secondary px-3 py-2 text-left transition hover:bg-surface-tertiary',+ running && 'animate-pulse-slow',+ )}+ aria-label={headerText}+ >+ <div className="flex items-center gap-2 text-sm font-medium text-text-primary">+ <div+ className={cn(+ 'flex h-5 w-5 shrink-0 items-center justify-center overflow-hidden rounded-full',+ running && !subagentAgent && 'animate-pulse text-primary',+ )}+ aria-hidden="true"+ >+ {subagentAgent ? (+ <MessageIcon+ message={+ {+ endpoint: EModelEndpoint.agents,+ isCreatedByUser: false,+ } as TMessage+ }+ agent={subagentAgent}+ />+ ) : (+ <Users size={14} />+ )}+ </div>+ <span className="shrink-0">{headerText}</span>+ {subagentNameLabel ? (+ <span+ className="min-w-0 flex-1 truncate font-normal text-text-secondary"+ title={subagentNameLabel}+ >+ {subagentNameLabel}+ </span>+ ) : (+ <span className="flex-1" />+ )}+ <ChevronRight+ size={14}+ className="shrink-0 text-text-secondary transition group-hover:translate-x-0.5"+ aria-hidden="true"+ />+ </div>++ <ul className="w-full space-y-0.5 pl-5 font-mono text-xs text-text-secondary">+ {displayedTickerLines.length === 0 && running ? (+ <li className="truncate opacity-70">{localize('com_ui_subagent_waiting')}</li>+ ) : null}+ {displayedTickerLines.map((line, i) => (+ <TickerLineView key={`${i}-${tickerLineKey(line)}`} line={line} />+ ))}+ </ul>+ </button>++ <OGDialog open={open} onOpenChange={setOpen}>+ <OGDialogContent+ className={cn(+ 'max-h-[85vh] overflow-hidden',+ /** Tighter inter-row gap than the dialog default (`gap-4`)+ * — title + description + scroll area read as one block+ * rather than three separated panels. */+ 'gap-2',+ /** Responsive width: narrow on phones, scales up to ~80rem on+ * widescreens. Viewport-relative max keeps margin on the+ * edges while still using real estate on laptops / large+ * displays — noticeably wider than the default dialog. */+ 'w-[min(96vw,80rem)] max-w-[min(96vw,80rem)]',+ )}+ >+ <OGDialogTitle>+ {isSelfSpawn+ ? localize('com_ui_subagent_dialog_title_self')+ : localize('com_ui_subagent_dialog_title', { 0: subagentType })}+ </OGDialogTitle>+ <OGDialogDescription className="text-sm text-text-secondary">+ {description || localize('com_ui_subagent_dialog_description')}+ </OGDialogDescription>++ <div className="relative mt-3">+ {!isAtBottom && (+ <button+ type="button"+ onClick={scrollDialogToBottom}+ aria-label={localize('com_ui_subagent_scroll_to_bottom')}+ className="absolute bottom-3 right-6 z-10 flex h-8 w-8 items-center justify-center rounded-full border border-border-light bg-surface-secondary text-text-secondary shadow-md transition hover:bg-surface-tertiary hover:text-text-primary"+ >+ <ArrowDown size={16} aria-hidden="true" />+ </button>+ )}+ <div+ ref={scrollRef}+ onScroll={handleScroll}+ /** Mirrors the main conversation's content-parts wrapper+ * (`max-w-full flex-grow flex-col gap-0` from+ * `MessageParts.tsx`). Part-specific wrappers (`Container`+ * on TEXT, the Reasoning component's own wrapper on THINK,+ * `ToolCallGroup` margins on grouped tools) handle their+ * own spacing — we don't re-wrap everything in `Container`+ * because that would constrain Reasoning's full-column+ * width the way it has in regular messages.+ * Outer `px-4 py-3` gives the dialog breathing room. */+ className="max-h-[65vh] overflow-y-auto px-4 py-3"+ >+ <div ref={contentRef} className="flex max-w-full flex-grow flex-col gap-0">+ {contentParts.length > 0 ? (+ <MessageContext.Provider value={dialogMessageContext}>+ {groupedParts.map((group) => {+ if (group.type === 'single') {+ const { part, idx } = group.part;+ /** Per-type dispatch handles wrapping: TEXT goes+ * through `Container`, THINK/TOOL_CALL render+ * directly so their own wrappers set the width+ * and spacing. */+ return renderDialogPart(part, idx, idx === lastPartIndex);+ }+ /** Consecutive tool_calls (2+) collapse into a+ * `Used N tools` group — same behavior as the main+ * message view. */+ return (+ <ToolCallGroup+ key={`${toolCallId}-group-${group.parts[0].idx}`}+ parts={group.parts}+ isSubmitting={running}+ isLast={group.parts.some((p) => p.idx === lastPartIndex)}+ renderPart={renderDialogPart}+ lastContentIdx={lastPartIndex}+ />+ );+ })}+ </MessageContext.Provider>+ ) : output ? (+ /** Fallback: no aggregated content parts but the backend+ * wrote a final tool_call output. Happens for older+ * subagent runs recorded before the event forwarder+ * existed. Route through the same leaf renderer so+ * markdown renders properly. */+ <MessageContext.Provider value={dialogMessageContext}>+ <SubagentDialogPart+ part={+ {+ type: ContentTypes.TEXT,+ text: output,+ } as unknown as TMessageContentParts+ }+ isSubmitting={false}+ showCursor={false}+ isLast+ />+ </MessageContext.Provider>+ ) : (+ <div className="text-sm italic text-text-secondary">+ {running+ ? localize('com_ui_subagent_no_result_yet')+ : localize('com_ui_subagent_empty_result')}+ </div>+ )}+ </div>+ </div>+ </div>+ </OGDialogContent>+ </OGDialog>++ {attachments && attachments.length > 0 && <AttachmentGroup attachments={attachments} />}+ </>+ );+}++function extractSubagentType(args: SubagentCallProps['args']): string {+ if (typeof args === 'string') {+ try {+ const parsed = JSON.parse(args) as { subagent_type?: string };+ return parsed?.subagent_type ?? 'agent';+ } catch {+ return 'agent';+ }+ }+ const a = args as { subagent_type?: string } | undefined;+ return a?.subagent_type ?? 'agent';+}++function extractDescription(args: Record<string, unknown> | undefined): string | undefined {+ const d = args?.description;+ return typeof d === 'string' && d.length > 0 ? d : undefined;+}++function tryDescription(args: string): string | undefined {+ try {+ const parsed = JSON.parse(args) as { description?: string };+ return typeof parsed?.description === 'string' ? parsed.description : undefined;+ } catch {+ return undefined;+ }+}++/** Stable key for a ticker line — helps React reuse the DOM node across+ * in-place updates to the same live `writing` / `reasoning` line, and+ * gives tool-call lines a stable identity by tool name. */+function tickerLineKey(line: SubagentTickerLine): string {+ switch (line.kind) {+ case 'writing':+ case 'reasoning':+ return line.kind;+ case 'using_tool':+ return `using:${line.toolNames.join(',')}`;+ case 'tool_complete':+ return `done:${line.toolName}`;+ case 'error':+ return `error:${line.message ?? ''}`;+ }+}++/** Inline code-style tool-name badge. Matches the monospace styling of+ * the ticker itself but with a subtle background so the tool identifier+ * reads as a "code" token rather than plain prose. */+function ToolNameBadge({ name }: { name: string }): JSX.Element {+ return (+ <code className="shrink-0 rounded bg-surface-tertiary px-1 text-text-primary">{name}</code>+ );+}++/** Render a single tool id as a compact JSX fragment: MCP tools split+ * into `<server> · <code>toolName</code>`, native tools resolve their+ * friendly name via `FRIENDLY_NAME_KEYS`, unknown ids fall back to a+ * bare code badge of the raw name. */+function ToolIdentifier({+ rawName,+ localize,+}: {+ rawName: string;+ localize: ReturnType<typeof useLocalize>;+}): JSX.Element {+ const parsed = parseToolName(rawName);+ if (parsed.mcpServer) {+ return (+ <span className="inline-flex min-w-0 shrink items-baseline gap-1">+ <span className="truncate">{parsed.mcpServer}</span>+ <span className="shrink-0 text-text-tertiary">·</span>+ <ToolNameBadge name={parsed.toolName} />+ </span>+ );+ }+ if (parsed.friendlyKey) {+ return <span className="truncate">{localize(parsed.friendlyKey)}</span>;+ }+ return <ToolNameBadge name={parsed.toolName} />;+}++/**+ * Renderer for one ticker line. Splits a fixed label (e.g. "Writing:")+ * into its own `shrink-0` span so the label is never clipped when the+ * body overflows; the body then uses `dir="rtl"` + `text-align: left`+ * to push tail-side ellipsis behavior (newest characters stay flush-+ * right, oldest clip off the left). The rtl trick is scoped to the+ * body span so trailing punctuation on non-streaming lines (e.g. the+ * `…` in "Waiting for first update…") can't get flipped by bidi.+ *+ * Tool lines (`using_tool`, `tool_complete`) go through `ToolIdentifier`+ * so MCP-hosted tools render as `<server> · <tool>` badges and native+ * tools use their friendly names — matching the delimiter-aware+ * rendering the main tool UI already uses.+ */+function TickerLineView({ line }: { line: SubagentTickerLine }): JSX.Element {+ const localize = useLocalize();+ if (line.kind === 'writing' || line.kind === 'reasoning') {+ const prefix =+ line.kind === 'writing'+ ? localize('com_ui_subagent_ticker_writing')+ : localize('com_ui_subagent_ticker_reasoning');+ return (+ <li className="flex w-full items-baseline gap-1 overflow-hidden text-text-primary">+ <span className="shrink-0">{prefix}:</span>+ <span+ dir="rtl"+ className="min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap text-left"+ >+ {line.body}+ </span>+ </li>+ );+ }+ if (line.kind === 'using_tool') {+ const prefix = localize('com_ui_subagent_ticker_using');+ return (+ <li className="flex w-full items-baseline gap-1 overflow-hidden whitespace-nowrap">+ <span className="shrink-0">{prefix}</span>+ <span className="flex min-w-0 flex-1 items-baseline gap-1 overflow-hidden">+ {line.toolNames.map((name, i) => (+ <span key={`${i}-${name}`} className="flex min-w-0 items-baseline gap-1">+ {i > 0 && <span className="shrink-0 text-text-tertiary">,</span>}+ <ToolIdentifier rawName={name} localize={localize} />+ </span>+ ))}+ {line.argsSnippet && (+ <span className="min-w-0 truncate text-text-tertiary">({line.argsSnippet})</span>+ )}+ </span>+ </li>+ );+ }+ if (line.kind === 'tool_complete') {+ return (+ <li className="flex w-full items-baseline gap-1 overflow-hidden whitespace-nowrap">+ <ToolIdentifier rawName={line.toolName} localize={localize} />+ <span className="shrink-0 text-text-tertiary">→</span>+ <span+ dir="rtl"+ className="min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap text-left"+ >+ {line.outputSnippet ?? localize('com_ui_subagent_ticker_tool_done')}+ </span>+ </li>+ );+ }+ /* error */+ const errorPrefix = localize('com_ui_subagent_ticker_error');+ return (+ <li className="flex w-full items-baseline gap-1 overflow-hidden text-text-warning">+ <span className="shrink-0">{errorPrefix}:</span>+ <span className="min-w-0 flex-1 truncate">{line.message ?? ''}</span>+ </li>+ );+}++/**+ * Per-part renderer for the dialog. Mirrors the wrapper choices `<Part>`+ * makes in regular messages so subagent content matches the visual width+ * and spacing the user already knows: TEXT wraps in `Container` (which+ * provides `gap-3` column spacing and the `mt-5` sibling margin), while+ * THINK and TOOL_CALL render bare — their own wrappers (`Reasoning`'s+ * `mb-2 pb-2 pt-2` box, `ToolCall`'s own margins) control their layout+ * and full-column width. Staying inline (vs. calling `<Part>`) avoids+ * the `Parts/index.ts → SubagentCall → Part` import cycle and keeps us+ * from accidentally rendering a nested subagent dialog.+ */+function SubagentDialogPart({+ part,+ isSubmitting,+ showCursor,+ isLast,+}: {+ part: TMessageContentParts;+ isSubmitting: boolean;+ showCursor: boolean;+ isLast: boolean;+}): JSX.Element | null {+ if (part.type === ContentTypes.TEXT) {+ const text = (part as { text: string }).text;+ return (+ <Container>+ <Text text={text} showCursor={showCursor} isCreatedByUser={false} />+ </Container>+ );+ }+ if (part.type === ContentTypes.THINK) {+ const think = (part as { think: string }).think;+ return <Reasoning reasoning={think} isLast={isLast} />;+ }+ if (part.type === ContentTypes.TOOL_CALL) {+ const tc = (+ part as {+ [ContentTypes.TOOL_CALL]?: {+ args?: string | Record<string, unknown>;+ output?: string;+ name?: string;+ progress?: number;+ };+ }+ )[ContentTypes.TOOL_CALL];+ if (!tc) return null;+ return (+ <ToolCall+ args={tc.args ?? ''}+ output={tc.output ?? ''}+ initialProgress={tc.progress ?? 0.1}+ isSubmitting={isSubmitting}+ isLast={isLast}+ name={tc.name ?? ''}+ />+ );+ }+ return null;+}diff --git a/client/src/components/Chat/Messages/Content/Parts/__tests__/SubagentCall.test.tsx b/client/src/components/Chat/Messages/Content/Parts/__tests__/SubagentCall.test.tsxnew file mode 100644index 0000000000..14725282cf--- /dev/null+++ b/client/src/components/Chat/Messages/Content/Parts/__tests__/SubagentCall.test.tsx@@ -0,0 +1,626 @@+import React from 'react';+import { RecoilRoot, useRecoilCallback } from 'recoil';+import { render, screen, act, waitFor } from '@testing-library/react';+import SubagentCall from '../SubagentCall';+import { subagentProgressByToolCallId, type SubagentProgress } from '~/store/subagents';+import {+ foldSubagentEvent,+ foldSubagentEventIntoTicker,+ initSubagentAggregatorState,+ initSubagentTickerState,+ type SubagentContentPart,+ type SubagentAggregatorState,+ type SubagentTickerState,+} from '~/utils/subagentContent';+import type { SubagentUpdateEvent } from 'librechat-data-provider';++jest.mock('~/hooks', () => ({+ useLocalize:+ () =>+ (key: string, values?: Record<string, unknown>): string => {+ const arg0 = (values?.[0] as string | undefined) ?? '';+ const arg1 = (values?.[1] as string | undefined) ?? '';+ const translations: Record<string, string> = {+ com_ui_subagent_running: 'Running agent',+ com_ui_subagent_complete: 'Ran agent',+ com_ui_subagent_cancelled: 'Cancelled agent',+ com_ui_subagent_errored: 'Agent errored',+ com_ui_subagent_waiting: 'Waiting for first update…',+ com_ui_subagent_dialog_title: `"${arg0}" agent`,+ com_ui_subagent_dialog_title_self: 'Agent',+ com_ui_subagent_dialog_description: 'Isolated child run.',+ com_ui_subagent_no_result_yet: 'No result yet.',+ com_ui_subagent_empty_result: 'No text.',+ com_ui_subagent_ticker_writing: 'Writing',+ com_ui_subagent_ticker_reasoning: 'Reasoning',+ com_ui_subagent_ticker_error: 'Error',+ com_ui_subagent_ticker_using: 'Using',+ com_ui_subagent_ticker_tool_done: 'done',+ com_ui_subagent_ticker_tool_output: `${arg0} → ${arg1}`,+ };+ return translations[key] ?? key;+ },+}));++/** Stub the leaf content-part renderers — the tests only need to confirm+ * that the right TMessageContentParts flow through to them. */+jest.mock('../Text', () => ({+ __esModule: true,+ default: ({ text }: { text: string }) => <div data-testid="text-part">{text}</div>,+}));++jest.mock('../Reasoning', () => ({+ __esModule: true,+ default: ({ reasoning }: { reasoning: string }) => (+ <div data-testid="reasoning-part">{reasoning}</div>+ ),+}));++jest.mock('~/components/Chat/Messages/Content/ToolCall', () => ({+ __esModule: true,+ default: ({ name, output }: { name: string; output: string }) => (+ <div data-testid="tool-call-part" data-name={name}>+ {output}+ </div>+ ),+}));++jest.mock('../Attachment', () => ({+ AttachmentGroup: ({ attachments }: { attachments: unknown }) => (+ <div data-testid="attachment-group">{JSON.stringify(attachments)}</div>+ ),+}));++jest.mock('@librechat/client', () => ({+ OGDialog: ({ children }: { children: React.ReactNode }) => <>{children}</>,+ OGDialogContent: ({ children }: { children: React.ReactNode }) => (+ <div data-testid="dialog-content">{children}</div>+ ),+ OGDialogTitle: ({ children }: { children: React.ReactNode }) => (+ <div data-testid="dialog-title">{children}</div>+ ),+ OGDialogDescription: ({ children }: { children: React.ReactNode }) => (+ <div data-testid="dialog-description">{children}</div>+ ),+}));++jest.mock('lucide-react', () => ({+ // eslint-disable-next-line i18next/no-literal-string+ ChevronRight: () => <span>chevron</span>,+ // eslint-disable-next-line i18next/no-literal-string+ Users: () => <span>users</span>,+}));++/** Stub out the agents-map provider so the header doesn't look up real+ * agent data. Tests don't exercise the avatar lookup path; the default+ * (no agent) renders the `Users` SVG fallback. */+jest.mock('~/Providers', () => ({+ useAgentsMapContext: () => ({}),+}));++/** Stub `MessageIcon` — only relevant when `useAgentsMapContext` returns+ * a matching agent; with the stub above it never renders. */+jest.mock('~/components/Share/MessageIcon', () => ({+ __esModule: true,+ default: ({ agent }: { agent?: { name?: string } }) => (+ <span data-testid="agent-icon">{agent?.name ?? ''}</span>+ ),+}));++jest.mock('~/utils', () => ({+ ...jest.requireActual('~/utils/groupToolCalls'),+ ...jest.requireActual('~/utils/toolLabels'),+ cn: (...classes: unknown[]) => classes.filter(Boolean).join(' '),+}));++/** The dialog wraps single parts in `Container` and grouped tool_calls in+ * `ToolCallGroup`. Stub both as transparent wrappers so the tests still+ * assert on the leaf renderers (Text/Reasoning/ToolCall) without pulling+ * Recoil-backed tool-call batching state into the component tree. */+jest.mock('~/components/Chat/Messages/Content/Container', () => ({+ __esModule: true,+ default: ({ children }: { children: React.ReactNode }) => (+ <div data-testid="dialog-container">{children}</div>+ ),+}));++jest.mock('~/components/Chat/Messages/Content/ToolCallGroup', () => ({+ __esModule: true,+ default: ({+ parts,+ renderPart,+ lastContentIdx,+ }: {+ parts: Array<{ part: unknown; idx: number }>;+ renderPart: (part: unknown, idx: number, isLast: boolean) => React.ReactNode;+ lastContentIdx: number;+ }) => (+ <div data-testid="tool-call-group">+ {parts.map(({ part, idx }) => renderPart(part, idx, idx === lastContentIdx))}+ </div>+ ),+}));++/** Helper: fold an event sequence through the real incremental+ * aggregators so each test seeds the atom with the same shape+ * `useStepHandler` produces in live state. */+function foldEvents(events: SubagentUpdateEvent[]): {+ contentParts: SubagentContentPart[];+ aggregatorState: SubagentAggregatorState;+ tickerState: SubagentTickerState;+} {+ let contentParts: SubagentContentPart[] = [];+ let aggregatorState = initSubagentAggregatorState();+ let tickerState = initSubagentTickerState();+ for (const event of events) {+ ({ parts: contentParts, state: aggregatorState } = foldSubagentEvent(+ contentParts,+ aggregatorState,+ event,+ ));+ tickerState = foldSubagentEventIntoTicker(tickerState, event);+ }+ return { contentParts, aggregatorState, tickerState };+}++/** Thin wrapper: tests pass `{status, subagentRunId, subagentType, events}`+ * and get back a full-shape `SubagentProgress` with all three aggregator+ * outputs filled. */+function progressFromEvents(+ base: { events: SubagentUpdateEvent[] } & Omit<+ SubagentProgress,+ 'contentParts' | 'aggregatorState' | 'tickerState'+ >,+): SubagentProgress {+ const { events, ...rest } = base;+ const aggregates = foldEvents(events);+ return { ...rest, ...aggregates };+}++/**+ * Mount the component inside a RecoilRoot and expose a setter so each test+ * can seed the `subagentProgressByToolCallId` atom with the state under test.+ * Real Recoil, no mocks of the store — matches the hook-integration test+ * style in useStepHandler.spec.ts.+ */+function renderWithState(args: {+ toolCallId: string;+ initialProgress: number;+ isSubmitting?: boolean;+ progress?: SubagentProgress | null;+}) {+ const setter = { current: null as null | ((next: SubagentProgress | null) => void) };+ const SeedHelper = () => {+ setter.current = useRecoilCallback(+ ({ set }) =>+ (next: SubagentProgress | null) => {+ set(subagentProgressByToolCallId(args.toolCallId), next);+ },+ [],+ );+ return null;+ };+ const rendered = render(+ <RecoilRoot>+ <SeedHelper />+ <SubagentCall+ toolCallId={args.toolCallId}+ initialProgress={args.initialProgress}+ isSubmitting={args.isSubmitting ?? false}+ args={{ subagent_type: 'self', description: 'compute' }}+ />+ </RecoilRoot>,+ );+ act(() => {+ setter.current?.(args.progress ?? null);+ });+ return rendered;+}++describe('SubagentCall — status resolution', () => {+ it('renders "Running agent" while streaming and no terminal envelope has arrived', () => {+ renderWithState({+ toolCallId: 'call_running',+ initialProgress: 0.3,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ events: [],+ status: 'run_step',+ }),+ });+ expect(screen.getByText('Running agent')).toBeInTheDocument();+ });++ it('renders "Ran agent" when the subagent emits a `stop` phase', () => {+ renderWithState({+ toolCallId: 'call_stopped',+ initialProgress: 1,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ events: [],+ status: 'stop',+ }),+ });+ expect(screen.getByText('Ran agent')).toBeInTheDocument();+ });++ it('renders "Ran agent" when the tool call progress reaches 1', () => {+ renderWithState({+ toolCallId: 'call_done',+ initialProgress: 1,+ isSubmitting: false,+ progress: null,+ });+ expect(screen.getByText('Ran agent')).toBeInTheDocument();+ });++ it('renders "Cancelled agent" when the stream stops before a terminal envelope (Codex P2 regression)', () => {+ /**+ * Codex P2 on #12725: the old `running` computation ignored whether the+ * parent run was still streaming, so a user stop or dropped connection+ * would leave the ticker permanently "working…". Mirror the behavior+ * of `ToolCall.tsx` — `!isSubmitting && !finished` → cancelled.+ */+ renderWithState({+ toolCallId: 'call_cancelled',+ initialProgress: 0.4,+ isSubmitting: false,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ events: [],+ status: 'run_step',+ }),+ });+ expect(screen.getByText('Cancelled agent')).toBeInTheDocument();+ });++ it('renders "Agent errored" when the subagent emits an `error` phase', () => {+ renderWithState({+ toolCallId: 'call_error',+ initialProgress: 0.4,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ events: [],+ status: 'error',+ }),+ });+ expect(screen.getByText('Agent errored')).toBeInTheDocument();+ });++ it('uses the base "Running agent" label for non-self subagent types (name shown as sub-label elsewhere)', () => {+ renderWithState({+ toolCallId: 'call_named',+ initialProgress: 0.3,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_b',+ subagentType: 'researcher',+ events: [],+ status: 'run_step',+ }),+ });+ /** Header base label is constant ("Running agent"). The agent+ * display name is rendered as a muted sub-label, which this test+ * doesn't exercise (no agents-map context is seeded). */+ expect(screen.getByText('Running agent')).toBeInTheDocument();+ });+});++describe('SubagentCall — ticker', () => {+ it('renders semantic text lines instead of raw event names', async () => {+ renderWithState({+ toolCallId: 'call_ticker',+ initialProgress: 0.3,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ status: 'run_step',+ events: [+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Computing result…' }] } },+ timestamp: '',+ },+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator', args: '{"expression":"42*58"}' }],+ },+ },+ timestamp: '',+ },+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: {+ id: 'c1',+ name: 'calculator',+ output: '42*58 = 2436',+ progress: 1,+ },+ },+ },+ timestamp: '',+ },+ ],+ }),+ });++ /** Ticker now renders a structured `using_tool` line — prefix span+ * ("Using"), a code-style badge for the tool name, and a muted+ * args snippet. Check the pieces individually rather than a+ * combined text match. */+ await waitFor(+ () => {+ expect(screen.getByText('Using')).toBeInTheDocument();+ },+ { timeout: 2500 },+ );+ /** Raw event names never appear in the ticker. */+ expect(screen.queryByText(/on_run_step/)).not.toBeInTheDocument();+ expect(screen.queryByText(/on_message_delta/)).not.toBeInTheDocument();+ /** Tool name renders as a `<code>` badge, args snippet in parens. */+ const calcBadges = screen.getAllByText('calculator');+ expect(calcBadges.some((el) => el.tagName === 'CODE')).toBe(true);+ expect(screen.getByText('(expression=42*58)')).toBeInTheDocument();+ /** Completion line renders the output snippet in the body span. */+ expect(screen.getAllByText('42*58 = 2436').length).toBeGreaterThan(0);+ });++ it('collapses a streak of message_delta events into one live Writing line', async () => {+ renderWithState({+ toolCallId: 'call_writing',+ initialProgress: 0.3,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ status: 'message_delta',+ events: ['Hello ', 'world', '!'].map((text) => ({+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'message_delta' as const,+ data: { delta: { content: [{ type: 'text', text }] } },+ timestamp: '',+ })),+ }),+ });+ /** Ticker renders the "Writing:" label and the body in separate spans+ * (prefix is `shrink-0`, body is a tail-truncatable sibling) so the+ * label never gets clipped when the body overflows. "Hello world!"+ * also appears in the dialog body (mocked OGDialog renders+ * children), so `getAllByText` is needed for the body. */+ await waitFor(+ () => {+ expect(screen.getAllByText('Hello world!').length).toBeGreaterThan(0);+ },+ { timeout: 2500 },+ );+ /** Only one "Writing:" label, not three — deltas collapse into one live line. */+ expect(screen.getAllByText('Writing:')).toHaveLength(1);+ });+});++describe('SubagentCall — dialog content', () => {+ it('renders aggregated text, reasoning, and tool_call parts through leaf renderers', () => {+ renderWithState({+ toolCallId: 'call_dialog',+ initialProgress: 0.4,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_a',+ subagentType: 'self',+ status: 'stop',+ events: [+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Let me compute.' }] } },+ timestamp: '',+ },+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator', args: '{}' }],+ },+ },+ timestamp: '',+ },+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'calculator', output: '4', progress: 1 },+ },+ },+ timestamp: '',+ },+ {+ runId: 'p',+ subagentRunId: 'run_a',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'The answer is 4.' }] } },+ timestamp: '',+ },+ ],+ }),+ });++ /** The mocked `OGDialog` always renders children, so dialog content is+ * inspectable without simulating a click. */+ expect(screen.getByTestId('reasoning-part')).toHaveTextContent('Let me compute.');+ expect(screen.getByTestId('tool-call-part')).toHaveAttribute('data-name', 'calculator');+ expect(screen.getByTestId('tool-call-part')).toHaveTextContent('4');+ expect(screen.getByTestId('text-part')).toHaveTextContent('The answer is 4.');+ });++ it('falls back to the raw tool output when no content parts were recorded', () => {+ renderWithState({+ toolCallId: 'call_fallback',+ initialProgress: 1,+ isSubmitting: false,+ progress: null,+ });+ /** No events → no aggregated parts. The SubagentCall should still+ * render the raw final `output` that came back in the parent's+ * tool_call (we pass it explicitly below). */+ const { rerender } = render(+ <RecoilRoot>+ <SubagentCall+ toolCallId="call_fallback_2"+ initialProgress={1}+ output="raw final text"+ isSubmitting={false}+ />+ </RecoilRoot>,+ );+ expect(screen.getByText('raw final text')).toBeInTheDocument();+ rerender(<RecoilRoot />);+ });++ it('renders persistedContent parts when no live events are available (page-refresh flow)', () => {+ /**+ * After a refresh the Recoil atom is empty — the child's history has+ * to come from the `subagent_content` array the backend attached to+ * the tool_call at message-save time. Verifies that a+ * `persistedContent` prop routes through the same leaf renderers+ * (Text / Reasoning / ToolCall) as live aggregation so a reopened+ * dialog looks identical to how the run streamed.+ */+ const persistedContent = [+ { type: 'think', think: 'Prior thinking.' },+ {+ type: 'tool_call',+ tool_call: {+ id: 'inner-1',+ name: 'calculator',+ args: '{"expression":"42*58"}',+ output: '2436',+ progress: 1,+ },+ },+ { type: 'text', text: 'Final persisted answer.' },+ ] as unknown as Parameters<typeof SubagentCall>[0]['persistedContent'];++ render(+ <RecoilRoot>+ <SubagentCall+ toolCallId="call_refresh"+ initialProgress={1}+ isSubmitting={false}+ persistedContent={persistedContent}+ />+ </RecoilRoot>,+ );++ expect(screen.getByTestId('reasoning-part')).toHaveTextContent('Prior thinking.');+ expect(screen.getByTestId('tool-call-part')).toHaveAttribute('data-name', 'calculator');+ expect(screen.getByTestId('tool-call-part')).toHaveTextContent('2436');+ expect(screen.getByTestId('text-part')).toHaveTextContent('Final persisted answer.');+ });++ it('prefers persistedContent when both are populated (sync/reconnect canonical)', () => {+ /**+ * Codex P2 regression: after a disconnect/reconnect the live+ * Recoil bucket can be stale or partial — it missed events+ * while the socket was down. The server-written+ * `persistedContent` on the `tool_call` is the canonical trace+ * of the completed run, so when it's present the dialog should+ * show it, not the (possibly lossy) live aggregation.+ *+ * This also covers the post-stream case where persistence has+ * landed and both snapshots carry the same content — preferring+ * persisted is still correct because it's the authoritative copy.+ */+ render(+ <RecoilRoot>+ <SubagentCall+ toolCallId="call_both_seeded"+ initialProgress={1}+ isSubmitting={false}+ persistedContent={+ [{ type: 'text', text: 'Persisted answer.' }] as unknown as Parameters<+ typeof SubagentCall+ >[0]['persistedContent']+ }+ />+ </RecoilRoot>,+ );+ expect(screen.getByText('Persisted answer.')).toBeInTheDocument();+ });++ it('falls back to live aggregated events when persistedContent is empty (mid-stream)', () => {+ /**+ * Before the parent message saves, `persistedContent` is+ * undefined/empty — the live atom is the only source of truth.+ * Verify we render the live aggregation in that case.+ */+ renderWithState({+ toolCallId: 'call_live_fallback',+ initialProgress: 0.4,+ isSubmitting: true,+ progress: progressFromEvents({+ subagentRunId: 'run_live',+ subagentType: 'self',+ status: 'message_delta',+ events: [+ {+ runId: 'p',+ subagentRunId: 'run_live',+ subagentType: 'self',+ subagentAgentId: 'child',+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Live answer.' }] } },+ timestamp: '',+ },+ ],+ }),+ });+ /** Live content renders — both in the ticker preview (collapsed+ * card) and inside the dialog body (mocked OGDialog renders+ * children). */+ expect(screen.getAllByText('Live answer.').length).toBeGreaterThan(0);+ });+});diff --git a/client/src/components/Chat/Messages/Content/Parts/index.ts b/client/src/components/Chat/Messages/Content/Parts/index.tsindex a37bbadd86..da495abb82 100644--- a/client/src/components/Chat/Messages/Content/Parts/index.ts+++ b/client/src/components/Chat/Messages/Content/Parts/index.ts@@ -12,3 +12,4 @@ export { default as EditTextPart } from './EditTextPart';export { default as SkillCall } from './SkillCall';export { default as ReadFileCall } from './ReadFileCall';export { default as BashCall } from './BashCall';+export { default as SubagentCall } from './SubagentCall';diff --git a/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx b/client/src/components/Chat/Messages/Content/ToolCallGroup.tsxindex c66ecc24fa..3706182a21 100644--- a/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx+++ b/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx@@ -1,29 +1,15 @@import { useState, useMemo, useEffect, useCallback } from 'react';import { useRecoilValue } from 'recoil';-import { ChevronDown } from 'lucide-react';-import { ContentTypes, ToolCallTypes } from 'librechat-data-provider';+import { ChevronDown, Users } from 'lucide-react';+import { Constants, ContentTypes, ToolCallTypes } from 'librechat-data-provider';import type { TMessageContentParts, Agents, FunctionToolCall } from 'librechat-data-provider';import type { PartWithIndex } from './ParallelContent';-import type { TranslationKeys } from '~/hooks';-import { StackedToolIcons, getMCPServerName } from './ToolOutput';+import { StackedToolIcons } from './ToolOutput';import { useLocalize, useExpandCollapse } from '~/hooks';import { useMCPIconMap } from '~/hooks/MCP';-import { cn } from '~/utils';+import { cn, getToolDisplayLabel } from '~/utils';import store from '~/store';-/** Maps tool names to translation keys — resolved via localize() at render time. */-const FRIENDLY_NAME_KEYS: Record<string, TranslationKeys> = {- execute_code: 'com_ui_tool_name_code',- run_tools_with_code: 'com_ui_tool_name_code',- web_search: 'com_ui_tool_name_web_search',- image_gen_oai: 'com_ui_tool_name_image_gen',- image_edit_oai: 'com_ui_tool_name_image_edit',- gemini_image_gen: 'com_ui_tool_name_image_gen',- file_search: 'com_ui_tool_name_file_search',- code_interpreter: 'com_ui_tool_name_code_analysis',- retrieval: 'com_ui_tool_name_file_search',-};-interface ToolMeta {name: string;hasOutput: boolean;@@ -41,8 +27,13 @@ function getToolMeta(part: TMessageContentParts): ToolMeta | null {const isStandard ='args' in toolCall && (!toolCall.type || toolCall.type === ToolCallTypes.TOOL_CALL);if (isStandard) {- const tc = toolCall as Agents.ToolCall;- return { name: tc.name ?? '', hasOutput: !!tc.output };+ const tc = toolCall as Agents.ToolCall & { progress?: number };+ /** Subagents can finish with `progress === 1` and no final output+ * text (the parent saw "" / undefined back). Fall back to progress+ * so the group header flips from "Running N agents" to "Ran N+ * agents" on completion even when the child returned no text. */+ const completed = !!tc.output || tc.progress === 1;+ return { name: tc.name ?? '', hasOutput: completed };}if (toolCall.type === ToolCallTypes.CODE_INTERPRETER) {@@ -88,16 +79,29 @@ export default function ToolCallGroup({);const toolNames = useMemo(() => toolMetadata.map((m) => m?.name ?? ''), [toolMetadata]);+ /** Subagent tool calls get their own label verb ("Running/Ran N agents")+ * since "Used N tools" reads oddly when the "tools" are actually child+ * agents. `subagentCount === count` ⇒ the group is 100% subagents. */+ const subagentCount = useMemo(+ () => toolNames.filter((n) => n === Constants.SUBAGENT).length,+ [toolNames],+ );+ const allSubagents = subagentCount > 0 && subagentCount === count;+ /** Past-tense label once the parent stream is no longer live OR every+ * child has a terminal signal (output / progress === 1). Without the+ * `!isSubmitting` branch, a cancelled or errored subagent that never+ * reached `progress === 1` would leave the header stuck on "Running+ * N agents" forever — each individual card already renders its own+ * terminal state ("Cancelled agent", "Agent errored"), so the group+ * summary needs to match that tense. */+ const subagentsDone = allSubagents && (allCompleted || !isSubmitting);+const toolNameSummary = useMemo(() => {const seen = new Set<string>();const labels: string[] = [];for (const rawName of toolNames) {- if (!rawName) {- continue;- }- const serverName = getMCPServerName(rawName);- const nameKey = FRIENDLY_NAME_KEYS[rawName];- const label = serverName || (nameKey ? localize(nameKey) : rawName);+ if (!rawName) continue;+ const label = getToolDisplayLabel(rawName, localize);if (!seen.has(label)) {seen.add(label);labels.push(label);@@ -144,18 +148,47 @@ export default function ToolCallGroup({className="inline-flex w-full items-center gap-2 py-1 text-text-secondary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-heavy"onClick={handleToggle}aria-expanded={isExpanded}- aria-label={localize('com_ui_used_n_tools', { 0: String(count) })}+ aria-label={+ allSubagents+ ? subagentsDone+ ? localize('com_ui_ran_n_agents', { 0: String(count) })+ : localize('com_ui_running_n_agents', { 0: String(count) })+ : localize('com_ui_used_n_tools', { 0: String(count) })+ }>- <StackedToolIcons- toolNames={toolNames}- mcpIconMap={mcpIconMap}- maxIcons={4}- isAnimating={!allCompleted && isSubmitting}- />+ {allSubagents ? (+ /** Subagent groups don't have per-tool icons — StackedToolIcons+ * falls back to a generic wrench that reads as "tools" rather+ * than "agents". A single Users glyph matches the individual+ * subagent card header and keeps the visual language consistent. */+ <div+ className={cn(+ 'flex h-5 w-5 shrink-0 items-center justify-center text-text-secondary',+ !allCompleted && isSubmitting && 'animate-pulse text-primary',+ )}+ aria-hidden="true"+ >+ <Users size={14} />+ </div>+ ) : (+ <StackedToolIcons+ toolNames={toolNames}+ mcpIconMap={mcpIconMap}+ maxIcons={4}+ isAnimating={!allCompleted && isSubmitting}+ />+ )}<span className="tool-status-text font-medium">- {localize('com_ui_used_n_tools', { 0: String(count) })}+ {allSubagents+ ? subagentsDone+ ? localize('com_ui_ran_n_agents', { 0: String(count) })+ : localize('com_ui_running_n_agents', { 0: String(count) })+ : localize('com_ui_used_n_tools', { 0: String(count) })}</span>- {toolNameSummary && (+ {/** Hide the tool-name summary for pure-subagent groups — every+ * entry deduplicates to the same "subagent" token, which adds+ * noise without info. Mixed groups keep the summary. */}+ {toolNameSummary && !allSubagents && (<span className="text-xs font-normal text-text-secondary">— {toolNameSummary}</span>)}<ChevronDowndiff --git a/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx b/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsxindex d34ee055b8..913b0ce49b 100644--- a/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx@@ -4,6 +4,7 @@ import { AgentCapabilities } from 'librechat-data-provider';import { useFormContext, Controller } from 'react-hook-form';import type { AgentForm } from '~/common';import { useAgentPanelContext } from '~/Providers';+import AgentSubagents from './AgentSubagents';import MaxAgentSteps from './MaxAgentSteps';import AgentHandoffs from './AgentHandoffs';import { useLocalize } from '~/hooks';@@ -21,6 +22,10 @@ export default function AdvancedPanel() {() => agentsConfig?.capabilities.includes(AgentCapabilities.chain) ?? false,[agentsConfig],);+ const subagentsEnabled = useMemo(+ () => agentsConfig?.capabilities.includes(AgentCapabilities.subagents) ?? false,+ [agentsConfig],+ );return (<div className="mb-1 flex w-full flex-col gap-2 text-sm">@@ -43,6 +48,13 @@ export default function AdvancedPanel() {</div><div className="flex flex-col gap-4 px-2 pb-2"><MaxAgentSteps />+ {subagentsEnabled && (+ <Controller+ name="subagents"+ control={control}+ render={({ field }) => <AgentSubagents field={field} currentAgentId={currentAgentId} />}+ />+ )}<Controllername="edges"control={control}diff --git a/client/src/components/SidePanel/Agents/Advanced/AgentSubagents.tsx b/client/src/components/SidePanel/Agents/Advanced/AgentSubagents.tsxnew file mode 100644index 0000000000..c3488b0c86--- /dev/null+++ b/client/src/components/SidePanel/Agents/Advanced/AgentSubagents.tsx@@ -0,0 +1,268 @@+import React, { useCallback, useEffect, useMemo, useState } from 'react';+import { MAX_SUBAGENTS, EModelEndpoint } from 'librechat-data-provider';+import { X, PlusCircle, Users } from 'lucide-react';+import {+ Switch,+ HoverCard,+ CircleHelpIcon,+ HoverCardPortal,+ ControlCombobox,+ HoverCardContent,+ HoverCardTrigger,+} from '@librechat/client';+import type { TMessage } from 'librechat-data-provider';+import type { ControllerRenderProps } from 'react-hook-form';+import type { AgentForm, OptionWithIcon } from '~/common';+import MessageIcon from '~/components/Share/MessageIcon';+import { useAgentsMapContext } from '~/Providers';+import { useLocalize } from '~/hooks';+import { ESide } from '~/common';++interface AgentSubagentsProps {+ field: ControllerRenderProps<AgentForm, 'subagents'>;+ currentAgentId: string;+}++const AgentSubagents: React.FC<AgentSubagentsProps> = ({ field, currentAgentId }) => {+ const localize = useLocalize();+ const agentsMap = useAgentsMapContext();+ const [newAgentId, setNewAgentId] = useState('');++ const fieldValue = field.value;+ const value = useMemo(() => fieldValue ?? {}, [fieldValue]);+ const enabled = value.enabled === true;+ const allowSelf = value.allowSelf !== false;+ const agentIds = useMemo(() => value.agent_ids ?? [], [value.agent_ids]);++ const setEnabled = useCallback(+ (next: boolean) => {+ if (!next) {+ /**+ * Persist `{ enabled: false }` (with the existing selections preserved)+ * rather than `undefined`. The backend's `removeNullishValues` strips+ * undefined fields from PATCH payloads, so setting the whole object to+ * undefined would leave the server copy enabled. An explicit+ * `enabled: false` flows through as a real update.+ */+ field.onChange({+ enabled: false,+ allowSelf: value.allowSelf ?? true,+ agent_ids: value.agent_ids ?? [],+ });+ return;+ }+ field.onChange({+ enabled: true,+ allowSelf: value.allowSelf ?? true,+ agent_ids: value.agent_ids ?? [],+ });+ },+ [field, value.allowSelf, value.agent_ids],+ );++ const setAllowSelf = useCallback(+ (next: boolean) => {+ field.onChange({+ ...value,+ enabled: true,+ allowSelf: next,+ });+ },+ [field, value],+ );++ const setAgentIds = useCallback(+ (ids: string[]) => {+ field.onChange({+ ...value,+ enabled: true,+ allowSelf: value.allowSelf ?? true,+ agent_ids: ids,+ });+ },+ [field, value],+ );++ const agents = useMemo(() => (agentsMap ? Object.values(agentsMap) : []), [agentsMap]);++ const selectableAgents = useMemo<OptionWithIcon[]>(() => {+ const selectedSet = new Set(agentIds);+ return agents+ .filter((agent) => {+ if (!agent?.id) return false;+ if (agent.id === currentAgentId) return false;+ return !selectedSet.has(agent.id);+ })+ .map(+ (agent) =>+ ({+ label: agent?.name || '',+ value: agent?.id || '',+ icon: (+ <MessageIcon+ message={+ {+ endpoint: EModelEndpoint.agents,+ isCreatedByUser: false,+ } as TMessage+ }+ agent={agent}+ />+ ),+ }) as OptionWithIcon,+ );+ }, [agents, currentAgentId, agentIds]);++ const getAgentDetails = useCallback((id: string) => agentsMap?.[id], [agentsMap]);++ useEffect(() => {+ if (newAgentId && agentIds.length < MAX_SUBAGENTS && !agentIds.includes(newAgentId)) {+ setAgentIds([...agentIds, newAgentId]);+ setNewAgentId('');+ } else if (newAgentId) {+ setNewAgentId('');+ }+ }, [newAgentId, agentIds, setAgentIds]);++ const removeAgentAt = (index: number) => {+ setAgentIds(agentIds.filter((_, i) => i !== index));+ };++ const enableId = 'subagents-enable-toggle';+ const selfId = 'subagents-self-toggle';+ const nothingToSpawn = enabled && !allowSelf && agentIds.length === 0;++ return (+ <HoverCard openDelay={50}>+ <div className="flex items-center justify-between gap-2">+ <div className="flex items-center gap-2">+ <label htmlFor={enableId} className="font-semibold text-text-primary">+ {localize('com_ui_agent_subagents')}+ </label>+ <HoverCardTrigger>+ <CircleHelpIcon className="h-4 w-4 text-text-tertiary" />+ </HoverCardTrigger>+ </div>+ <div className="flex items-center gap-3">+ <div className="rounded-full border border-purple-600/40 bg-purple-500/10 px-2 py-0.5 text-xs font-medium text-purple-700 hover:bg-purple-700/10 dark:text-purple-400">+ {localize('com_ui_beta')}+ </div>+ <Switch+ id={enableId}+ checked={enabled}+ onCheckedChange={setEnabled}+ aria-label={localize('com_ui_agent_subagents_enable')}+ />+ </div>+ </div>++ {enabled && (+ <div className="mt-2 space-y-3">+ <div className="flex items-center justify-between gap-2 rounded-md border border-border-light bg-surface-primary p-3">+ <div className="flex flex-col">+ <label htmlFor={selfId} className="text-sm font-medium text-text-primary">+ {localize('com_ui_agent_subagents_allow_self')}+ </label>+ <span className="text-xs text-text-secondary">+ {localize('com_ui_agent_subagents_allow_self_info')}+ </span>+ </div>+ <Switch+ id={selfId}+ checked={allowSelf}+ onCheckedChange={setAllowSelf}+ aria-label={localize('com_ui_agent_subagents_allow_self')}+ />+ </div>++ <div className="space-y-1">+ <div className="flex items-center justify-between gap-2">+ <span className="text-xs font-medium text-text-secondary">+ {localize('com_ui_agent_subagents_agents')}+ </span>+ <span className="text-xs text-text-secondary">+ {agentIds.length} / {MAX_SUBAGENTS}+ </span>+ </div>++ {agentIds.map((agentId, idx) => {+ const details = getAgentDetails(agentId);+ return (+ <div+ key={agentId}+ className="flex h-9 items-center gap-2 rounded-md border border-border-medium bg-surface-tertiary pl-2 pr-2"+ >+ <div className="flex h-6 w-6 items-center justify-center overflow-hidden rounded-full">+ <MessageIcon+ message={+ {+ endpoint: EModelEndpoint.agents,+ isCreatedByUser: false,+ } as TMessage+ }+ agent={details}+ />+ </div>+ <div className="flex-1 truncate text-sm text-text-primary">+ {details?.name ?? agentId}+ </div>+ <button+ type="button"+ className="rounded-xl p-1 transition hover:bg-surface-hover"+ onClick={() => removeAgentAt(idx)}+ aria-label={localize('com_ui_agent_subagents_remove', {+ 0: details?.name ?? agentId,+ })}+ >+ <X size={18} className="text-text-secondary" aria-hidden="true" />+ </button>+ </div>+ );+ })}++ {agentIds.length < MAX_SUBAGENTS && (+ <ControlCombobox+ isCollapsed={false}+ ariaLabel={localize('com_ui_agent_subagents_add')}+ selectedValue=""+ setValue={setNewAgentId}+ selectPlaceholder={localize('com_ui_agent_subagents_add')}+ searchPlaceholder={localize('com_ui_agent_var', { 0: localize('com_ui_search') })}+ items={selectableAgents}+ className="h-9 w-full border-dashed border-border-heavy text-center text-text-secondary hover:text-text-primary"+ containerClassName="px-0"+ SelectIcon={<PlusCircle size={16} className="text-text-secondary" />}+ />+ )}++ {agentIds.length >= MAX_SUBAGENTS && (+ <p className="pt-1 text-center text-xs italic text-text-tertiary">+ {localize('com_ui_agent_subagents_max', { 0: MAX_SUBAGENTS })}+ </p>+ )}+ </div>++ {nothingToSpawn && (+ <p className="flex items-center gap-2 text-xs italic text-amber-600 dark:text-amber-400">+ <Users size={14} aria-hidden="true" />+ {localize('com_ui_agent_subagents_empty')}+ </p>+ )}+ </div>+ )}++ <HoverCardPortal>+ <HoverCardContent side={ESide.Top} className="w-80">+ <div className="space-y-2">+ <p className="text-sm text-text-secondary">{localize('com_ui_agent_subagents_info')}</p>+ <p className="text-sm text-text-secondary">+ {localize('com_ui_agent_subagents_info_2')}+ </p>+ </div>+ </HoverCardContent>+ </HoverCardPortal>+ </HoverCard>+ );+};++export default AgentSubagents;diff --git a/client/src/components/SidePanel/Agents/AgentPanel.tsx b/client/src/components/SidePanel/Agents/AgentPanel.tsxindex 6f1504440b..5096551b83 100644--- a/client/src/components/SidePanel/Agents/AgentPanel.tsx+++ b/client/src/components/SidePanel/Agents/AgentPanel.tsx@@ -69,6 +69,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | nprovider: _provider,agent_ids,edges,+ subagents,end_after_tools,hide_sequential_outputs,recursion_limit,@@ -96,6 +97,7 @@ export function composeAgentUpdatePayload(data: AgentForm, agent_id?: string | nmodel_parameters,agent_ids,edges,+ subagents,end_after_tools,hide_sequential_outputs,recursion_limit,diff --git a/client/src/components/SidePanel/Agents/AgentSelect.tsx b/client/src/components/SidePanel/Agents/AgentSelect.tsxindex 8c6291183a..1fbaa1f989 100644--- a/client/src/components/SidePanel/Agents/AgentSelect.tsx+++ b/client/src/components/SidePanel/Agents/AgentSelect.tsx@@ -120,6 +120,11 @@ function AgentSelect({return;}+ if (name === 'subagents' && typeof value === 'object' && value !== null) {+ formValues[name] = value;+ return;+ }+if (name === 'tool_options' && typeof value === 'object' && value !== null) {formValues[name] = value;return;diff --git a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts b/client/src/hooks/SSE/__tests__/useStepHandler.spec.tsindex 220d55704d..ae28a9e6f1 100644--- a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts+++ b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts@@ -1,5 +1,12 @@import { renderHook, act } from '@testing-library/react';-import { StepTypes, StepEvents, ContentTypes, ToolCallTypes } from 'librechat-data-provider';+import { RecoilRoot, useRecoilCallback } from 'recoil';+import {+ Constants,+ StepTypes,+ StepEvents,+ ContentTypes,+ ToolCallTypes,+} from 'librechat-data-provider';import type {TMessageContentParts,SummaryContentPart,@@ -7,9 +14,11 @@ import type {TEndpointOption,TConversation,TMessage,+ SubagentUpdateEvent,Agents,} from 'librechat-data-provider';import useStepHandler from '~/hooks/SSE/useStepHandler';+import { subagentProgressByToolCallId } from '~/store/subagents';type TSubmissionForTest = {userMessage: TMessage;@@ -1508,4 +1517,414 @@ describe('useStepHandler', () => {expect(mockSetMessages).not.toHaveBeenCalled();});});++ describe('on_subagent_update event', () => {+ /**+ * These tests exercise the real Recoil `atomFamily` via a `RecoilRoot`+ * wrapper and a `useRecoilCallback`-powered reader mounted alongside+ * the hook under test. No mocks of the store module — only the same+ * `setMessages`/`getMessages` spies the rest of this file uses.+ */+ const renderStepHandlerWithReader = (): {+ result: ReturnType<typeof renderHook>['result'];+ getProgress: (toolCallId: string) => unknown;+ } => {+ /** Composite hook: the step handler under test + a `useRecoilCallback`+ * reader that shares the same `RecoilRoot` store. Reading via a+ * top-level `snapshot_UNSTABLE()` returns a different root, so the+ * writes done by the step handler wouldn't be visible. */+ const hookResult = renderHook(+ () => {+ const stepHandler = useStepHandler(createHookParams());+ const read = useRecoilCallback(+ ({ snapshot }) =>+ (toolCallId: string): unknown =>+ snapshot.getLoadable(subagentProgressByToolCallId(toolCallId)).valueOrThrow(),+ [],+ );+ return { ...stepHandler, read };+ },+ { wrapper: RecoilRoot },+ );++ const getProgress = (toolCallId: string): unknown =>+ (hookResult.result.current as any).read(toolCallId);+ return { result: hookResult.result, getProgress };+ };++ const buildSubagentToolCallPart = (toolCallId: string): TMessageContentParts =>+ ({+ type: ContentTypes.TOOL_CALL,+ [ContentTypes.TOOL_CALL]: {+ id: toolCallId,+ name: Constants.SUBAGENT,+ args: '{}',+ type: ToolCallTypes.TOOL_CALL,+ progress: 0.1,+ },+ }) as unknown as TMessageContentParts;++ /**+ * Directly seed the hook's internal `messageMap` with a response message+ * whose content contains one or more `subagent` tool calls. Uses the+ * real `syncStepMessage` export so we exercise the same code path the+ * SSE pipeline uses for reconnects — no mocks, no patched internals.+ */+ const seedResponseWithSubagentToolCalls = (+ result: ReturnType<typeof renderHook>['result'],+ toolCallIds: string[],+ ): { response: TMessage; submission: EventSubmission } => {+ const response: TMessage = {+ ...createResponseMessage(),+ content: toolCallIds.map(buildSubagentToolCallPart),+ };+ mockGetMessages.mockReturnValue([response]);+ const submission = createSubmission({+ initialResponse: createResponseMessage({+ messageId: 'initial-response-id',+ }),+ });+ act(() => {+ (result.current as any).syncStepMessage(response);+ });+ return { response, submission };+ };++ const makeUpdate = (overrides: Partial<SubagentUpdateEvent> = {}): SubagentUpdateEvent => ({+ runId: 'parent-run',+ subagentRunId: 'child-run-1',+ subagentType: 'self',+ subagentAgentId: 'child-1',+ parentAgentId: 'parent',+ phase: 'start',+ label: 'Subagent "self" started',+ timestamp: new Date().toISOString(),+ ...overrides,+ });++ it('correlates updates to a tool call via parentToolCallId (deterministic path)', () => {+ const { result, getProgress } = renderStepHandlerWithReader();+ const { submission } = seedResponseWithSubagentToolCalls(result, ['call_A']);++ const start = makeUpdate({ parentToolCallId: 'call_A', phase: 'start' });+ const step = makeUpdate({+ parentToolCallId: 'call_A',+ phase: 'run_step',+ label: 'Using tool: calculator',+ });+ const stop = makeUpdate({+ parentToolCallId: 'call_A',+ phase: 'stop',+ label: 'Subagent "self" finished',+ });++ act(() => {+ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: start },+ submission,+ );++ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: step },+ submission,+ );++ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: stop },+ submission,+ );+ });++ const bucket = getProgress('call_A') as {+ status: string;+ latestLabel?: string;+ subagentType: string;+ };+ /** The atom no longer retains raw envelopes — they're folded+ * incrementally into `contentParts`/`tickerState`. Metadata+ * (status, latestLabel, subagentType) still reflects the last+ * update, which is what the UI actually renders from. */+ expect(bucket.status).toBe('stop');+ expect(bucket.latestLabel).toBe('Subagent "self" finished');+ expect(bucket.subagentType).toBe('self');+ });++ it('falls back to oldest-unclaimed tool call when parentToolCallId is absent', () => {+ const { result, getProgress } = renderStepHandlerWithReader();+ /** Two subagent tool calls seeded in creation order. Without+ * `parentToolCallId`, forward iteration must claim `call_old` for+ * the first start and `call_new` for the second. */+ const { submission } = seedResponseWithSubagentToolCalls(result, ['call_old', 'call_new']);++ const updateOld = makeUpdate({+ subagentRunId: 'run-1',+ phase: 'start',+ label: 'first',+ });+ const updateNew = makeUpdate({+ subagentRunId: 'run-2',+ phase: 'start',+ label: 'second',+ });++ act(() => {+ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: updateOld },+ submission,+ );++ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: updateNew },+ submission,+ );+ });++ const first = getProgress('call_old') as { latestLabel?: string };+ const second = getProgress('call_new') as { latestLabel?: string };+ expect(first.latestLabel).toBe('first');+ expect(second.latestLabel).toBe('second');+ });++ it('buffers early-arriving updates and replays once a tool call is claimable', () => {+ const { result, getProgress } = renderStepHandlerWithReader();+ const submission = createSubmission({+ initialResponse: createResponseMessage({+ messageId: 'initial-response-id',+ }),+ });+ /** Deliberately: no `mockGetMessages.mockReturnValue([response])`+ * and no ON_RUN_STEP yet, so the tool call isn't visible. The+ * first envelope must be buffered. */+ mockGetMessages.mockReturnValue([]);++ const earlyUpdate = makeUpdate({+ phase: 'start',+ label: 'arrives first',+ });+ const laterUpdate = makeUpdate({+ phase: 'run_step',+ label: 'arrives after correlation',+ });++ act(() => {+ (result.current as any).stepHandler(+ { event: StepEvents.ON_SUBAGENT_UPDATE, data: earlyUpdate },+ submission,+ );+ });++ /** Now the tool call appears. Subsequent update can claim and drain. */+ const responseWithToolCall: TMessage = {+ ...createResponseMessage(),+ content: [buildSubagentToolCallPart('call_late')],+ };+ mockGetMessages.mockReturnValue([responseWithToolCall]);+ act(() => {+ (result.current as any).syncStepMessage(responseWithToolCall);+ });++ act(() => {+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: { ...laterUpdate, parentToolCallId: 'call_late' },+ },+ submission,+ );+ });++ const bucket = getProgress('call_late') as {+ status: string;+ latestLabel?: string;+ };+ /** The buffered `start` event and the current `run_step` both+ * get applied in order — the latest label reflects the most+ * recently processed envelope. */+ expect(bucket.status).toBe('run_step');+ expect(bucket.latestLabel).toBe('arrives after correlation');+ });++ it('keeps atom state bounded under a large burst of lifecycle-only updates', () => {+ /** Previously the atom retained a 200-event rolling window so long+ * runs could lose earlier tool_call records. We now fold events+ * into `contentParts` + `tickerState` incrementally — no raw+ * event array is stored, so memory is bounded by the structural+ * output (text/reasoning runs + tool calls), not delta volume.+ * A pile of pass-through phases like `run_step_delta` must not+ * create lines at all. */+ const { result, getProgress } = renderStepHandlerWithReader();+ const { submission } = seedResponseWithSubagentToolCalls(result, ['call_cap']);++ act(() => {+ for (let i = 0; i < 500; i++) {+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeUpdate({+ parentToolCallId: 'call_cap',+ phase: 'run_step_delta',+ label: `delta-${i}`,+ }),+ },+ submission,+ );+ }+ });++ const bucket = getProgress('call_cap') as {+ contentParts: unknown[];+ tickerState: { lines: unknown[] };+ latestLabel?: string;+ };+ expect(bucket.contentParts).toEqual([]);+ expect(bucket.tickerState.lines).toEqual([]);+ expect(bucket.latestLabel).toBe('delta-499');+ });++ it('keeps parallel subagent streams independent when events interleave', () => {+ /**+ * Parallel tool calls: the LLM emits two `subagent` tool calls in the+ * same AIMessage, LangChain invokes them concurrently, and the SDK+ * streams `ON_SUBAGENT_UPDATE` envelopes for both runs in arbitrary+ * order. Each envelope carries `parentToolCallId` (SDK dev.2+), so+ * correlation stays deterministic. Verify no cross-contamination+ * between buckets: each tool_call_id's atom should accumulate only+ * that run's events, and closing one stream must not affect the+ * other.+ */+ const { result, getProgress } = renderStepHandlerWithReader();+ const { submission } = seedResponseWithSubagentToolCalls(result, ['call_a', 'call_b']);++ const makeParallelUpdate = (+ runId: string,+ toolCallId: string,+ overrides: Partial<SubagentUpdateEvent> = {},+ ): SubagentUpdateEvent => ({+ ...makeUpdate({ subagentRunId: runId, parentToolCallId: toolCallId }),+ ...overrides,+ });++ act(() => {+ // Interleaved order: a-start, b-start, a-step, b-step, a-stop, b-stop+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_a', 'call_a', {+ phase: 'start',+ label: 'A started',+ }),+ },+ submission,+ );+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_b', 'call_b', {+ phase: 'start',+ label: 'B started',+ }),+ },+ submission,+ );+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_a', 'call_a', {+ phase: 'run_step',+ label: 'A using calculator',+ }),+ },+ submission,+ );+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_b', 'call_b', {+ phase: 'run_step',+ label: 'B using web',+ }),+ },+ submission,+ );+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_a', 'call_a', {+ phase: 'stop',+ label: 'A done',+ }),+ },+ submission,+ );+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeParallelUpdate('run_b', 'call_b', {+ phase: 'run_step',+ label: 'B still going',+ }),+ },+ submission,+ );+ });++ const bucketA = getProgress('call_a') as {+ subagentRunId: string;+ status: string;+ latestLabel?: string;+ };+ const bucketB = getProgress('call_b') as {+ subagentRunId: string;+ status: string;+ latestLabel?: string;+ };++ /** Each bucket only captures its own run's lifecycle — metadata+ * (status, latestLabel, subagentRunId) stays scoped to the+ * matching tool_call_id despite interleaved delivery order. */+ expect(bucketA.subagentRunId).toBe('run_a');+ expect(bucketB.subagentRunId).toBe('run_b');+ expect(bucketA.latestLabel).toBe('A done');+ expect(bucketB.latestLabel).toBe('B still going');++ // A reached `stop`, B is still running — their statuses should reflect that+ expect(bucketA.status).toBe('stop');+ expect(bucketB.status).toBe('run_step');+ });++ it('clearStepMaps preserves subagent atoms so the dialog can be re-opened for auditability', () => {+ /**+ * Intentionally the inverse of the earlier behavior: the collapsed+ * `SubagentCall` ticker and its dialog must stay readable after the+ * stream ends. Wiping the atoms on `clearStepMaps` would leave a+ * completed subagent tool call with no content to display, forcing+ * the fallback "raw tool output" branch and losing interleaved tool+ * calls / reasoning from the rendering. Growth is bounded (200-event+ * cap per atom, one atom per subagent spawn).+ */+ const { result, getProgress } = renderStepHandlerWithReader();+ const { submission } = seedResponseWithSubagentToolCalls(result, ['call_keep']);++ act(() => {+ (result.current as any).stepHandler(+ {+ event: StepEvents.ON_SUBAGENT_UPDATE,+ data: makeUpdate({+ parentToolCallId: 'call_keep',+ phase: 'stop',+ }),+ },+ submission,+ );+ });++ expect(getProgress('call_keep')).not.toBeNull();++ act(() => {+ (result.current as any).clearStepMaps();+ });++ expect(getProgress('call_keep')).not.toBeNull();+ });+ });});diff --git a/client/src/hooks/SSE/useEventHandlers.ts b/client/src/hooks/SSE/useEventHandlers.tsindex 2759fb0527..e696eefa84 100644--- a/client/src/hooks/SSE/useEventHandlers.ts+++ b/client/src/hooks/SSE/useEventHandlers.ts@@ -1,4 +1,4 @@-import { useCallback, useRef } from 'react';+import { useCallback, useEffect, useRef } from 'react';import { v4 } from 'uuid';import { useSetRecoilState } from 'recoil';import { useQueryClient } from '@tanstack/react-query';@@ -188,7 +188,7 @@ export default function useEventHandlers({const { token } = useAuthContext();const { contentHandler, resetContentHandler } = useContentHandler({ setMessages, getMessages });- const { stepHandler, clearStepMaps, syncStepMessage } = useStepHandler({+ const { stepHandler, clearStepMaps, resetSubagentAtoms, syncStepMessage } = useStepHandler({setMessages,getMessages,announcePolite,@@ -197,6 +197,47 @@ export default function useEventHandlers({});const attachmentHandler = useAttachmentHandler(queryClient);+ /** Wipe the per-subagent Recoil atoms on conversation navigation.+ * Historical subagent dialogs rehydrate from the persisted+ * `subagent_content` on each `tool_call` (written by the backend+ * at message-save time), so clearing live atoms on switch+ * doesn't lose any viewable history — it just keeps `atomFamily`+ * bounded across multi-conversation sessions.+ *+ * Rule: only reset when transitioning AWAY FROM an established+ * conversation (`previous != null`). Transitions FROM null or+ * undefined pass through:+ * - initial mount on a new-chat route: nothing to clear.+ * - new-chat URL stamp mid-stream (null → newId): the in-flight+ * subagent ticker/content state for that freshly-stamped id+ * would be wiped if we reset here — that id IS the current+ * run, not a stale one.+ * Cases that DO reset (previous non-null, value changed):+ * - id1 → id2 (switching between established chats)+ * - id → null (user clicked "new chat")+ * - id → undefined (route teardown / navigate away) */+ const lastConversationIdRef = useRef<string | null | undefined>(paramId);+ useEffect(() => {+ const previous = lastConversationIdRef.current;+ lastConversationIdRef.current = paramId;+ if (previous != null && previous !== paramId) {+ resetSubagentAtoms();+ }+ }, [paramId, resetSubagentAtoms]);++ /** Final cleanup on component unmount. `useStepHandler` keeps the+ * set of known atom keys in a ref; when the hook unmounts (user+ * navigates away from the chat route entirely) that ref is lost,+ * so a subsequent remount can't clear atoms it never saw created.+ * Flush at the teardown boundary to keep `atomFamily` bounded+ * across route changes. */+ useEffect(+ () => () => {+ resetSubagentAtoms();+ },+ [resetSubagentAtoms],+ );+const messageHandler = useCallback((data: string | undefined, submission: EventSubmission) => {const { messages, userMessage, initialResponse, isRegenerate = false } = submission;diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.tsindex 1f28d97433..e4c6283269 100644--- a/client/src/hooks/SSE/useStepHandler.ts+++ b/client/src/hooks/SSE/useStepHandler.ts@@ -1,4 +1,5 @@import { useCallback, useRef } from 'react';+import { useRecoilCallback } from 'recoil';import {Constants,StepTypes,@@ -15,10 +16,18 @@ import type {EventSubmission,SummaryContentPart,TMessageContentParts,+ SubagentUpdateEvent,} from 'librechat-data-provider';import type { SetterOrUpdater } from 'recoil';import type { AnnounceOptions } from '~/common';import { MESSAGE_UPDATE_INTERVAL } from '~/common';+import { subagentProgressByToolCallId } from '~/store';+import {+ foldSubagentEvent,+ foldSubagentEventIntoTicker,+ initSubagentAggregatorState,+ initSubagentTickerState,+} from '~/utils/subagentContent';type TUseStepHandler = {announcePolite: (options: AnnounceOptions) => void;@@ -38,7 +47,8 @@ type TStepEvent =| { event: StepEvents.ON_RUN_STEP_COMPLETED; data: { result: Agents.ToolEndEvent } }| { event: StepEvents.ON_SUMMARIZE_START; data: Agents.SummarizeStartEvent }| { event: StepEvents.ON_SUMMARIZE_DELTA; data: Agents.SummarizeDeltaEvent }- | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent };+ | { event: StepEvents.ON_SUMMARIZE_COMPLETE; data: Agents.SummarizeCompleteEvent }+ | { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent };type MessageDeltaUpdate = { type: ContentTypes.TEXT; text: string; tool_call_ids?: string[] };@@ -66,6 +76,157 @@ export default function useStepHandler({const pendingDeltaBuffer = useRef(new Map<string, TStepEvent[]>());/** Coalesces rapid-fire summarize delta renders into a single rAF frame */const summarizeDeltaRaf = useRef<number | null>(null);+ /**+ * Maps `SubagentUpdateEvent.subagentRunId` → parent `tool_call_id`.+ * Preferred source is `payload.parentToolCallId` (threaded through by the+ * SDK from `ToolRunnableConfig.toolCall.id`, deterministic). If a host+ * runs an older SDK that doesn't emit it, we fall back to a temporal+ * claim: the OLDEST unclaimed `subagent` tool call in the active message.+ * Forward (oldest-first) iteration matches the order tool calls are+ * created in, so concurrent spawns map in creation order.+ */+ const subagentRunToToolCallId = useRef(new Map<string, string>());+ const claimedSubagentToolCallIds = useRef(new Set<string>());+ /**+ * Buffers for envelopes that arrive before their `subagent` tool call is+ * reflected in `messageMap`. Keyed by `subagentRunId`. Once a tool call is+ * claimed we drain the buffer into the Recoil atom in arrival order.+ */+ const pendingSubagentBuffer = useRef(new Map<string, SubagentUpdateEvent[]>());+ /**+ * Tracked atom keys so `clearStepMaps` can reset them. Without this, each+ * subagent invocation leaks an `events: SubagentUpdateEvent[]` array in the+ * `atomFamily` — atoms persist for the app lifetime.+ */+ const knownSubagentAtomKeys = useRef(new Set<string>());++ /** Both content parts and ticker lines are aggregated incrementally+ * into the atom as each `ON_SUBAGENT_UPDATE` arrives — we never+ * retain the raw event array, so no rolling window is needed. A+ * talkative subagent can emit thousands of deltas without growing+ * memory past what the structural output requires. */++ /**+ * Attempts to resolve the parent `tool_call_id` for a subagent run, using+ * the SDK-provided `parentToolCallId` first and falling back to an+ * oldest-unclaimed temporal claim.+ */+ const resolveSubagentToolCallId = useCallback(+ (payload: SubagentUpdateEvent): string | undefined => {+ const cached = subagentRunToToolCallId.current.get(payload.subagentRunId);+ if (cached != null) return cached;++ if (payload.parentToolCallId) {+ subagentRunToToolCallId.current.set(payload.subagentRunId, payload.parentToolCallId);+ claimedSubagentToolCallIds.current.add(payload.parentToolCallId);+ return payload.parentToolCallId;+ }++ // Fallback — oldest unclaimed subagent tool call wins.+ for (const message of messageMap.current.values()) {+ const content = message.content;+ if (!Array.isArray(content)) continue;+ for (let i = 0; i < content.length; i++) {+ const part = content[i];+ if (part?.type !== ContentTypes.TOOL_CALL) continue;+ const tc = (part as { [ContentTypes.TOOL_CALL]?: { id?: string; name?: string } })[+ ContentTypes.TOOL_CALL+ ];+ if (+ tc?.name === Constants.SUBAGENT &&+ tc.id &&+ !claimedSubagentToolCallIds.current.has(tc.id)+ ) {+ subagentRunToToolCallId.current.set(payload.subagentRunId, tc.id);+ claimedSubagentToolCallIds.current.add(tc.id);+ return tc.id;+ }+ }+ }++ return undefined;+ },+ [],+ );++ /**+ * Merges an incoming {@link SubagentUpdateEvent} into the Recoil atom bucket+ * keyed by the parent `tool_call_id`. Buffers early-arriving events whose+ * tool call is not yet mapped, and replays the buffer once correlation+ * completes.+ */+ const applySubagentUpdate = useRecoilCallback(+ ({ set }) =>+ (payload: SubagentUpdateEvent): void => {+ const toolCallId = resolveSubagentToolCallId(payload);++ if (!toolCallId) {+ const queue = pendingSubagentBuffer.current.get(payload.subagentRunId) ?? [];+ queue.push(payload);+ pendingSubagentBuffer.current.set(payload.subagentRunId, queue);+ return;+ }++ const buffered = pendingSubagentBuffer.current.get(payload.subagentRunId);+ if (buffered && buffered.length > 0) {+ pendingSubagentBuffer.current.delete(payload.subagentRunId);+ }+ const toApply = buffered ? [...buffered, payload] : [payload];++ knownSubagentAtomKeys.current.add(toolCallId);+ set(subagentProgressByToolCallId(toolCallId), (prev) => {+ /** Fold the batch into both aggregators. Pure functions — they+ * return a new reference only when something actually changed,+ * so React bails out of unnecessary re-renders downstream. */+ let contentParts = prev?.contentParts ?? [];+ let aggregatorState = prev?.aggregatorState ?? initSubagentAggregatorState();+ let tickerState = prev?.tickerState ?? initSubagentTickerState();+ for (const event of toApply) {+ ({ parts: contentParts, state: aggregatorState } = foldSubagentEvent(+ contentParts,+ aggregatorState,+ event,+ ));+ tickerState = foldSubagentEventIntoTicker(tickerState, event);+ }++ const last = toApply[toApply.length - 1];+ return {+ subagentRunId: payload.subagentRunId,+ subagentType: payload.subagentType,+ subagentAgentId: payload.subagentAgentId ?? prev?.subagentAgentId,+ contentParts,+ aggregatorState,+ tickerState,+ status: last.phase,+ latestLabel: last.label ?? prev?.latestLabel,+ };+ });+ },+ [resolveSubagentToolCallId],+ );++ /**+ * Resets all accumulated subagent Recoil state. Kept for conversation-+ * switch cleanup (see top-level hook usage) but NOT called from+ * `clearStepMaps` — the collapsed SubagentCall ticker and its dialog+ * read from these atoms to render the child's content parts, and we+ * want that history to remain visible after the stream ends so the+ * user can reopen the dialog for auditability. The atoms are bounded+ * per-call (200-event cap) and per-conversation (one atom per+ * subagent spawn), so growth is proportional to messages — the same+ * growth profile as the rest of the conversation state.+ */+ const resetSubagentAtoms = useRecoilCallback(+ ({ reset }) =>+ (): void => {+ for (const toolCallId of knownSubagentAtomKeys.current) {+ reset(subagentProgressByToolCallId(toolCallId));+ }+ knownSubagentAtomKeys.current.clear();+ },+ [],+ );/*** Calculate content index for a run step.@@ -612,6 +773,8 @@ export default function useStepHandler({setMessages(updatedMessages);}+ } else if (stepEvent.event === StepEvents.ON_SUBAGENT_UPDATE) {+ applySubagentUpdate(stepEvent.data);} else if (stepEvent.event === StepEvents.ON_SUMMARIZE_START) {announcePolite({ message: 'summarize_started', isStatus: true });} else if (stepEvent.event === StepEvents.ON_SUMMARIZE_DELTA) {@@ -714,7 +877,14 @@ export default function useStepHandler({console.warn('Unhandled step event', (_exhaustive as TStepEvent).event);}},- [getMessages, lastAnnouncementTimeRef, announcePolite, setMessages, calculateContentIndex],+ [+ getMessages,+ lastAnnouncementTimeRef,+ announcePolite,+ setMessages,+ calculateContentIndex,+ applySubagentUpdate,+ ],);const clearStepMaps = useCallback(() => {@@ -726,6 +896,17 @@ export default function useStepHandler({messageMap.current.clear();stepMap.current.clear();pendingDeltaBuffer.current.clear();+ subagentRunToToolCallId.current.clear();+ claimedSubagentToolCallIds.current.clear();+ pendingSubagentBuffer.current.clear();+ /** Intentionally NOT calling `resetSubagentAtoms()` here — users need+ * to be able to reopen the SubagentCall dialog after completion to+ * audit what the child did. `resetSubagentAtoms` is returned below+ * so callers can wipe atoms on conversation-switch (see+ * `useEventHandlers`) — that's the correct cleanup boundary:+ * persisted `subagent_content` takes over for historical messages+ * once the conversation is saved, and we prevent unbounded+ * atomFamily growth across multi-conversation sessions. */}, []);/**@@ -739,5 +920,5 @@ export default function useStepHandler({}}, []);- return { stepHandler, clearStepMaps, syncStepMessage };+ return { stepHandler, clearStepMaps, resetSubagentAtoms, syncStepMessage };}diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex b61f4bc6a6..6a17f85260 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -699,6 +699,33 @@"com_ui_agent_handoff_prompt_key_placeholder": "Label the content passed (default: 'instructions')","com_ui_agent_handoff_prompt_placeholder": "Tell this agent what content to generate and pass to the handoff agent. You need to add something here to enable this feature","com_ui_agent_handoffs": "Agent Handoffs",+ "com_ui_agent_subagents": "Subagents",+ "com_ui_agent_subagents_enable": "Enable subagents",+ "com_ui_agent_subagents_allow_self": "Allow self-spawn",+ "com_ui_agent_subagents_allow_self_info": "Let this agent delegate focused subtasks to a copy of itself in an isolated context window.",+ "com_ui_agent_subagents_agents": "Additional subagents",+ "com_ui_agent_subagents_add": "Add subagent",+ "com_ui_agent_subagents_remove": "Remove {{0}} from subagents",+ "com_ui_agent_subagents_max": "Maximum {{0}} subagents reached.",+ "com_ui_agent_subagents_empty": "No subagents available: enable self-spawn or add at least one agent.",+ "com_ui_agent_subagents_info": "Subagents run in isolated context windows. Verbose tool output stays scoped to the child; only a summary returns to this agent.",+ "com_ui_agent_subagents_info_2": "Enabling with no agents listed still allows self-spawn, so this agent can delegate focused subtasks to a fresh copy of itself.",+ "com_ui_subagent_running": "Running agent",+ "com_ui_subagent_complete": "Ran agent",+ "com_ui_subagent_cancelled": "Cancelled agent",+ "com_ui_subagent_errored": "Agent errored",+ "com_ui_subagent_ticker_writing": "Writing",+ "com_ui_subagent_ticker_reasoning": "Reasoning",+ "com_ui_subagent_ticker_error": "Error",+ "com_ui_subagent_ticker_using": "Using",+ "com_ui_subagent_ticker_tool_done": "done",+ "com_ui_subagent_waiting": "Waiting for first update…",+ "com_ui_subagent_dialog_title": "\"{{0}}\" agent",+ "com_ui_subagent_dialog_title_self": "Agent",+ "com_ui_subagent_dialog_description": "Isolated-context child run. Activity and final result below.",+ "com_ui_subagent_no_result_yet": "Still running — no final result yet.",+ "com_ui_subagent_empty_result": "No text returned.",+ "com_ui_subagent_scroll_to_bottom": "Scroll to latest","com_ui_agent_description": "Agent description","com_ui_agent_name": "Agent name","com_ui_agent_name_is_required": "Agent name is required",@@ -1624,6 +1651,8 @@"com_ui_use_prompt": "Use Prompt","com_ui_used": "Used","com_ui_used_n_tools": "Used {{0}} tools",+ "com_ui_running_n_agents": "Running {{0}} agents",+ "com_ui_ran_n_agents": "Ran {{0}} agents","com_ui_user": "User","com_ui_user_group_permissions": "User & Group Permissions","com_ui_user_provides_key": "Each user provides their own key",diff --git a/client/src/store/index.ts b/client/src/store/index.tsindex 25d721e65b..0584e9d805 100644--- a/client/src/store/index.ts+++ b/client/src/store/index.ts@@ -15,6 +15,7 @@ import isTemporary from './temporary';export * from './agents';export * from './mcp';export * from './favorites';+export * from './subagents';export default {...artifacts,diff --git a/client/src/store/subagents.ts b/client/src/store/subagents.tsnew file mode 100644index 0000000000..cf243a8c03--- /dev/null+++ b/client/src/store/subagents.ts@@ -0,0 +1,47 @@+import { atomFamily } from 'recoil';+import type { SubagentUpdatePhase } from 'librechat-data-provider';+import type {+ SubagentAggregatorState,+ SubagentContentPart,+ SubagentTickerState,+} from '~/utils/subagentContent';++/**+ * Progress bucket captured per subagent tool call. Populated as+ * `ON_SUBAGENT_UPDATE` SSE events stream in from the backend. Keyed by the+ * parent's `tool_call_id` so the `SubagentCall` renderer can look the bucket+ * up from the tool call it's rendering.+ *+ * Both the dialog content and the ticker are aggregated *incrementally*+ * into the atom as each envelope arrives — the atom never keeps the raw+ * event array. A long-running subagent can emit thousands of deltas+ * without the state growing past what its structural output (N text+ * runs + M tool calls + a bounded tail preview) needs.+ */+export interface SubagentProgress {+ /** Child run id from the SDK — unique per spawn; one tool_call may only have one. */+ subagentRunId: string;+ /** `type` identifier from the SubagentConfig (e.g. 'self', 'researcher'). */+ subagentType: string;+ /** Child agent id (for avatar / name lookup in the ticker header). */+ subagentAgentId?: string;+ /**+ * Fully aggregated child content parts. Bounded by structure (text+ * runs + reasoning runs + tool calls), not by delta volume.+ */+ contentParts: SubagentContentPart[];+ /** Cursor carried across `foldSubagentEvent` calls. */+ aggregatorState: SubagentAggregatorState;+ /** Ticker lines + live-cursor state, built incrementally. */+ tickerState: SubagentTickerState;+ /** Current lifecycle phase — drives the header "running" / "done" state. */+ status: SubagentUpdatePhase;+ /** Convenience: last event's `label` for quick ticker display. */+ latestLabel?: string;+}++/** Progress state keyed by parent tool_call_id. */+export const subagentProgressByToolCallId = atomFamily<SubagentProgress | null, string>({+ key: 'subagentProgressByToolCallId',+ default: null,+});diff --git a/client/src/utils/__tests__/subagentContent.test.ts b/client/src/utils/__tests__/subagentContent.test.tsnew file mode 100644index 0000000000..35ef518e40--- /dev/null+++ b/client/src/utils/__tests__/subagentContent.test.ts@@ -0,0 +1,472 @@+import { ContentTypes } from 'librechat-data-provider';+import type { SubagentUpdateEvent } from 'librechat-data-provider';+import { aggregateSubagentContent, buildSubagentTickerLines } from '../subagentContent';++const makeEvent = (overrides: Partial<SubagentUpdateEvent>): SubagentUpdateEvent => ({+ runId: 'parent-run',+ subagentRunId: 'child-run',+ subagentType: 'self',+ subagentAgentId: 'child',+ parentAgentId: 'parent',+ phase: 'start',+ timestamp: '2026-04-17T00:00:00Z',+ ...overrides,+});++describe('aggregateSubagentContent', () => {+ it('returns empty array for no events', () => {+ expect(aggregateSubagentContent([])).toEqual([]);+ });++ it('concatenates adjacent message_delta chunks into a single TEXT part', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Hello ' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'world' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: '!' }] } },+ }),+ ]);+ expect(parts).toEqual([{ type: ContentTypes.TEXT, text: 'Hello world!' }]);+ });++ it('concatenates reasoning_delta chunks into a single THINK part', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Let me ' }] } },+ }),+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'compute…' }] } },+ }),+ ]);+ expect(parts).toEqual([{ type: ContentTypes.THINK, think: 'Let me compute…' }]);+ });++ it('creates a TOOL_CALL part for each unique tool_call id on run_step', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [+ { id: 'call_1', name: 'calculator', args: '{"expression":"1+1"}' },+ { id: 'call_2', name: 'web_search', args: '{"query":"x"}' },+ ],+ },+ },+ }),+ ]);+ expect(parts).toHaveLength(2);+ expect((parts[0] as { tool_call: { name: string; progress: number } }).tool_call.name).toBe(+ 'calculator',+ );+ expect((parts[1] as { tool_call: { name: string; progress: number } }).tool_call.name).toBe(+ 'web_search',+ );+ expect((parts[0] as { tool_call: { progress: number } }).tool_call.progress).toBe(0.1);+ });++ it('finalizes a TOOL_CALL part on run_step_completed with output and progress=1', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'call_1', name: 'calculator', args: '{}' }],+ },+ },+ }),+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: {+ id: 'call_1',+ name: 'calculator',+ args: '{"expression":"1+1"}',+ output: '1+1 = 2',+ progress: 1,+ },+ },+ },+ }),+ ]);+ expect(parts).toHaveLength(1);+ const tc = (parts[0] as { tool_call: { output?: string; progress: number } }).tool_call;+ expect(tc.output).toBe('1+1 = 2');+ expect(tc.progress).toBe(1);+ });++ it('interleaves tool calls between text parts in order', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Computing…' }] } },+ }),+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator', args: '{}' }],+ },+ },+ }),+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'calculator', output: '4', progress: 1 },+ },+ },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'The answer is 4.' }] } },+ }),+ ]);+ expect(parts).toHaveLength(3);+ expect((parts[0] as { type: string }).type).toBe(ContentTypes.TEXT);+ expect((parts[1] as { type: string }).type).toBe(ContentTypes.TOOL_CALL);+ expect((parts[2] as { type: string }).type).toBe(ContentTypes.TEXT);+ expect((parts[2] as { text: string }).text).toBe('The answer is 4.');+ });++ it('ignores start, stop, error, and run_step_delta phases', () => {+ const parts = aggregateSubagentContent([+ makeEvent({ phase: 'start' }),+ makeEvent({ phase: 'run_step_delta' }),+ makeEvent({ phase: 'stop' }),+ makeEvent({ phase: 'error', data: { message: 'boom' } }),+ ]);+ expect(parts).toEqual([]);+ });++ it('preserves chronological order when reasoning and text arrive interleaved (ordering regression)', () => {+ /**+ * Before the delta-type-switch close, a run where the LLM emitted+ * reasoning FIRST, then text, then a tool call would flush both+ * buffers at the tool_call boundary in a fixed (text, think) order —+ * landing text BEFORE think in the content array even though the+ * user observed reasoning first. Fix: when a text chunk arrives+ * close any open think buffer first, and vice versa.+ */+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Let me think.' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Sure!' }] } },+ }),+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator', args: '{}' }],+ },+ },+ }),+ ]);+ expect(parts).toHaveLength(3);+ expect((parts[0] as { type: string; think?: string }).type).toBe(ContentTypes.THINK);+ expect((parts[0] as { think: string }).think).toBe('Let me think.');+ expect((parts[1] as { type: string; text?: string }).type).toBe(ContentTypes.TEXT);+ expect((parts[1] as { text: string }).text).toBe('Sure!');+ expect((parts[2] as { type: string }).type).toBe(ContentTypes.TOOL_CALL);+ });++ it('handles repeated reasoning → text → reasoning flows across a turn', () => {+ /** Second pattern from the screenshot: reasoning before the final+ * text, and the completed run still ending with streaming text.+ * A new reasoning after a text streak should appear AFTER the text,+ * not before. */+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Pre-thinking.' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'First draft.' }] } },+ }),+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Post-thinking.' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Final.' }] } },+ }),+ ]);+ expect(parts.map((p) => (p as { type: string }).type)).toEqual([+ ContentTypes.THINK,+ ContentTypes.TEXT,+ ContentTypes.THINK,+ ContentTypes.TEXT,+ ]);+ expect((parts[0] as { think: string }).think).toBe('Pre-thinking.');+ expect((parts[1] as { text: string }).text).toBe('First draft.');+ expect((parts[2] as { think: string }).think).toBe('Post-thinking.');+ expect((parts[3] as { text: string }).text).toBe('Final.');+ });++ it('handles a run_step_completed without a preceding run_step (late arrival)', () => {+ const parts = aggregateSubagentContent([+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'web', output: 'x', progress: 1 },+ },+ },+ }),+ ]);+ expect(parts).toHaveLength(1);+ const tc = (parts[0] as { tool_call: { output?: string } }).tool_call;+ expect(tc.output).toBe('x');+ });+});++describe('buildSubagentTickerLines', () => {+ it('returns empty array when no meaningful events are present', () => {+ expect(+ buildSubagentTickerLines([+ makeEvent({ phase: 'start' }),+ makeEvent({ phase: 'run_step_delta' }),+ makeEvent({ phase: 'stop' }),+ ]),+ ).toEqual([]);+ });++ it('produces a single writing line whose body extends as deltas arrive', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Hello ' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'world' }] } },+ }),+ ]);+ expect(lines).toHaveLength(1);+ expect(lines[0]).toEqual({ kind: 'writing', body: 'Hello world' });+ });++ it('truncates the writing body to the tail when it grows past the cap', () => {+ const longText = 'x'.repeat(1000);+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: longText }] } },+ }),+ ]);+ expect(lines).toHaveLength(1);+ expect(lines[0].kind).toBe('writing');+ const body = (lines[0] as { body: string }).body;+ /** No data-level ellipsis prefix — the component's CSS tail-ellipsis+ * (`dir="rtl"` + `text-overflow: ellipsis`) handles the visual cue+ * on overflow. Prepending one in data would stack a visible dot+ * right after the "Writing:" label even when the body fits the+ * container. */+ expect(body.startsWith('…')).toBe(false);+ expect(body.length).toBe(300);+ });++ it('emits using_tool + tool_complete lines', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator' }],+ },+ },+ }),+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'calculator', output: '42*58 = 2436', progress: 1 },+ },+ },+ }),+ ]);+ expect(lines).toEqual([+ { kind: 'using_tool', toolNames: ['calculator'] },+ { kind: 'tool_complete', toolName: 'calculator', outputSnippet: '42*58 = 2436' },+ ]);+ });++ it('includes an args snippet for single tool_calls and drops it for parallel', () => {+ const single = buildSubagentTickerLines([+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator', args: '{"expression":"42*58"}' }],+ },+ },+ }),+ ]);+ expect(single[0]).toEqual({+ kind: 'using_tool',+ toolNames: ['calculator'],+ argsSnippet: 'expression=42*58',+ });++ const parallel = buildSubagentTickerLines([+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [+ { id: 'c1', name: 'calculator', args: '{"expression":"42*58"}' },+ { id: 'c2', name: 'web_search', args: '{"query":"weather"}' },+ ],+ },+ },+ }),+ ]);+ expect(parallel[0]).toEqual({+ kind: 'using_tool',+ toolNames: ['calculator', 'web_search'],+ });+ });++ it('truncates long tool output to a 48-char head snippet', () => {+ const bigOutput = 'x'.repeat(500);+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'reader', output: bigOutput, progress: 1 },+ },+ },+ }),+ ]);+ expect(lines[0].kind).toBe('tool_complete');+ const snippet = (lines[0] as { outputSnippet?: string }).outputSnippet ?? '';+ expect(snippet).toMatch(/^x+…$/);+ /** 48-char head + trailing ellipsis. */+ expect(snippet.length).toBe(49);+ });++ it('omits outputSnippet when output is empty', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'run_step_completed',+ data: {+ result: {+ type: 'tool_call',+ tool_call: { id: 'c1', name: 'noop', output: '', progress: 1 },+ },+ },+ }),+ ]);+ expect(lines[0]).toEqual({ kind: 'tool_complete', toolName: 'noop' });+ });++ it('closes a streaming line when a tool call arrives so subsequent deltas start fresh', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'I will compute' }] } },+ }),+ makeEvent({+ phase: 'run_step',+ data: {+ stepDetails: {+ type: 'tool_calls',+ tool_calls: [{ id: 'c1', name: 'calculator' }],+ },+ },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Result: 4' }] } },+ }),+ ]);+ expect(lines).toEqual([+ { kind: 'writing', body: 'I will compute' },+ { kind: 'using_tool', toolNames: ['calculator'] },+ { kind: 'writing', body: 'Result: 4' },+ ]);+ });++ it('distinguishes reasoning from writing', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Step 1' }] } },+ }),+ ]);+ expect(lines[0]).toEqual({ kind: 'reasoning', body: 'Step 1' });+ });++ it('closes the opposite cursor on text↔reasoning phase switches (chronological order)', () => {+ /** Codex P2 regression: a `reasoning → text → reasoning` sequence+ * used to append the second reasoning chunk to the first+ * reasoning line (cursor never reset across the text switch),+ * producing merged/out-of-order previews. Now each delta-type+ * transition closes the opposite buffer/cursor, matching the+ * content-parts reducer's chronological rule. */+ const lines = buildSubagentTickerLines([+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Plan step.' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Answer part 1.' }] } },+ }),+ makeEvent({+ phase: 'reasoning_delta',+ data: { delta: { content: [{ type: 'think', think: 'Refined plan.' }] } },+ }),+ makeEvent({+ phase: 'message_delta',+ data: { delta: { content: [{ type: 'text', text: 'Answer part 2.' }] } },+ }),+ ]);+ expect(lines.map((l) => (l as { kind: string }).kind)).toEqual([+ 'reasoning',+ 'writing',+ 'reasoning',+ 'writing',+ ]);+ expect((lines[0] as { body: string }).body).toBe('Plan step.');+ expect((lines[1] as { body: string }).body).toBe('Answer part 1.');+ expect((lines[2] as { body: string }).body).toBe('Refined plan.');+ expect((lines[3] as { body: string }).body).toBe('Answer part 2.');+ });++ it('surfaces error envelopes with their message', () => {+ const lines = buildSubagentTickerLines([+ makeEvent({ phase: 'error', data: { message: 'recursion limit' } }),+ ]);+ expect(lines).toEqual([{ kind: 'error', message: 'recursion limit' }]);+ });+});diff --git a/client/src/utils/__tests__/toolLabels.test.ts b/client/src/utils/__tests__/toolLabels.test.tsnew file mode 100644index 0000000000..12fb0dcefa--- /dev/null+++ b/client/src/utils/__tests__/toolLabels.test.ts@@ -0,0 +1,67 @@+import { parseToolName, getToolDisplayLabel, TOOL_FRIENDLY_NAME_KEYS } from '../toolLabels';++describe('parseToolName', () => {+ it('splits an MCP tool id into server + tool name', () => {+ const parsed = parseToolName('search_code_mcp_github');+ expect(parsed).toEqual({+ raw: 'search_code_mcp_github',+ mcpServer: 'github',+ toolName: 'search_code',+ });+ });++ it('handles an MCP id whose tool-name portion contains underscores', () => {+ const parsed = parseToolName('deeply_nested_sub_tool_mcp_some-server');+ expect(parsed.mcpServer).toBe('some-server');+ expect(parsed.toolName).toBe('deeply_nested_sub_tool');+ });++ it('returns empty mcpServer + friendlyKey for a known native tool', () => {+ const parsed = parseToolName('web_search');+ expect(parsed).toEqual({+ raw: 'web_search',+ mcpServer: '',+ toolName: 'web_search',+ friendlyKey: TOOL_FRIENDLY_NAME_KEYS.web_search,+ });+ });++ it('returns empty mcpServer + no friendlyKey for an unknown native tool', () => {+ const parsed = parseToolName('custom_tool');+ expect(parsed).toEqual({+ raw: 'custom_tool',+ mcpServer: '',+ toolName: 'custom_tool',+ });+ });++ it('handles an MCP id with an empty server segment (pathological)', () => {+ /** `<tool>_mcp_` with nothing after the delimiter — treat as MCP+ * with an empty server name rather than falling through to the+ * native-tool path, so the display logic can surface "broken" ids+ * rather than silently showing the whole thing as a tool name. */+ const parsed = parseToolName('foo_mcp_');+ expect(parsed.mcpServer).toBe('');+ expect(parsed.toolName).toBe('foo');+ });+});++describe('getToolDisplayLabel', () => {+ const identityLocalize = (key: string): string => key;++ it('returns the MCP server name for an MCP tool', () => {+ expect(getToolDisplayLabel('search_code_mcp_github', identityLocalize)).toBe('github');+ });++ it('returns the friendly translation key for a known native tool', () => {+ /** The identity-localize stub returns the translation key itself,+ * which is what the real `useLocalize` would resolve at render time. */+ expect(getToolDisplayLabel('web_search', identityLocalize)).toBe(+ TOOL_FRIENDLY_NAME_KEYS.web_search,+ );+ });++ it('returns the raw name for an unknown native tool', () => {+ expect(getToolDisplayLabel('custom_tool', identityLocalize)).toBe('custom_tool');+ });+});diff --git a/client/src/utils/index.ts b/client/src/utils/index.tsindex 32f7a67c4a..1918ca16d8 100644--- a/client/src/utils/index.ts+++ b/client/src/utils/index.ts@@ -30,6 +30,7 @@ export * from './localStorage';export * from './promptGroups';export * from './previewCache';export * from './groupToolCalls';+export * from './toolLabels';export * from './favoritesError';export { default as cn } from './cn';export { default as logger } from './logger';diff --git a/client/src/utils/subagentContent.ts b/client/src/utils/subagentContent.tsnew file mode 100644index 0000000000..15755ac94b--- /dev/null+++ b/client/src/utils/subagentContent.ts@@ -0,0 +1,496 @@+import { ContentTypes, ToolCallTypes } from 'librechat-data-provider';+import type { SubagentUpdateEvent } from 'librechat-data-provider';++/**+ * Client-side helpers for rendering the live `SubagentCall` UI while+ * `ON_SUBAGENT_UPDATE` events stream in. Exports two pure transforms:+ *+ * - `aggregateSubagentContent` — folds the raw event stream into an+ * ordered array of TEXT / THINK / TOOL_CALL parts so the dialog can+ * render the child's activity through the same `<Part />` pipeline+ * the parent conversation uses. Frontend-only: on the backend we+ * fold directly into the SDK's `createContentAggregator` in the+ * `ON_SUBAGENT_UPDATE` handler, so no shared aggregator is needed.+ * - `buildSubagentTickerLines` — short, user-readable status lines+ * for the collapsed ticker. Aggregates message/reasoning deltas+ * into running previews, surfaces tool-call lifecycle with+ * args/output snippets, drops low-signal events.+ */++type RunStepData = {+ id?: string;+ stepDetails?: {+ type?: string;+ tool_calls?: Array<{+ id?: string;+ name?: string;+ args?: unknown;+ type?: string;+ }>;+ };+};++type RunStepCompletedData = {+ result?: {+ type?: string;+ tool_call?: {+ id?: string;+ name?: string;+ args?: unknown;+ output?: string;+ progress?: number;+ };+ };+};++type MessageDeltaData = {+ delta?: { content?: Array<{ type?: string; text?: string }> };+};++type ReasoningDeltaData = {+ delta?: { content?: Array<{ type?: string; think?: string }> };+};++type ErrorData = { message?: string };++type TextPart = { type: ContentTypes.TEXT; text: string };+type ThinkPart = { type: ContentTypes.THINK; think: string };+type ToolCallPart = {+ type: ContentTypes.TOOL_CALL;+ tool_call: {+ id: string;+ name: string;+ args: string;+ output?: string;+ progress: number;+ type?: string;+ };+};++/** Single content-part-shaped entry produced by the aggregator. The union+ * matches the subset of `TMessageContentParts` a subagent run emits. */+export type SubagentContentPart = TextPart | ThinkPart | ToolCallPart;++const extractTextChunk = (data: MessageDeltaData | undefined): string => {+ const content = data?.delta?.content;+ if (!Array.isArray(content)) return '';+ for (const block of content) {+ if (block?.type === 'text' && typeof block.text === 'string') {+ return block.text;+ }+ }+ return '';+};++const extractThinkChunk = (data: ReasoningDeltaData | undefined): string => {+ const content = data?.delta?.content;+ if (!Array.isArray(content)) return '';+ for (const block of content) {+ if (block?.type === 'think' && typeof block.think === 'string') {+ return block.think;+ }+ }+ return '';+};++const stringifyArgs = (args: unknown): string =>+ typeof args === 'string' ? args : JSON.stringify(args ?? {});++/**+ * Cursor carried across `foldSubagentEvent` calls so the aggregator can+ * extend an in-flight TEXT/THINK run without re-scanning earlier parts+ * on every event. `null` means the corresponding buffer is closed;+ * otherwise it's the index of the still-growing part in `contentParts`.+ */+export interface SubagentAggregatorState {+ /** Index of the currently-open TEXT part, or `null` when none. */+ openTextIdx: number | null;+ /** Index of the currently-open THINK part, or `null` when none. */+ openThinkIdx: number | null;+ /** `tool_call.id` → its index in `contentParts` for O(1) updates. */+ toolCallIndexById: Record<string, number>;+}++/** Initial empty aggregator state. */+export function initSubagentAggregatorState(): SubagentAggregatorState {+ return {+ openTextIdx: null,+ openThinkIdx: null,+ toolCallIndexById: {},+ };+}++/**+ * Incrementally fold a single {@link SubagentUpdateEvent} into an existing+ * `contentParts` array, returning a new array + updated cursor state.+ * Pure function — never mutates inputs.+ *+ * Adjacent `message_delta` / `reasoning_delta` events extend the in-flight+ * TEXT / THINK part (tracked via the open*Idx cursors). When a delta+ * type switches, the opposite buffer is closed first so chronological+ * order is preserved — what the user saw is what lands in the array.+ *+ * `run_step` with `tool_calls` closes any open text/think and appends a+ * TOOL_CALL part per unique id. `run_step_completed` updates the matching+ * TOOL_CALL (output + progress). Late-arriving completions without a+ * prior `run_step` synthesize the part. `start` / `stop` / `error` /+ * `run_step_delta` contribute nothing to content.+ */+export function foldSubagentEvent(+ parts: SubagentContentPart[],+ state: SubagentAggregatorState,+ event: SubagentUpdateEvent,+): { parts: SubagentContentPart[]; state: SubagentAggregatorState } {+ if (event.phase === 'message_delta') {+ const chunk = extractTextChunk(event.data as MessageDeltaData | undefined);+ if (!chunk) return { parts, state };+ /** Reasoning→text transition: close the open THINK so the THINK part+ * lands BEFORE the TEXT part in chronological order. */+ const afterThinkClose = state.openThinkIdx != null ? { ...state, openThinkIdx: null } : state;+ if (afterThinkClose.openTextIdx != null) {+ const idx = afterThinkClose.openTextIdx;+ const existing = parts[idx] as TextPart;+ const next = parts.slice();+ next[idx] = { type: ContentTypes.TEXT, text: existing.text + chunk };+ return { parts: next, state: afterThinkClose };+ }+ const next = parts.slice();+ const newIdx = next.length;+ next.push({ type: ContentTypes.TEXT, text: chunk });+ return { parts: next, state: { ...afterThinkClose, openTextIdx: newIdx } };+ }++ if (event.phase === 'reasoning_delta') {+ const chunk = extractThinkChunk(event.data as ReasoningDeltaData | undefined);+ if (!chunk) return { parts, state };+ const afterTextClose = state.openTextIdx != null ? { ...state, openTextIdx: null } : state;+ if (afterTextClose.openThinkIdx != null) {+ const idx = afterTextClose.openThinkIdx;+ const existing = parts[idx] as ThinkPart;+ const next = parts.slice();+ next[idx] = { type: ContentTypes.THINK, think: existing.think + chunk };+ return { parts: next, state: afterTextClose };+ }+ const next = parts.slice();+ const newIdx = next.length;+ next.push({ type: ContentTypes.THINK, think: chunk });+ return { parts: next, state: { ...afterTextClose, openThinkIdx: newIdx } };+ }++ if (event.phase === 'run_step') {+ const data = event.data as RunStepData | undefined;+ if (data?.stepDetails?.type !== 'tool_calls') return { parts, state };+ const toolCalls = data.stepDetails.tool_calls ?? [];+ let next = parts;+ const toolCallIndexById = { ...state.toolCallIndexById };+ for (const tc of toolCalls) {+ if (typeof tc?.id !== 'string' || !tc.id || tc.id in toolCallIndexById) continue;+ if (next === parts) next = parts.slice();+ toolCallIndexById[tc.id] = next.length;+ next.push({+ type: ContentTypes.TOOL_CALL,+ tool_call: {+ id: tc.id,+ name: tc.name ?? '',+ args: stringifyArgs(tc.args),+ progress: 0.1,+ type: tc.type ?? ToolCallTypes.TOOL_CALL,+ },+ });+ }+ if (next === parts) return { parts, state: { ...state, toolCallIndexById } };+ /** New tool_call parts bound any open TEXT/THINK to the run before+ * them — close the buffers. */+ return {+ parts: next,+ state: { openTextIdx: null, openThinkIdx: null, toolCallIndexById },+ };+ }++ if (event.phase === 'run_step_completed') {+ const data = event.data as RunStepCompletedData | undefined;+ const tc = data?.result?.tool_call;+ if (typeof tc?.id !== 'string' || !tc.id) return { parts, state };+ const existingIdx = state.toolCallIndexById[tc.id];+ if (existingIdx != null) {+ const existing = parts[existingIdx] as ToolCallPart;+ const merged: ToolCallPart = {+ type: ContentTypes.TOOL_CALL,+ tool_call: {+ ...existing.tool_call,+ ...(tc.name ? { name: tc.name } : {}),+ ...(tc.args != null ? { args: stringifyArgs(tc.args) } : {}),+ ...(tc.output != null ? { output: tc.output } : {}),+ progress: tc.progress ?? 1,+ },+ };+ const next = parts.slice();+ next[existingIdx] = merged;+ return { parts: next, state };+ }+ /** Late-arriving completion without a prior run_step — synthesize the+ * part (and close any open buffer like run_step would). */+ const next = parts.slice();+ const newIdx = next.length;+ next.push({+ type: ContentTypes.TOOL_CALL,+ tool_call: {+ id: tc.id,+ name: tc.name ?? '',+ args: stringifyArgs(tc.args),+ output: tc.output,+ progress: tc.progress ?? 1,+ type: ToolCallTypes.TOOL_CALL,+ },+ });+ return {+ parts: next,+ state: {+ openTextIdx: null,+ openThinkIdx: null,+ toolCallIndexById: { ...state.toolCallIndexById, [tc.id]: newIdx },+ },+ };+ }++ return { parts, state };+}++/**+ * Batch wrapper around {@link foldSubagentEvent}: folds an entire event+ * stream in one go and returns just the parts. Kept for tests and for+ * legacy call-sites that don't need cursor state.+ */+export function aggregateSubagentContent(events: SubagentUpdateEvent[]): SubagentContentPart[] {+ let parts: SubagentContentPart[] = [];+ let state = initSubagentAggregatorState();+ for (const event of events) {+ ({ parts, state } = foldSubagentEvent(parts, state, event));+ }+ return parts;+}++/**+ * Discriminated-union ticker line. Keeping the label tokens + body/snippets+ * separate from their rendered strings lets the caller localize at+ * render time (hooks can't live in a pure aggregator) and — more+ * importantly — lets the UI split a fixed prefix (e.g. "Writing: ")+ * from a tail-truncatable body, so the prefix never gets clipped out+ * of view when the body overflows.+ */+export type SubagentTickerLine =+ | { kind: 'writing'; body: string }+ | { kind: 'reasoning'; body: string }+ | { kind: 'using_tool'; toolNames: string[]; argsSnippet?: string }+ | { kind: 'tool_complete'; toolName: string; outputSnippet?: string }+ | { kind: 'error'; message?: string };++/** Live-update cursor carried across incremental folds. Mirrors the+ * content-parts aggregator pattern so the atom can own the ticker+ * state and never has to re-aggregate from a trimmed event buffer. */+export interface SubagentTickerState {+ lines: SubagentTickerLine[];+ /** Index of the in-flight 'writing' line (for in-place tail updates). */+ textLineIdx: number | null;+ /** Index of the in-flight 'reasoning' line. */+ thinkLineIdx: number | null;+ /** Raw message-delta accumulator — truncated into `writing.body` but+ * preserved so subsequent deltas extend the running preview. */+ textBuffer: string;+ thinkBuffer: string;+}++export function initSubagentTickerState(): SubagentTickerState {+ return {+ lines: [],+ textLineIdx: null,+ thinkLineIdx: null,+ textBuffer: '',+ thinkBuffer: '',+ };+}++/** Generous tail window so wide ticker containers aren't half-empty.+ * The component applies CSS tail-ellipsis (`dir="rtl"` ++ * `text-overflow: ellipsis`) so narrow viewports clip from the oldest+ * side; we deliberately DON'T prepend a data-level `…` on top of that+ * CSS ellipsis — double-eliding would render a stray dot character+ * right next to the "Writing:" / "Reasoning:" label. */+const PREVIEW_MAX_CHARS = 300;+const truncatePreview = (input: string): string => {+ const normalized = input.replace(/\s+/g, ' ').trim();+ if (normalized.length <= PREVIEW_MAX_CHARS) return normalized;+ return normalized.slice(-PREVIEW_MAX_CHARS);+};++const SNIPPET_MAX_CHARS = 48;+/** Short head-truncation for tool args/output — caller labels what each+ * side is. Whitespace collapsed so multi-line outputs stay one line. */+const truncateSnippet = (input: string): string => {+ const normalized = input.replace(/\s+/g, ' ').trim();+ if (normalized.length <= SNIPPET_MAX_CHARS) return normalized;+ return `${normalized.slice(0, SNIPPET_MAX_CHARS)}…`;+};++/** Best-effort, non-rendering summary of a tool's args payload. Parsed JSON+ * is collapsed into `key=value, key=value`; everything else falls back to+ * the raw string. Returns `''` when nothing useful is extractable. */+const summarizeArgs = (args: unknown): string => {+ if (typeof args !== 'string' || args.length === 0) return '';+ const raw = args.trim();+ if (raw.length === 0 || raw === '{}' || raw === '[]') return '';+ try {+ const parsed = JSON.parse(raw) as unknown;+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {+ const entries = Object.entries(parsed as Record<string, unknown>)+ .filter(([, v]) => v !== undefined && v !== null && v !== '')+ .map(([k, v]) => {+ const valueStr = typeof v === 'string' ? v : JSON.stringify(v);+ return `${k}=${valueStr}`;+ });+ if (entries.length === 0) return '';+ return truncateSnippet(entries.join(', '));+ }+ } catch {+ /* fall through to raw-string snippet */+ }+ return truncateSnippet(raw);+};++const summarizeOutput = (output: unknown): string => {+ if (typeof output === 'string') return truncateSnippet(output);+ if (output == null) return '';+ try {+ return truncateSnippet(JSON.stringify(output));+ } catch {+ return '';+ }+};++/**+ * Incrementally fold a single {@link SubagentUpdateEvent} into the ticker+ * state. Pure — never mutates inputs. Stored in the Recoil atom so the+ * ticker always reflects the *full* run, not just the rolling event+ * window (which trims as deltas pile up and can drop earlier tool_call+ * lifecycle events).+ *+ * Message/reasoning deltas extend an in-flight line via the `textLineIdx`+ * / `thinkLineIdx` cursors. A `run_step` with tool_calls closes the+ * running buffers and appends a `using_tool` line. `run_step_completed`+ * appends a `tool_complete` line. `error` appends an `error` line.+ * Phases we ignore (`start`, `stop`, `run_step_delta`): pass-through.+ */+export function foldSubagentEventIntoTicker(+ state: SubagentTickerState,+ event: SubagentUpdateEvent,+): SubagentTickerState {+ if (event.phase === 'message_delta') {+ const chunk = extractTextChunk(event.data as MessageDeltaData | undefined);+ if (!chunk) return state;+ /** Delta-type transition: close any open reasoning buffer/cursor so+ * a later `reasoning_delta` starts a NEW line below this text,+ * rather than appending to the original reasoning line (which+ * would produce merged / out-of-order previews). Mirrors the+ * content-parts reducer's chronological-order rule. */+ const afterClose =+ state.thinkLineIdx != null || state.thinkBuffer+ ? { ...state, thinkLineIdx: null, thinkBuffer: '' }+ : state;+ const textBuffer = afterClose.textBuffer + chunk;+ const body = truncatePreview(textBuffer);+ const line: SubagentTickerLine = { kind: 'writing', body };+ if (afterClose.textLineIdx == null) {+ const lines = afterClose.lines.concat(line);+ return { ...afterClose, textBuffer, lines, textLineIdx: lines.length - 1 };+ }+ const lines = afterClose.lines.slice();+ lines[afterClose.textLineIdx] = line;+ return { ...afterClose, textBuffer, lines };+ }++ if (event.phase === 'reasoning_delta') {+ const chunk = extractThinkChunk(event.data as ReasoningDeltaData | undefined);+ if (!chunk) return state;+ /** Symmetric: close any open text buffer/cursor. */+ const afterClose =+ state.textLineIdx != null || state.textBuffer+ ? { ...state, textLineIdx: null, textBuffer: '' }+ : state;+ const thinkBuffer = afterClose.thinkBuffer + chunk;+ const body = truncatePreview(thinkBuffer);+ const line: SubagentTickerLine = { kind: 'reasoning', body };+ if (afterClose.thinkLineIdx == null) {+ const lines = afterClose.lines.concat(line);+ return { ...afterClose, thinkBuffer, lines, thinkLineIdx: lines.length - 1 };+ }+ const lines = afterClose.lines.slice();+ lines[afterClose.thinkLineIdx] = line;+ return { ...afterClose, thinkBuffer, lines };+ }++ if (event.phase === 'run_step') {+ /** A new run_step starts a fresh lifecycle marker and closes any+ * in-flight streaming line — the delta cursors reset so the *next*+ * message/reasoning delta starts its own line below the tool call. */+ const afterClose: SubagentTickerState = {+ ...state,+ textBuffer: '',+ thinkBuffer: '',+ textLineIdx: null,+ thinkLineIdx: null,+ };+ const data = event.data as RunStepData | undefined;+ if (data?.stepDetails?.type !== 'tool_calls') return afterClose;+ const toolCalls = data.stepDetails.tool_calls ?? [];+ const named = toolCalls.filter(+ (tc): tc is { id?: string; name: string; args?: unknown } =>+ typeof tc?.name === 'string' && tc.name.length > 0,+ );+ if (named.length === 0) return afterClose;+ const toolNames = named.map((tc) => tc.name);+ const argsSnippet = named.length === 1 ? summarizeArgs(named[0].args) : undefined;+ const line: SubagentTickerLine = {+ kind: 'using_tool',+ toolNames,+ ...(argsSnippet ? { argsSnippet } : {}),+ };+ return { ...afterClose, lines: afterClose.lines.concat(line) };+ }++ if (event.phase === 'run_step_completed') {+ const data = event.data as RunStepCompletedData | undefined;+ const tc = data?.result?.tool_call;+ if (typeof tc?.name !== 'string' || tc.name.length === 0) return state;+ const outputSnippet = tc.output != null ? summarizeOutput(tc.output) : undefined;+ const line: SubagentTickerLine = {+ kind: 'tool_complete',+ toolName: tc.name,+ ...(outputSnippet ? { outputSnippet } : {}),+ };+ return { ...state, lines: state.lines.concat(line) };+ }++ if (event.phase === 'error') {+ const data = event.data as ErrorData | undefined;+ const line: SubagentTickerLine = {+ kind: 'error',+ ...(data?.message ? { message: data.message } : {}),+ };+ return { ...state, lines: state.lines.concat(line) };+ }++ return state;+}++/**+ * Batch wrapper around {@link foldSubagentEventIntoTicker} — folds an+ * entire event stream in one shot. Kept for tests and any legacy+ * consumer that prefers a one-call API.+ */+export function buildSubagentTickerLines(events: SubagentUpdateEvent[]): SubagentTickerLine[] {+ let state = initSubagentTickerState();+ for (const event of events) {+ state = foldSubagentEventIntoTicker(state, event);+ }+ return state.lines;+}diff --git a/client/src/utils/toolLabels.ts b/client/src/utils/toolLabels.tsnew file mode 100644index 0000000000..fcb6131213--- /dev/null+++ b/client/src/utils/toolLabels.ts@@ -0,0 +1,79 @@+import { Constants } from 'librechat-data-provider';+import type { TranslationKeys } from '~/hooks';++/**+ * Shared tool-name parsing + friendly-label mapping used by the main+ * tool-call UI and the subagent ticker. Centralized so the MCP+ * delimiter (`<tool>_mcp_<server>`) and native-tool short names read+ * consistently in every surface that renders tool lifecycle.+ */++/** Native tool id → translation key for a user-readable short name. */+export const TOOL_FRIENDLY_NAME_KEYS: Record<string, TranslationKeys> = {+ execute_code: 'com_ui_tool_name_code',+ run_tools_with_code: 'com_ui_tool_name_code',+ web_search: 'com_ui_tool_name_web_search',+ image_gen_oai: 'com_ui_tool_name_image_gen',+ image_edit_oai: 'com_ui_tool_name_image_edit',+ gemini_image_gen: 'com_ui_tool_name_image_gen',+ file_search: 'com_ui_tool_name_file_search',+ code_interpreter: 'com_ui_tool_name_code_analysis',+ retrieval: 'com_ui_tool_name_file_search',+};++export interface ParsedToolName {+ /** Original tool id (unchanged). */+ raw: string;+ /** MCP server name when the tool follows `<tool>_mcp_<server>`, else `''`. */+ mcpServer: string;+ /** Tool-specific name — the `<tool>` half of an MCP id, or the raw+ * name for native tools. Useful as the "action" label shown in a+ * code-style badge next to the server name. */+ toolName: string;+ /** Translation key for a user-friendly display name, when the raw+ * name matches a built-in native tool (web_search, execute_code, …).+ * Absent for MCP tools and unknown names. */+ friendlyKey?: TranslationKeys;+}++/**+ * Split an incoming tool id into its constituent parts:+ *+ * - `search_code_mcp_github` → `{ mcpServer: 'github', toolName: 'search_code' }`+ * - `web_search` → `{ mcpServer: '', toolName: 'web_search', friendlyKey: 'com_ui_tool_name_web_search' }`+ * - `some_custom_tool` → `{ mcpServer: '', toolName: 'some_custom_tool' }`+ */+export function parseToolName(rawName: string): ParsedToolName {+ const idx = rawName.indexOf(Constants.mcp_delimiter);+ if (idx >= 0) {+ const mcpServer = rawName.slice(idx + Constants.mcp_delimiter.length);+ const toolName = rawName.slice(0, idx);+ return { raw: rawName, mcpServer, toolName };+ }+ const friendlyKey = TOOL_FRIENDLY_NAME_KEYS[rawName];+ return {+ raw: rawName,+ mcpServer: '',+ toolName: rawName,+ ...(friendlyKey ? { friendlyKey } : {}),+ };+}++/**+ * Resolve a tool id to a single user-facing short label. Pure string —+ * use `parseToolName` directly when you need structured parts (e.g. to+ * render a code-style badge for the tool name next to the server).+ *+ * - MCP tool → server name (keeps the header summary short)+ * - Native → localized friendly name from {@link TOOL_FRIENDLY_NAME_KEYS}+ * - Unknown → raw name+ */+export function getToolDisplayLabel(+ rawName: string,+ localize: (key: TranslationKeys) => string,+): string {+ const parsed = parseToolName(rawName);+ if (parsed.mcpServer) return parsed.mcpServer;+ if (parsed.friendlyKey) return localize(parsed.friendlyKey);+ return parsed.toolName;+}diff --git a/packages/api/src/agents/__tests__/run-summarization.test.ts b/packages/api/src/agents/__tests__/run-summarization.test.tsindex 2461b6416a..4164d5ecf4 100644--- a/packages/api/src/agents/__tests__/run-summarization.test.ts+++ b/packages/api/src/agents/__tests__/run-summarization.test.ts@@ -805,3 +805,118 @@ describe('custom-endpoint provider resolution', () => {expect(parameters.modelName).toBeUndefined();});});++// ---------------------------------------------------------------------------+// Suite 8: subagentConfigs+// ---------------------------------------------------------------------------+describe('subagentConfigs', () => {+ it('is undefined when subagents are not enabled', async () => {+ const agents = await callAndCapture({});+ expect(agents[0].subagentConfigs).toBeUndefined();+ });++ it('adds self-spawn when enabled and allowSelf defaults to true', async () => {+ const agents = await callAndCapture({+ agents: [makeAgent({ subagents: { enabled: true } })],+ });+ const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;+ expect(Array.isArray(configs)).toBe(true);+ expect(configs).toHaveLength(1);+ expect(configs[0]).toMatchObject({ self: true, type: 'self' });+ });++ it('omits self-spawn when allowSelf is false', async () => {+ const agents = await callAndCapture({+ agents: [makeAgent({ subagents: { enabled: true, allowSelf: false } })],+ });+ expect(agents[0].subagentConfigs).toBeUndefined();+ });++ it('adds explicit subagent configs with agentInputs', async () => {+ const child = makeAgent({+ id: 'agent_child',+ name: 'Researcher',+ description: 'Deep web research',+ });+ const agents = await callAndCapture({+ agents: [+ makeAgent({+ subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },+ subagentAgentConfigs: [child],+ }),+ ],+ });+ const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;+ expect(configs).toHaveLength(1);+ expect(configs[0]).toMatchObject({+ type: 'agent_child',+ name: 'Researcher',+ description: 'Deep web research',+ });+ expect(configs[0].agentInputs).toBeDefined();+ expect(configs[0].self).toBeUndefined();+ });++ it('combines self-spawn and explicit subagents when both enabled', async () => {+ const child = makeAgent({ id: 'agent_child', name: 'Helper' });+ const agents = await callAndCapture({+ agents: [+ makeAgent({+ subagents: { enabled: true, agent_ids: ['agent_child'] },+ subagentAgentConfigs: [child],+ }),+ ],+ });+ const configs = agents[0].subagentConfigs as Array<Record<string, unknown>>;+ expect(configs).toHaveLength(2);+ expect(configs[0].self).toBe(true);+ expect(configs[1].type).toBe('agent_child');+ });++ it('skips a child that points at the parent itself', async () => {+ const self = makeAgent({ id: 'agent_1' });+ const agents = await callAndCapture({+ agents: [+ makeAgent({+ subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_1'] },+ subagentAgentConfigs: [self],+ }),+ ],+ });+ expect(agents[0].subagentConfigs).toBeUndefined();+ });++ it('does NOT leak the parent run `initialSummary` into an explicit child (Codex P1 regression)', async () => {+ /**+ * `buildAgentInput` is a shared factory that always stamps the parent+ * run's `initialSummary` on the returned AgentInputs. When it's reused+ * to build a subagent child's inputs, `buildSubagentConfigs` must clear+ * that field — otherwise the child inherits unrelated conversation+ * context, defeating the isolation contract (and burning extra tokens).+ */+ const summary = { text: 'parent conversation summary', tokenCount: 99 };+ const child = makeAgent({ id: 'agent_child', name: 'Child' });+ const agents = await callAndCapture({+ initialSummary: summary,+ agents: [+ makeAgent({+ subagents: { enabled: true, allowSelf: false, agent_ids: ['agent_child'] },+ subagentAgentConfigs: [child],+ }),+ ],+ });++ const parent = agents[0];+ /** The parent itself keeps the summary — that's how it receives+ * cross-turn context. */+ expect(parent.initialSummary).toEqual(summary);++ const childConfig = (parent.subagentConfigs as Array<Record<string, unknown>>)[0];+ const childInputs = childConfig.agentInputs as {+ initialSummary?: unknown;+ discoveredTools?: unknown;+ };+ expect(childInputs.initialSummary).toBeUndefined();+ expect(childInputs.discoveredTools).toBeUndefined();+ });+});diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.tsindex b79fe92cfd..d86b15a470 100644--- a/packages/api/src/agents/run.ts+++ b/packages/api/src/agents/run.ts@@ -13,13 +13,14 @@ import type {OpenAIClientOptions,StandardGraphConfig,LCToolRegistry,+ SubagentConfig,AgentInputs,GenericTool,RunConfig,IState,LCTool,} from '@librechat/agents';-import type { Agent, SummarizationConfig } from 'librechat-data-provider';+import type { Agent, AgentSubagentsConfig, SummarizationConfig } from 'librechat-data-provider';import type { BaseMessage } from '@langchain/core/messages';import type { AppConfig, IUser } from '@librechat/data-schemas';import type * as t from '~/types';@@ -245,6 +246,10 @@ type RunAgent = Omit<Agent, 'tools'> & {* Overrides the default computed from maxContextTokens.*/maxToolResultChars?: number;+ /** Initialized subagent configs (loaded by initialize.js from agent.subagents.agent_ids). */+ subagentAgentConfigs?: RunAgent[];+ /** Source subagent spawning configuration (enabled / allowSelf / agent_ids). */+ subagents?: AgentSubagentsConfig;};function isNonEmptyString(value: unknown): value is string {@@ -494,6 +499,91 @@ function computeEffectiveMaxContextTokens(return Math.min(maxContextTokens ?? ratioComputed, ratioComputed);}+/** Identifier for the self-spawn subagent (reuses parent's AgentInputs in an isolated child graph). */+const SELF_SUBAGENT_TYPE = 'self';++/**+ * Builds SubagentConfig entries for an agent: optional self-spawn plus any+ * explicit child agents loaded in `agent.subagentAgentConfigs`. Returns an empty+ * array when subagents are disabled or no spawn targets are available.+ */+function buildSubagentConfigs(+ agent: RunAgent,+ agentInput: AgentInputs,+ toInput: (child: RunAgent, opts?: { isSubagent?: boolean }) => AgentInputs,+ ancestors: Set<string> = new Set(),+): SubagentConfig[] {+ if (!agent.subagents?.enabled) {+ return [];+ }++ const configs: SubagentConfig[] = [];+ const allowSelf = agent.subagents.allowSelf !== false;++ if (allowSelf) {+ const selfName = agentInput.name ?? agent.name ?? 'self';+ configs.push({+ self: true,+ type: SELF_SUBAGENT_TYPE,+ name: selfName,+ description: `Spawn ${selfName} in an isolated context to handle a focused subtask. Verbose tool output stays in the child's context; only a summary returns.`,+ });+ }++ /** Cycle-safety: include the current agent in `ancestors` before+ * descending into children so a `A → B → A` configuration stops at+ * the second encounter of A rather than recursing forever. Skip+ * `A → A` too (already guarded) and anything that would re-enter+ * an ancestor. */+ const nextAncestors = new Set(ancestors);+ nextAncestors.add(agent.id);++ for (const child of agent.subagentAgentConfigs ?? []) {+ if (!child?.id || child.id === agent.id) {+ continue;+ }+ if (ancestors.has(child.id)) {+ continue;+ }+ /**+ * `buildAgentInput` applies parent-run context (initialSummary ++ * discoveredTools) to the returned AgentInputs *and* to the+ * passed-in agent's `toolRegistry` / `toolDefinitions` — flipping+ * `defer_loading: true → false` on tools the parent had previously+ * searched for, and injecting those tools' definitions into the+ * child's `toolDefinitions`. Clearing fields on the returned+ * object post-hoc would leave those side-effects in place, leaking+ * the parent's tool-search state into an "isolated" subagent and+ * inflating the child's prompt/token budget. The `isSubagent` flag+ * skips both the field stamping and the registry mutation at the+ * source so children truly start fresh.+ */+ const childInputs = toInput(child, { isSubagent: true });+ /**+ * Recursively resolve the child's own spawn targets so multi-level+ * delegation (A → B → C) works. Without this, a child whose own+ * `subagents.enabled` is true loses every explicit target when+ * invoked as a subagent — only the top-level loop attaches+ * `subagentConfigs`, and that only runs for the outer agents in+ * `agents[]`. Cycle-safe via `nextAncestors`.+ */+ const grandchildConfigs = buildSubagentConfigs(child, childInputs, toInput, nextAncestors);+ if (grandchildConfigs.length > 0) {+ childInputs.subagentConfigs = grandchildConfigs;+ }+ configs.push({+ type: child.id,+ name: child.name ?? child.id,+ description:+ child.description ??+ `Delegate a subtask to the ${child.name ?? child.id} agent in an isolated context.`,+ agentInputs: childInputs,+ });+ }++ return configs;+}+/*** Creates a new Run instance with custom handlers and configuration.*@@ -565,8 +655,8 @@ export async function createRun({? extractDiscoveredToolsFromHistory(messages): new Set<string>();- const agentInputs: AgentInputs[] = [];- const buildAgentContext = (agent: RunAgent) => {+ const buildAgentInput = (agent: RunAgent, opts: { isSubagent?: boolean } = {}): AgentInputs => {+ const isSubagent = opts.isSubagent === true;const provider =(providerEndpointMap[agent.provider as keyof typeof providerEndpointMap@@ -627,12 +717,22 @@ export async function createRun({}/**- * Override defer_loading for tools that were discovered in previous turns.- * This prevents the LLM from having to re-discover tools via tool_search.- * Also add the discovered tools' definitions so the LLM has their schemas.+ * Override defer_loading for tools that were discovered in previous+ * turns. This prevents the LLM from having to re-discover tools via+ * tool_search. Also add the discovered tools' definitions so the+ * LLM has their schemas.+ *+ * Skipped for subagent children (`isSubagent`) — they run in an+ * isolated context by contract, so inheriting the parent's+ * tool-search state leaks unrelated history and pre-loads tools the+ * child shouldn't care about. Mutations on `agent.toolRegistry`+ * and additions to `toolDefinitions` both happen here, so the flag+ * has to gate the whole block (clearing fields post-return can't+ * undo registry writes).*/let toolDefinitions = agent.toolDefinitions ?? [];- if (discoveredTools.size > 0 && agent.toolRegistry) {+ let toolRegistry = agent.toolRegistry;+ if (!isSubagent && discoveredTools.size > 0 && agent.toolRegistry) {overrideDeferLoadingForDiscoveredTools(agent.toolRegistry, discoveredTools);/** Add discovered tools' definitions so the LLM can see their schemas */@@ -646,6 +746,25 @@ export async function createRun({toolDefinitions = [...toolDefinitions, toolDef];}}+ } else if (isSubagent && agent.toolRegistry) {+ /**+ * Subagent children: hand the child a deep-enough clone of the+ * registry so later parent-graph builds (e.g. when the same+ * agent also appears as a handoff target in the outer loop)+ * can't mutate `defer_loading` on tool definitions the child+ * already holds a reference to. Clone the `Map` *and* each+ * `LCTool` — `overrideDeferLoadingForDiscoveredTools` writes+ * through to the tool object itself, so a shallow Map copy+ * alone wouldn't isolate the flag.+ */+ toolRegistry = new Map();+ for (const [name, tool] of agent.toolRegistry.entries()) {+ toolRegistry.set(name, { ...tool });+ }+ /** Child's own `toolDefinitions` list gets the same shallow-+ * copied view so any later parent mutation of shared definitions+ * is contained to the parent-graph path. */+ toolDefinitions = toolDefinitions.map((def) => ({ ...def }));}const effectiveMaxContextTokens = computeEffectiveMaxContextTokens(@@ -655,7 +774,7 @@ export async function createRun({);const reasoningKey = getReasoningKey(provider, llmConfig, agent.endpoint);- const agentInput: AgentInputs = {+ return {provider,reasoningKey,toolDefinitions,@@ -664,21 +783,27 @@ export async function createRun({clientOptions: llmConfig,instructions: systemContent,name: agent.name ?? undefined,- toolRegistry: agent.toolRegistry,+ toolRegistry,maxContextTokens: effectiveMaxContextTokens,useLegacyContent: agent.useLegacyContent ?? false,- discoveredTools: discoveredTools.size > 0 ? Array.from(discoveredTools) : undefined,+ discoveredTools:+ !isSubagent && discoveredTools.size > 0 ? Array.from(discoveredTools) : undefined,summarizationEnabled: summarization.enabled,summarizationConfig: summarization.config,- initialSummary,+ initialSummary: isSubagent ? undefined : initialSummary,contextPruningConfig: summarization.contextPruning,maxToolResultChars: agent.maxToolResultChars,};- agentInputs.push(agentInput);};+ const agentInputs: AgentInputs[] = [];for (const agent of agents) {- buildAgentContext(agent);+ const agentInput = buildAgentInput(agent);+ const subagentConfigs = buildSubagentConfigs(agent, agentInput, buildAgentInput);+ if (subagentConfigs.length > 0) {+ agentInput.subagentConfigs = subagentConfigs;+ }+ agentInputs.push(agentInput);}const graphConfig: RunConfig['graphConfig'] = {diff --git a/packages/api/src/agents/validation.spec.ts b/packages/api/src/agents/validation.spec.tsnew file mode 100644index 0000000000..743217780f--- /dev/null+++ b/packages/api/src/agents/validation.spec.ts@@ -0,0 +1,83 @@+import { MAX_SUBAGENTS } from 'librechat-data-provider';+import { agentCreateSchema, agentUpdateSchema, agentSubagentsSchema } from './validation';++describe('agentSubagentsSchema', () => {+ it('accepts enabled:true with a list within the cap', () => {+ const result = agentSubagentsSchema.safeParse({+ enabled: true,+ allowSelf: false,+ agent_ids: ['agent_1', 'agent_2'],+ });+ expect(result.success).toBe(true);+ });++ it('accepts the feature-off shape (enabled:false, no agents)', () => {+ const result = agentSubagentsSchema.safeParse({ enabled: false });+ expect(result.success).toBe(true);+ });++ it('rejects agent_ids longer than MAX_SUBAGENTS', () => {+ const oversized = Array.from({ length: MAX_SUBAGENTS + 1 }, (_, i) => `agent_${i}`);+ const result = agentSubagentsSchema.safeParse({+ enabled: true,+ agent_ids: oversized,+ });+ expect(result.success).toBe(false);+ });++ it('accepts exactly MAX_SUBAGENTS entries', () => {+ const atCap = Array.from({ length: MAX_SUBAGENTS }, (_, i) => `agent_${i}`);+ const result = agentSubagentsSchema.safeParse({+ enabled: true,+ agent_ids: atCap,+ });+ expect(result.success).toBe(true);+ });+});++describe('agentCreateSchema with subagents', () => {+ const base = {+ provider: 'openAI',+ model: 'gpt-4o-mini',+ tools: [],+ };++ it('passes with subagents omitted', () => {+ const result = agentCreateSchema.safeParse(base);+ expect(result.success).toBe(true);+ });++ it('passes with a valid subagents config', () => {+ const result = agentCreateSchema.safeParse({+ ...base,+ subagents: { enabled: true, allowSelf: true, agent_ids: [] },+ });+ expect(result.success).toBe(true);+ });++ it('rejects when subagents.agent_ids exceeds the cap', () => {+ const oversized = Array.from({ length: MAX_SUBAGENTS + 1 }, (_, i) => `agent_${i}`);+ const result = agentCreateSchema.safeParse({+ ...base,+ subagents: { enabled: true, agent_ids: oversized },+ });+ expect(result.success).toBe(false);+ });+});++describe('agentUpdateSchema with subagents', () => {+ it('accepts a partial update with only the disabled flag set', () => {+ const result = agentUpdateSchema.safeParse({+ subagents: { enabled: false, allowSelf: true, agent_ids: [] },+ });+ expect(result.success).toBe(true);+ });++ it('rejects oversized agent_ids on update', () => {+ const oversized = Array.from({ length: MAX_SUBAGENTS + 3 }, (_, i) => `agent_${i}`);+ const result = agentUpdateSchema.safeParse({+ subagents: { enabled: true, agent_ids: oversized },+ });+ expect(result.success).toBe(false);+ });+});diff --git a/packages/api/src/agents/validation.ts b/packages/api/src/agents/validation.tsindex dd12a9ffe6..877614bf95 100644--- a/packages/api/src/agents/validation.ts+++ b/packages/api/src/agents/validation.ts@@ -1,5 +1,5 @@import { z } from 'zod';-import { ViolationTypes, ErrorTypes } from 'librechat-data-provider';+import { MAX_SUBAGENTS, ViolationTypes, ErrorTypes } from 'librechat-data-provider';import type { Agent, TModelsConfig } from 'librechat-data-provider';import type { Request, Response } from 'express';@@ -51,11 +51,20 @@ export const agentSupportContactSchema = zexport const graphEdgeSchema = z.object({from: z.union([z.string(), z.array(z.string())]),to: z.union([z.string(), z.array(z.string())]),- description: z.string().optional().transform((v) => (v === '' ? undefined : v)),+ description: z+ .string()+ .optional()+ .transform((v) => (v === '' ? undefined : v)),edgeType: z.enum(['handoff', 'direct']).optional(),- prompt: z.union([z.string(), z.function()]).optional().transform((v) => (v === '' ? undefined : v)),+ prompt: z+ .union([z.string(), z.function()])+ .optional()+ .transform((v) => (v === '' ? undefined : v)),excludeResults: z.boolean().optional(),- promptKey: z.string().optional().transform((v) => (v === '' ? undefined : v)),+ promptKey: z+ .string()+ .optional()+ .transform((v) => (v === '' ? undefined : v)),});/** Per-tool options schema (defer_loading, allowed_callers) */@@ -67,6 +76,20 @@ export const toolOptionsSchema = z.object({/** Agent tool options - map of tool_id to tool options */export const agentToolOptionsSchema = z.record(z.string(), toolOptionsSchema).optional();+/**+ * Subagent spawning configuration for an agent. `agent_ids` is capped at+ * `Constants.MAX_SUBAGENTS` so a crafted API request cannot trigger hundreds+ * of `processAgent` calls (DB lookup + permission check + tool loading).+ * The UI enforces the same cap, so legitimate payloads never hit the bound.+ */+export const agentSubagentsSchema = z+ .object({+ enabled: z.boolean().optional(),+ allowSelf: z.boolean().optional(),+ agent_ids: z.array(z.string()).max(MAX_SUBAGENTS).optional(),+ })+ .optional();+/** Base agent schema with all common fields */export const agentBaseSchema = z.object({name: z.string().nullable().optional(),@@ -86,6 +109,7 @@ export const agentBaseSchema = z.object({conversation_starters: z.array(z.string()).optional(),tool_resources: agentToolResourcesSchema,tool_options: agentToolOptionsSchema,+ subagents: agentSubagentsSchema,support_contact: agentSupportContactSchema,category: z.string().optional(),});diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 6b1f5aed6c..f783391323 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -223,6 +223,7 @@ export enum AgentCapabilities {file_search = 'file_search',web_search = 'web_search',artifacts = 'artifacts',+ subagents = 'subagents',actions = 'actions',context = 'context',skills = 'skills',@@ -313,6 +314,7 @@ export const defaultAgentCapabilities = [AgentCapabilities.file_search,AgentCapabilities.web_search,AgentCapabilities.artifacts,+ AgentCapabilities.subagents,AgentCapabilities.actions,AgentCapabilities.context,AgentCapabilities.skills,@@ -1925,8 +1927,13 @@ export enum Constants {EPHEMERAL_AGENT_ID = 'ephemeral',/** Programmatic Tool Calling tool name */PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',+ /** Subagent spawn tool name (must match `@librechat/agents` `Constants.SUBAGENT`). */+ SUBAGENT = 'subagent',}+/** Maximum number of explicit subagents per parent agent. UI + Zod schema share this. */+export const MAX_SUBAGENTS = 10;+export enum LocalStorageKeys {/** Key for the admin defined App Title */APP_TITLE = 'appTitle',diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.tsindex dd611250cd..9b52e3711d 100644--- a/packages/data-provider/src/schemas.ts+++ b/packages/data-provider/src/schemas.ts@@ -298,6 +298,10 @@ export const defaultAgentFormValues = {* interacted with the skills UI) does not accidentally persist "explicit none"* on first save — removeNullishValues strips the field server-side. */skills: undefined as string[] | undefined,+ /** `undefined` = feature disabled by default (no subagent tool injected). */+ subagents: undefined as+ | { enabled?: boolean; allowSelf?: boolean; agent_ids?: string[] }+ | undefined,};export const ImageVisionTool: FunctionTool = {diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.tsindex 4618f4f49f..402a6de2af 100644--- a/packages/data-provider/src/types/assistants.ts+++ b/packages/data-provider/src/types/assistants.ts@@ -241,6 +241,19 @@ export type ToolOptions = {*/export type AgentToolOptions = Record<string, ToolOptions>;+/**+ * Configuration for spawning subagents (isolated-context child agents) from an agent.+ * When `enabled` is true, the agent gets a subagent-spawn tool that can delegate work+ * to either itself (when `allowSelf` is true) and/or the listed `agent_ids`.+ */+export type AgentSubagentsConfig = {+ enabled?: boolean;+ /** When true (default), the agent may spawn itself in an isolated context. */+ allowSelf?: boolean;+ /** Specific agents that may be spawned as subagents. */+ agent_ids?: string[];+};+export type Agent = {_id?: string;id: string;@@ -277,6 +290,8 @@ export type Agent = {tool_options?: AgentToolOptions;/** Skill ObjectIds the agent can invoke — phase 2 wiring in AgentConfig. */skills?: string[];+ /** Subagent spawning configuration — isolated-context child agents. */+ subagents?: AgentSubagentsConfig;};export type TAgentsMap = Record<string, Agent | undefined>;@@ -303,6 +318,7 @@ export type AgentCreateParams = {| 'support_contact'| 'tool_options'| 'skills'+ | 'subagents'>;export type AgentUpdateParams = {@@ -328,6 +344,7 @@ export type AgentUpdateParams = {| 'support_contact'| 'tool_options'| 'skills'+ | 'subagents'>;export type AgentListParams = {diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.tsindex b159f99daf..706c380c6f 100644--- a/packages/data-provider/src/types/runs.ts+++ b/packages/data-provider/src/types/runs.ts@@ -37,4 +37,33 @@ export enum StepEvents {ON_SUMMARIZE_START = 'on_summarize_start',ON_SUMMARIZE_DELTA = 'on_summarize_delta',ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',+ ON_SUBAGENT_UPDATE = 'on_subagent_update',+}++/** Lifecycle phase carried on subagent-progress envelopes (mirrors SDK SubagentUpdatePhase). */+export type SubagentUpdatePhase =+ | 'start'+ | 'run_step'+ | 'run_step_delta'+ | 'run_step_completed'+ | 'message_delta'+ | 'reasoning_delta'+ | 'stop'+ | 'error';++/** Single streamed subagent update forwarded by the SDK's SubagentExecutor. */+export interface SubagentUpdateEvent {+ runId: string;+ subagentRunId: string;+ /** Parent-side `tool_call_id` for the `subagent` tool invocation that+ * triggered this run. Surfaces from the SDK (`3.1.67-dev.2`+) so hosts+ * can correlate child progress to the parent tool call deterministically. */+ parentToolCallId?: string;+ subagentType: string;+ subagentAgentId: string;+ parentAgentId?: string;+ phase: SubagentUpdatePhase;+ data?: unknown;+ label?: string;+ timestamp: string;}diff --git a/packages/data-schemas/src/schema/agent.ts b/packages/data-schemas/src/schema/agent.tsindex b09bf04a6d..a6d893d628 100644--- a/packages/data-schemas/src/schema/agent.ts+++ b/packages/data-schemas/src/schema/agent.ts@@ -116,6 +116,11 @@ const agentSchema = new Schema<IAgent>(type: Schema.Types.Mixed,default: undefined,},+ /** Subagent spawning configuration — isolated-context child agents. */+ subagents: {+ type: Schema.Types.Mixed,+ default: undefined,+ },tenantId: {type: String,index: true,diff --git a/packages/data-schemas/src/types/agent.ts b/packages/data-schemas/src/types/agent.tsindex e66af874af..f10b0ffe76 100644--- a/packages/data-schemas/src/types/agent.ts+++ b/packages/data-schemas/src/types/agent.ts@@ -1,5 +1,10 @@import { Document, Types } from 'mongoose';-import type { GraphEdge, AgentToolOptions, AgentToolResources } from 'librechat-data-provider';+import type {+ GraphEdge,+ AgentToolOptions,+ AgentToolResources,+ AgentSubagentsConfig,+} from 'librechat-data-provider';export interface ISupportContact {name?: string;@@ -42,5 +47,7 @@ export interface IAgent extends Omit<Document, 'model'> {mcpServerNames?: string[];/** Per-tool configuration (defer_loading, allowed_callers) */tool_options?: AgentToolOptions;+ /** Subagent spawning configuration — isolated-context child agents. */+ subagents?: AgentSubagentsConfig;tenantId?: string;}