Skip to content

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

🪆 feat: Add Parent Activity Phase Summaries (#14721)

Danny Avilaa3cec67e0800
diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.js
index efa4c88fb7..c86bd8222f 100644
--- a/api/app/clients/BaseClient.js
+++ b/api/app/clients/BaseClient.js
@@ -1265,36 +1265,67 @@ class BaseClient {
return existingContent.concat(newCompletion);
}
- if (editedType !== ContentTypes.TEXT && editedType !== ContentTypes.THINK) {
- return existingContent.concat(newCompletion);
- }
-
const lastIndex = existingContent.length - 1;
const lastExisting = existingContent[lastIndex];
const firstNew = newCompletion[0];
+ /** Phased and legacy/unphased text are distinct semantic streams. Merging
+ * either direction would stamp retained text with the wrong phase. */
+ const textPhaseCompatible =
+ editedType !== ContentTypes.TEXT ||
+ (lastExisting?.phase ?? null) === (firstNew?.phase ?? null);
+ const mergesFirstPart =
+ (editedType === ContentTypes.TEXT || editedType === ContentTypes.THINK) &&
+ lastExisting?.type === firstNew?.type &&
+ firstNew?.type === editedType &&
+ textPhaseCompatible;
+ /** Phase bounds are completion-local while the run streams. Persist them
+ * in the same absolute index space as the edited response assembled
+ * here. When the first new text/think part merges into the retained tail,
+ * every completion index shifts by prefixLength - 1; otherwise it shifts
+ * by the full retained prefix. */
+ const phaseIndexOffset = mergesFirstPart ? lastIndex : existingContent.length;
+ const adjustedCompletion = newCompletion.map((part) => {
+ if (
+ part?.type !== ContentTypes.ACTIVITY_LABEL ||
+ part.activity_label_type !== 'phase' ||
+ typeof part.activity_start_index !== 'number'
+ ) {
+ return part;
+ }
+ return {
+ ...part,
+ activity_start_index: part.activity_start_index + phaseIndexOffset,
+ };
+ });
- if (lastExisting?.type !== firstNew?.type || firstNew?.type !== editedType) {
- return existingContent.concat(newCompletion);
+ if (editedType !== ContentTypes.TEXT && editedType !== ContentTypes.THINK) {
+ return existingContent.concat(adjustedCompletion);
+ }
+
+ if (!mergesFirstPart) {
+ return existingContent.concat(adjustedCompletion);
}
const mergedContent = [...existingContent];
if (editedType === ContentTypes.TEXT) {
mergedContent[lastIndex] = {
...mergedContent[lastIndex],
+ ...(firstNew.phase != null && { phase: firstNew.phase }),
[ContentTypes.TEXT]:
- (mergedContent[lastIndex][ContentTypes.TEXT] || '') + (firstNew[ContentTypes.TEXT] || ''),
+ (mergedContent[lastIndex][ContentTypes.TEXT] || '') +
+ (adjustedCompletion[0][ContentTypes.TEXT] || ''),
};
} else {
mergedContent[lastIndex] = {
...mergedContent[lastIndex],
[ContentTypes.THINK]:
(mergedContent[lastIndex][ContentTypes.THINK] || '') +
- (firstNew[ContentTypes.THINK] || ''),
+ (adjustedCompletion[0][ContentTypes.THINK] || ''),
};
}
// Add remaining completion items
- return mergedContent.concat(newCompletion.slice(1));
+ return mergedContent.concat(adjustedCompletion.slice(1));
}
async sendPayload(payload, opts = {}) {
diff --git a/api/app/clients/specs/BaseClient.test.js b/api/app/clients/specs/BaseClient.test.js
index 1cf3b45431..df9b5d1e3c 100644
--- a/api/app/clients/specs/BaseClient.test.js
+++ b/api/app/clients/specs/BaseClient.test.js
@@ -1,4 +1,4 @@
-const { Constants } = require('librechat-data-provider');
+const { Constants, ContentTypes } = require('librechat-data-provider');
const { FakeClient, initializeFakeClient } = require('./FakeClient');
function deferred() {
@@ -1797,4 +1797,52 @@ describe('BaseClient', () => {
expect(userSave[0].quotes).toBeUndefined();
});
});
+
+ describe('mergeEditedContent phase boundaries', () => {
+ test('does not merge commentary into a final answer', () => {
+ const existing = [
+ { type: ContentTypes.TEXT, text: 'Checked the deployment. ', phase: 'commentary' },
+ ];
+ const completion = [
+ { type: ContentTypes.TEXT, text: 'Everything is healthy.', phase: 'final_answer' },
+ {
+ type: ContentTypes.ACTIVITY_LABEL,
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_label: 'Verified deployment health',
+ },
+ ];
+
+ expect(TestClient.mergeEditedContent(existing, completion, ContentTypes.TEXT)).toEqual([
+ existing[0],
+ completion[0],
+ { ...completion[1], activity_start_index: 1 },
+ ]);
+ });
+
+ test.each([
+ [undefined, 'commentary'],
+ ['commentary', undefined],
+ ])('does not merge phased and unphased text (%s → %s)', (existingPhase, completionPhase) => {
+ const existing = [
+ {
+ type: ContentTypes.TEXT,
+ text: 'Retained text. ',
+ ...(existingPhase != null && { phase: existingPhase }),
+ },
+ ];
+ const completion = [
+ {
+ type: ContentTypes.TEXT,
+ text: 'New text.',
+ ...(completionPhase != null && { phase: completionPhase }),
+ },
+ ];
+
+ expect(TestClient.mergeEditedContent(existing, completion, ContentTypes.TEXT)).toEqual([
+ existing[0],
+ completion[0],
+ ]);
+ });
+ });
});
diff --git a/api/package.json b/api/package.json
index 3da12736ce..05d4488392 100644
--- a/api/package.json
+++ b/api/package.json
@@ -46,7 +46,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "^4.3.3",
- "@librechat/agents": "^3.4.3",
+ "@librechat/agents": "^3.4.4",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js
index 28c62743c8..9e8b0604d6 100644
--- a/api/server/controllers/agents/client.js
+++ b/api/server/controllers/agents/client.js
@@ -57,10 +57,15 @@ const {
buildSteerMedia,
stampSteerPartMedia,
createActivityLabelWiring,
+ createActivityPhaseWiring,
+ createAssistantPhaseStampingHandlers,
resolveActivityConfig,
+ resolveActivityPhaseConfig,
getCustomEndpointConfig,
mapCollectedMetadataToUsage,
resolveActivityLabelModel,
+ resolveActivityPhaseLabelModel,
+ traceIdForMessage,
settlePendingLabelFills,
stripActivityLabelParts,
getRequestMemories,
@@ -334,6 +339,10 @@ class AgentClient extends BaseClient {
deliveredSteer: item,
},
);
+ /** Only a COMMITTED steer is a hard semantic boundary. If its durable
+ * append failed, the drain restores the queue item and the current
+ * phase evidence must remain intact for the eventual retry. */
+ this.activityPhaseWiring?.drop?.();
} catch (error) {
/** The part and its receipt commit as one durable unit. Roll the local
* projection back when that commit fails so the drain can restore the
@@ -419,6 +428,27 @@ class AgentClient extends BaseClient {
return this.activityLabelLLMPromise;
}
+ /** Phase resolution is independently configurable and memoized per response. */
+ async resolveActivityPhaseLabelLLM() {
+ this.activityPhaseLabelLLMPromise =
+ this.activityPhaseLabelLLMPromise ??
+ resolveActivityPhaseLabelModel({
+ req: this.options.req,
+ agent: this.options.agent,
+ publicEndpoint: this.options.endpoint,
+ ids: {
+ messageId: this.responseMessageId,
+ conversationId: this.conversationId,
+ parentMessageId: this.parentMessageId,
+ },
+ db: { getUserKey: db.getUserKey, getUserKeyValues: db.getUserKeyValues },
+ }).catch((error) => {
+ this.activityPhaseLabelLLMPromise = null;
+ throw error;
+ });
+ return this.activityPhaseLabelLLMPromise;
+ }
+
/**
* Bills the label call and folds its usage into the response rollup with
* an `activity-label` tag (subagent precedent) so `metadata.usage` and the
@@ -445,6 +475,8 @@ class AgentClient extends BaseClient {
* the title convention — from locally counted text rather than going
* unbilled. Invoked only when no entry carries a real token count. */
estimate = undefined,
+ /** Separate telemetry bucket for parent phase summaries. */
+ usageType = 'activity-label',
) {
const appConfig = this.options.req?.config;
/** Provider ON EVERY ENTRY, not just the streamed event: `splitUsage`
@@ -517,7 +549,7 @@ class AgentClient extends BaseClient {
}),
...(provider != null && { provider }),
model,
- usage_type: 'activity-label',
+ usage_type: usageType,
/**
* Scoped to the GENERATION, not just the response. Editing one
* assistant response reuses its `responseMessageId` while each fresh
@@ -561,14 +593,14 @@ class AgentClient extends BaseClient {
* generation replaced it. */
{ expectedCreatedAt: this.jobCreatedAt },
).catch((err) => {
- logger.warn(`[AgentClient] Failed to emit activity-label usage: ${err?.message ?? err}`);
+ logger.warn(`[AgentClient] Failed to emit ${usageType} usage: ${err?.message ?? err}`);
});
this.pendingSubagentEmits.push(emit);
}
}
await this.recordCollectedUsage({
collectedUsage,
- context: 'activity-label',
+ context: usageType,
model,
endpointTokenConfig: labelTokenConfig,
/** The label ran elsewhere, so its config governs even when undefined. */
@@ -698,6 +730,7 @@ class AgentClient extends BaseClient {
})),
thinkingExcerpts: context.thinkingExcerpts,
lastAssistantText: context.lastAssistantText,
+ lastAssistantPhase: context.lastAssistantPhase,
...(previousLabels != null && { previousLabels }),
traceSeed,
charLimit,
@@ -731,6 +764,98 @@ class AgentClient extends BaseClient {
}
}
+ /**
+ * SDK bridge for parent phase summaries. Usage is returned as a deferred
+ * collector so the runtime can commit the durable label first and bill
+ * only summaries that actually became visible.
+ */
+ async generateActivityPhaseViaRun({
+ activities,
+ assistantContext,
+ closingTextPhase,
+ phaseIndex,
+ totalActivityCount,
+ status,
+ agentIds,
+ charLimit,
+ prompt,
+ signal,
+ }) {
+ if (typeof this.run?.generateActivityPhaseLabel !== 'function') {
+ return {};
+ }
+ const { provider, clientOptions, endpointTokenConfig, sameEndpoint } =
+ await this.resolveActivityPhaseLabelLLM();
+ const { handleLLMEnd, collected } = createMetadataAggregator();
+ let sdkPromptText;
+ const capturePrompt = {
+ handleLLMStart: (_llm, prompts) => {
+ sdkPromptText = Array.isArray(prompts) ? prompts.join('\n') : undefined;
+ },
+ handleChatModelStart: (_llm, messages) => {
+ try {
+ sdkPromptText = (messages ?? [])
+ .flat()
+ .map((message) =>
+ typeof message?.content === 'string'
+ ? message.content
+ : JSON.stringify(message?.content ?? ''),
+ )
+ .join('\n');
+ } catch {
+ // Providers with usage metadata do not need the estimate fallback.
+ }
+ },
+ };
+ let label;
+ try {
+ ({ label } = await this.run.generateActivityPhaseLabel({
+ provider,
+ clientOptions,
+ activities,
+ assistantContext,
+ closingTextPhase,
+ phaseIndex,
+ totalActivityCount,
+ status,
+ agentIds,
+ charLimit,
+ prompt,
+ sourceRunId: this.responseMessageId,
+ sourceTraceId: traceIdForMessage(this.responseMessageId),
+ responseId: this.responseMessageId,
+ traceSeed: `${this.responseMessageId}-activity-phase-${phaseIndex}`,
+ chainOptions: {
+ signal,
+ callbacks: [{ handleLLMEnd, ...capturePrompt }],
+ configurable: {
+ thread_id: this.conversationId,
+ user_id: this.user ?? this.options.req?.user?.id,
+ requestBody: { parentMessageId: this.parentMessageId },
+ },
+ },
+ }));
+ } catch (error) {
+ if (!signal?.aborted) {
+ logger.warn('[AgentClient] Activity phase generation failed', error);
+ }
+ }
+ return {
+ label,
+ collectUsage: async (completionText) =>
+ this.recordActivityLabelUsage(
+ collected,
+ clientOptions.model,
+ endpointTokenConfig,
+ sameEndpoint,
+ undefined,
+ provider,
+ () => ({ promptText: sdkPromptText ?? '', completionText: completionText ?? '' }),
+ 'activity-phase',
+ ),
+ };
+ }
+
/** Bounded settle for in-flight label fills before finalization. On
* timeout the label scope is closed and its abort controller fired, so a
* straggler cannot mutate the saved response or emit into a dead job. */
@@ -821,16 +946,15 @@ class AgentClient extends BaseClient {
* emit, whose ordering against shifted SDK indices is load-bearing.
* The chain settles on failure (warned retry), so a lost write can
* never wedge run startup. */
- this.activityLabelsMarkedPromise = GenerationJobManager.markActivityLabels(
- streamId,
- this.jobCreatedAt,
- ).catch(() =>
- GenerationJobManager.markActivityLabels(streamId, this.jobCreatedAt).catch(() => {
- logger.warn(
- `[AgentClient] Could not flag activity labels for ${streamId}; a label resolving during a resume gap may not be reconciled.`,
- );
- }),
- );
+ this.activityLabelsMarkedPromise =
+ this.activityLabelsMarkedPromise ??
+ GenerationJobManager.markActivityLabels(streamId, this.jobCreatedAt).catch(() =>
+ GenerationJobManager.markActivityLabels(streamId, this.jobCreatedAt).catch(() => {
+ logger.warn(
+ `[AgentClient] Could not flag activity labels for ${streamId}; a label resolving during a resume gap may not be reconciled.`,
+ );
+ }),
+ );
/** SDK support probe (steering-style): the Run method and the formatter
* replay skip ship together, so method presence is the capability. */
const sdkCapable = typeof Run?.prototype?.generateActivityLabel === 'function';
@@ -951,6 +1075,94 @@ class AgentClient extends BaseClient {
});
}
+ /** Builds the independently opt-in parent activity-phase collector. */
+ buildActivityPhaseWiring(streamId, abortSignal, initialSnapshot) {
+ if (!streamId || typeof Run?.prototype?.generateActivityPhaseLabel !== 'function') {
+ return undefined;
+ }
+ const agentEndpoint = this.options.agent?.endpoint ?? '';
+ const appConfig = this.options.req?.config;
+ let customEndpointConfig;
+ try {
+ customEndpointConfig = getCustomEndpointConfig({ endpoint: agentEndpoint, appConfig });
+ } catch {
+ customEndpointConfig = undefined;
+ }
+ const phaseConfig = resolveActivityPhaseConfig(
+ appConfig,
+ agentEndpoint,
+ customEndpointConfig,
+ this.options.endpoint,
+ );
+ if (!phaseConfig.enabled) {
+ return undefined;
+ }
+
+ this.activityLabelsMarkedPromise =
+ this.activityLabelsMarkedPromise ??
+ GenerationJobManager.markActivityLabels(streamId, this.jobCreatedAt).catch(() =>
+ GenerationJobManager.markActivityLabels(streamId, this.jobCreatedAt).catch(() => {
+ logger.warn(
+ `[AgentClient] Could not flag activity phases for ${streamId}; a phase resolving during a resume gap may not be reconciled.`,
+ );
+ }),
+ );
+
+ const scope = { closed: false, abort: new AbortController() };
+ this.activityLabelScopes = this.activityLabelScopes ?? [];
+ this.activityLabelScopes.push(scope);
+ const closeOnAbort = () => {
+ scope.closed = true;
+ scope.abort.abort();
+ };
+ if (abortSignal != null) {
+ if (abortSignal.aborted) {
+ closeOnAbort();
+ } else {
+ abortSignal.addEventListener('abort', closeOnAbort, { once: true });
+ scope.detach = () => abortSignal.removeEventListener('abort', closeOnAbort);
+ }
+ }
+ this.activityLabelUsageSeq =
+ this.activityLabelUsageSeq ??
+ (this.contentParts ?? []).filter((part) => part?.type === ContentTypes.ACTIVITY_LABEL).length;
+
+ const wiring = createActivityPhaseWiring({
+ maxPerRun: phaseConfig.maxPerRun,
+ charLimit: phaseConfig.charLimit,
+ prompt: phaseConfig.prompt,
+ initialSnapshot,
+ abortSignal: scope.abort.signal,
+ isClosed: () => scope.closed,
+ getContentParts: () => this.contentParts,
+ getStepIndex: (stepId) => this.stepMap?.get(stepId)?.index,
+ bumpIndexOffset: () => {
+ this.steerOffsetState.offset += 1;
+ },
+ emitLabelEvent: (index, part) =>
+ GenerationJobManager.emitChunk(
+ streamId,
+ {
+ event: ActivityLabelEvents.ON_ACTIVITY_LABEL,
+ data: {
+ index,
+ part,
+ responseMessageId: this.responseMessageId,
+ conversationId: this.conversationId,
+ },
+ },
+ { durable: true, expectedCreatedAt: this.jobCreatedAt },
+ ),
+ trackPendingFill: (fillDone) => {
+ this.pendingActivityLabelFills = this.pendingActivityLabelFills ?? [];
+ this.pendingActivityLabelFills.push(fillDone);
+ },
+ generatePhase: (payload) => this.generateActivityPhaseViaRun(payload),
+ });
+ this.activityPhaseWiring = wiring;
+ return wiring;
+ }
+
/**
* `AgentClient` is not opinionated about vision requests, so we don't do anything here
* @param {MongoFile[]} attachments
@@ -2058,6 +2270,48 @@ class AgentClient extends BaseClient {
);
}
+ /**
+ * Rebase parent activity bounds after completion-time content reshaping.
+ * Object identity links retained parts back to their pre-reshape positions,
+ * so prepended skill cards cannot enter a phase and a filtered-away leading
+ * reasoning part advances the bound to the first retained child.
+ *
+ * @param {Array<import('librechat-data-provider').ContentPart | null | undefined>} previousParts
+ */
+ rebaseActivityPhaseBounds(previousParts) {
+ if (!Array.isArray(previousParts) || !Array.isArray(this.contentParts)) {
+ return;
+ }
+ const retainedIndexes = new Map(this.contentParts.map((part, index) => [part, index]));
+ for (let markerIndex = 0; markerIndex < this.contentParts.length; markerIndex += 1) {
+ const marker = this.contentParts[markerIndex];
+ if (
+ marker?.type !== ContentTypes.ACTIVITY_LABEL ||
+ marker.activity_label_type !== 'phase' ||
+ typeof marker.activity_start_index !== 'number'
+ ) {
+ continue;
+ }
+ const previousMarkerIndex = previousParts.indexOf(marker);
+ if (previousMarkerIndex < 0) {
+ continue;
+ }
+ const previousStartIndex = Math.min(
+ previousMarkerIndex,
+ Math.max(0, marker.activity_start_index),
+ );
+ let nextStartIndex = markerIndex;
+ for (let index = previousStartIndex; index < previousMarkerIndex; index += 1) {
+ const retainedIndex = retainedIndexes.get(previousParts[index]);
+ if (retainedIndex != null && retainedIndex < markerIndex) {
+ nextStartIndex = retainedIndex;
+ break;
+ }
+ }
+ marker.activity_start_index = nextStartIndex;
+ }
+ }
+
/**
* Surface any human-in-the-loop interrupt the SDK captured during the most
* recent `processStream` / `resume`. When the run paused for tool approval (or
@@ -2165,6 +2419,9 @@ class AgentClient extends BaseClient {
const paused = await GenerationJobManager.approvals.pause(streamId, pendingAction, {
expectedCreatedAt: this.jobCreatedAt,
...(discoveredTools.length > 0 ? { discoveredTools } : {}),
+ ...(this.activityPhaseWiring?.snapshot != null && {
+ activityPhaseSnapshot: this.activityPhaseWiring.snapshot(),
+ }),
persistencePending: true,
});
if (!paused) {
@@ -2518,6 +2775,12 @@ class AgentClient extends BaseClient {
});
}
+ const activityLabel = this.buildActivityLabelWiring(streamId, abortController.signal);
+ const activityPhase = this.buildActivityPhaseWiring(streamId, abortController.signal);
+ const offsetHandlers = createSteerIndexOffsetHandlers(
+ this.options.eventHandlers,
+ this.steerOffsetState,
+ );
const createRunPromise = createRun({
agents,
messages,
@@ -2531,17 +2794,19 @@ class AgentClient extends BaseClient {
// boundary and inject them into graph state. The offset wrapper
// shifts SDK content indices past any spliced steer parts.
steering: this.buildSteerWiring(streamId),
- activityLabel: this.buildActivityLabelWiring(streamId, abortController.signal),
+ activityLabel,
+ activityPhase,
indexTokenCountMap,
initialSummary,
initialSessions,
calibrationRatio,
runId: this.responseMessageId,
signal: abortController.signal,
- customHandlers: createSteerIndexOffsetHandlers(
- this.options.eventHandlers,
- this.steerOffsetState,
- ),
+ /** The phase wrapper stays outermost: it claims and offsets the
+ * parent slot before the text step reaches the normal handlers. */
+ customHandlers:
+ activityPhase?.handlers(offsetHandlers) ??
+ (activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers),
requestBody: config.configurable.requestBody,
user: createSafeUser(this.options.req?.user),
tenantId: this.options.req?.user?.tenantId,
@@ -2663,6 +2928,7 @@ class AgentClient extends BaseClient {
*/
await this.settleActivityLabels();
+ const contentBeforeReshape = [...this.contentParts];
const manualPrimed = this.options.agent?.manualSkillPrimes ?? [];
if (manualPrimed.length > 0) {
const runId = this.responseMessageId ?? 'skill-prime';
@@ -2671,6 +2937,7 @@ class AgentClient extends BaseClient {
}
this.applyHideSequentialOutputsFilter();
+ this.rebaseActivityPhaseBounds(contentBeforeReshape);
} catch (err) {
if (abortController.signal.aborted) {
logger.debug(
@@ -2788,6 +3055,7 @@ class AgentClient extends BaseClient {
* @param {Agents.ToolApprovalDecisionMap | { answer: string }} params.resumeValue
* @param {Array} [params.seedContent] - content aggregated before the pause
* @param {Array<import('@librechat/agents').RunStep>} [params.runSteps] - run steps emitted before the pause
+ * @param {import('@librechat/api').ActivityPhaseSnapshot} [params.activityPhaseSnapshot]
* @param {AbortController} [params.abortController]
* @param {Pick<import('@langchain/langgraph').Command, 'update' | 'goto'>} [params.commandOptions]
*/
@@ -2799,6 +3067,7 @@ class AgentClient extends BaseClient {
commandOptions,
userMCPAuthMap,
discoveredToolNames,
+ activityPhaseSnapshot,
}) {
/** @type {Partial<GraphRunnableConfig>} */
let config;
@@ -2878,6 +3147,19 @@ class AgentClient extends BaseClient {
const initialSessions = buildInitialToolSessions({ skillSessions, agents });
const streamId = this.options.req?._resumableStreamId;
+ const activityLabel = this.buildActivityLabelWiring(streamId, abortController.signal);
+ const activityPhase = this.buildActivityPhaseWiring(
+ streamId,
+ abortController.signal,
+ activityPhaseSnapshot,
+ );
+ const offsetHandlers = createSteerIndexOffsetHandlers(
+ createContentIndexOffsetHandlers(
+ this.options.eventHandlers,
+ Array.isArray(seedContent) ? seedContent : [],
+ ),
+ this.steerOffsetState,
+ );
run = await createRun({
agents,
// State (messages, tool calls) is rehydrated from the checkpoint by
@@ -2892,7 +3174,8 @@ class AgentClient extends BaseClient {
steering: this.buildSteerWiring(streamId),
// Activity labels likewise survive pause/resume: post-resume tool
// batches keep claiming slots and generating group headers.
- activityLabel: this.buildActivityLabelWiring(streamId, abortController.signal),
+ activityLabel,
+ activityPhase,
// Replay deferred tools discovered before the pause. With `messages: []` the
// discovery scan finds nothing, so these names restore the schemas to the
// rebuilt model binding. Undefined/empty for non-deferred turns is a no-op.
@@ -2906,13 +3189,9 @@ class AgentClient extends BaseClient {
// type mismatch, is silently dropped against) the pre-pause content. The
// steer wrapper composes on top: resumed indices shift by seed + any
// steer parts spliced in while the resumed segment streams.
- customHandlers: createSteerIndexOffsetHandlers(
- createContentIndexOffsetHandlers(
- this.options.eventHandlers,
- Array.isArray(seedContent) ? seedContent : [],
- ),
- this.steerOffsetState,
- ),
+ customHandlers:
+ activityPhase?.handlers(offsetHandlers) ??
+ (activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers),
requestBody: config.configurable.requestBody,
user: createSafeUser(this.options.req?.user),
tenantId: this.options.req?.user?.tenantId,
@@ -2981,7 +3260,9 @@ class AgentClient extends BaseClient {
// before resume finalize/re-pause persistence reads `this.contentParts`, so a
// resumed sequential chain doesn't persist/emit outputs hide_sequential_outputs
// is meant to hide.
+ const contentBeforeReshape = [...this.contentParts];
this.applyHideSequentialOutputsFilter();
+ this.rebaseActivityPhaseBounds(contentBeforeReshape);
} catch (err) {
if (abortController.signal.aborted) {
logger.debug(
diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.js
index 8c0f643507..872d05369a 100644
--- a/api/server/controllers/agents/client.test.js
+++ b/api/server/controllers/agents/client.test.js
@@ -162,6 +162,30 @@ describe('AgentClient - applyHideSequentialOutputsFilter', () => {
AgentClient.prototype.applyHideSequentialOutputsFilter.call(ctx);
expect(ctx.contentParts).toEqual([textPart('a'), textPart('b')]);
});
+
+ it('rebases phase bounds across skill prepends and sequential filtering', () => {
+ const reasoning = { type: ContentTypes.THINK, think: 'checking' };
+ const activityTool = toolCallPart('activity-tool');
+ const phase = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ activity_label: 'Resolved the session issue',
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ };
+ const final = textPart('final');
+ const previousParts = [reasoning, activityTool, phase, final];
+ const skillCard = toolCallPart('manual-skill');
+ const ctx = {
+ options: { agent: { hide_sequential_outputs: true } },
+ contentParts: [skillCard, ...previousParts],
+ };
+
+ AgentClient.prototype.applyHideSequentialOutputsFilter.call(ctx);
+ AgentClient.prototype.rebaseActivityPhaseBounds.call(ctx, previousParts);
+
+ expect(ctx.contentParts).toEqual([skillCard, activityTool, phase, final]);
+ expect(phase.activity_start_index).toBe(1);
+ });
});
describe('AgentClient - startup telemetry', () => {
diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.js
index 2bd1b50b5d..0d375d804b 100644
--- a/api/server/controllers/agents/resume.js
+++ b/api/server/controllers/agents/resume.js
@@ -929,6 +929,7 @@ const ResumeAgentController = async (req, res, next, initializeClient, addTitle)
// Replay deferred tools discovered before the pause (captured at pause). The rebuilt
// graph passes `messages: []`, so without these the model would lose their schemas.
discoveredToolNames: job.metadata?.discoveredTools,
+ activityPhaseSnapshot: job.metadata?.activityPhaseSnapshot,
});
// The model may pause AGAIN (another tool, or a follow-up question). The pending
diff --git a/client/src/components/Chat/Messages/Content/ActivityPhaseGroup.tsx b/client/src/components/Chat/Messages/Content/ActivityPhaseGroup.tsx
new file mode 100644
index 0000000000..cf73a7e9f3
--- /dev/null
+++ b/client/src/components/Chat/Messages/Content/ActivityPhaseGroup.tsx
@@ -0,0 +1,87 @@
+import { ChevronDown, ListTree } from 'lucide-react';
+import { ContentTypes } from 'librechat-data-provider';
+import type { TMessageContentParts } from 'librechat-data-provider';
+import type { ReactNode } from 'react';
+import { getActivityLabelText } from '~/utils/activityLabels';
+import { EmptyText } from './Parts';
+import Container from './Container';
+import { cn } from '~/utils';
+
+type ActivityPhasePart = Extract<TMessageContentParts, { type: ContentTypes.ACTIVITY_LABEL }> & {
+ activity_label_type?: 'phase';
+ activity_start_index?: number;
+};
+
+export default function ActivityPhaseGroup({
+ labelPart,
+ children,
+ hasContent,
+ showCursor = false,
+}: {
+ labelPart: ActivityPhasePart;
+ children: ReactNode;
+ hasContent: boolean;
+ showCursor?: boolean;
+}) {
+ const label = getActivityLabelText(labelPart);
+ const hasFailure = labelPart.status === 'failed' || labelPart.status === 'partial';
+ const cursor = showCursor ? (
+ <Container>
+ <EmptyText />
+ </Container>
+ ) : null;
+ if (!label) {
+ return <>{children}</>;
+ }
+ const group = !hasContent ? (
+ <div className="my-2 flex min-h-10 w-full items-center gap-2 rounded-lg border border-border-light bg-surface-secondary/40 px-3 py-2 text-text-secondary">
+ <ListTree
+ className={cn('size-4 shrink-0', hasFailure && 'text-amber-600 dark:text-amber-400')}
+ aria-hidden="true"
+ />
+ <span
+ className={cn(
+ 'min-w-0 flex-1 truncate text-sm font-medium',
+ hasFailure && 'text-amber-600 dark:text-amber-400',
+ )}
+ role="status"
+ title={label}
+ >
+ {label}
+ </span>
+ </div>
+ ) : (
+ <details className="group/activity-phase my-2 w-full rounded-lg border border-border-light bg-surface-secondary/40">
+ <summary
+ className="flex min-h-10 cursor-pointer list-none items-center gap-2 px-3 py-2 text-text-secondary transition-colors hover:bg-surface-hover hover:text-text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring-primary [&::-webkit-details-marker]:hidden"
+ aria-label={label}
+ title={label}
+ >
+ <ListTree
+ className={cn('size-4 shrink-0', hasFailure && 'text-amber-600 dark:text-amber-400')}
+ aria-hidden="true"
+ />
+ <span
+ className={cn(
+ 'min-w-0 flex-1 truncate text-sm font-medium',
+ hasFailure && 'text-amber-600 dark:text-amber-400',
+ )}
+ role="status"
+ >
+ {label}
+ </span>
+ <ChevronDown
+ className="size-4 shrink-0 transition-transform duration-200 group-open/activity-phase:rotate-180"
+ aria-hidden="true"
+ />
+ </summary>
+ <div className="border-t border-border-light px-3 py-2">{children}</div>
+ </details>
+ );
+ return (
+ <>
+ {group}
+ {cursor}
+ </>
+ );
+}
diff --git a/client/src/components/Chat/Messages/Content/ApprovalContext.tsx b/client/src/components/Chat/Messages/Content/ApprovalContext.tsx
index fa3e4382de..2b54a4664e 100644
--- a/client/src/components/Chat/Messages/Content/ApprovalContext.tsx
+++ b/client/src/components/Chat/Messages/Content/ApprovalContext.tsx
@@ -84,6 +84,10 @@ interface ApprovalContextValue {
getStatus: (actionId: string) => ActionStatus;
/** Set an action's submission status (driven by the cards' submit via `useResumeSubmit`). */
setStatus: (actionId: string, status: ActionStatus) => void;
+ /** Restore a free-form question answer after transient phase-slice remounts. */
+ getAskAnswerDraft: (actionId: string) => string;
+ /** Retain a free-form question answer for this response message's lifetime. */
+ setAskAnswerDraft: (actionId: string, answer: string) => void;
}
const ApprovalContext = createContext<ApprovalContextValue | null>(null);
@@ -107,6 +111,8 @@ const FALLBACK: ApprovalContextValue = {
isReady: () => false,
getStatus: () => 'idle',
setStatus: () => undefined,
+ getAskAnswerDraft: () => '',
+ setAskAnswerDraft: () => undefined,
};
const isExpiredError = (error: unknown): boolean => {
@@ -136,6 +142,7 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
* never propagate past the memoized value). */
const decisionsRef = useRef(new Map<string, Map<string, Agents.ToolApprovalResolution>>());
const registeredRef = useRef(new Map<string, Set<string>>());
+ const askAnswerDraftsRef = useRef(new Map<string, string>());
const [version, bump] = useState(0);
const rerender = useCallback(() => bump((v) => v + 1), []);
const [statusByAction, setStatusByAction] = useState<Record<string, ActionStatus>>({});
@@ -162,12 +169,14 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
return;
}
set.delete(toolCallId);
- // Also drop any decision it held so a stale entry can't linger.
- decisionsRef.current.get(actionId)?.delete(toolCallId);
if (set.size === 0) {
registeredRef.current.delete(actionId);
- decisionsRef.current.delete(actionId);
}
+ /** Keep the decision for the provider's message-scoped lifetime. A
+ * phase label can resolve while an approval card is visible, moving
+ * that card through a nested phase segment; its transient unmount must
+ * not erase the user's selection. Unregistered decisions are excluded
+ * from submit/readiness and disappear with this provider. */
rerender();
},
[rerender],
@@ -202,10 +211,17 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
[],
);
- const getDecisions = useCallback(
- (actionId: string) => Array.from(decisionsRef.current.get(actionId)?.values() ?? []),
- [],
- );
+ const getDecisions = useCallback((actionId: string) => {
+ const registered = registeredRef.current.get(actionId);
+ const decisions = decisionsRef.current.get(actionId);
+ if (registered == null || decisions == null) {
+ return [];
+ }
+ return [...registered].flatMap((toolCallId) => {
+ const decision = decisions.get(toolCallId);
+ return decision == null ? [] : [decision];
+ });
+ }, []);
const isReady = useCallback((actionId: string) => {
const registered = registeredRef.current.get(actionId);
@@ -230,6 +246,19 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
setStatusByAction((prev) => ({ ...prev, [actionId]: status }));
}, []);
+ const getAskAnswerDraft = useCallback(
+ (actionId: string) => askAnswerDraftsRef.current.get(actionId) ?? '',
+ [],
+ );
+
+ const setAskAnswerDraft = useCallback((actionId: string, answer: string) => {
+ if (answer.length === 0) {
+ askAnswerDraftsRef.current.delete(actionId);
+ return;
+ }
+ askAnswerDraftsRef.current.set(actionId, answer);
+ }, []);
+
const value = useMemo<ApprovalContextValue>(
() => ({
version,
@@ -243,6 +272,8 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
isReady,
getStatus,
setStatus,
+ getAskAnswerDraft,
+ setAskAnswerDraft,
}),
[
version,
@@ -256,6 +287,8 @@ export default function ApprovalProvider({ children }: { children: React.ReactNo
isReady,
getStatus,
setStatus,
+ getAskAnswerDraft,
+ setAskAnswerDraft,
],
);
diff --git a/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx b/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx
index ccea2ef9f7..7e5d76da2f 100644
--- a/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx
+++ b/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx
@@ -2,7 +2,7 @@ import { useContext, useMemo, useState } from 'react';
import { ChevronUp, TriangleAlert } from 'lucide-react';
import { Button, TextareaAutosize } from '@librechat/client';
import type { Agents } from 'librechat-data-provider';
-import { useAskSubmitStatus, useResumeSubmit } from './ApprovalContext';
+import { useApprovalContext, useAskSubmitStatus, useResumeSubmit } from './ApprovalContext';
import useAskAnswerMode from '~/hooks/Input/useAskAnswerMode';
import { ChatContext } from '~/Providers/ChatContext';
import { splitOtherOption } from '~/utils/approval';
@@ -25,9 +25,10 @@ export default function AskUserQuestion({
question: Agents.AskUserQuestionRequest;
}) {
const localize = useLocalize();
+ const { getAskAnswerDraft, setAskAnswerDraft } = useApprovalContext();
const { getAskStatus } = useAskSubmitStatus();
const { submitAskAnswer } = useResumeSubmit();
- const [answer, setAnswer] = useState('');
+ const [answer, setAnswer] = useState(() => getAskAnswerDraft(actionId));
const [localChecked, setLocalChecked] = useState<number[]>([]);
/**
* The composer popover is the primary answer surface — while it's VISIBLE
@@ -152,7 +153,10 @@ export default function AskUserQuestion({
<TextareaAutosize
value={answer}
disabled={locked}
- onChange={(e) => setAnswer(e.target.value)}
+ onChange={(e) => {
+ setAnswer(e.target.value);
+ setAskAnswerDraft(actionId, e.target.value);
+ }}
minRows={2}
maxRows={12}
placeholder={otherLabel ?? localize('com_ui_your_answer')}
diff --git a/client/src/components/Chat/Messages/Content/ContentParts.tsx b/client/src/components/Chat/Messages/Content/ContentParts.tsx
index 116f51f379..e22b940ff8 100644
--- a/client/src/components/Chat/Messages/Content/ContentParts.tsx
+++ b/client/src/components/Chat/Messages/Content/ContentParts.tsx
@@ -9,13 +9,15 @@ import type {
import type { ReactNode, ReactElement } from 'react';
import type { ToolCallGroupExpansionState } from './ToolCallGroup';
import { mapAttachments, filterAttachmentsForPart, groupSequentialToolCalls } from '~/utils';
+import { groupActivityPhases, lastVisibleContentIdx } from '~/utils/activityLabels';
import { ParallelContentRenderer, type PartWithIndex } from './ParallelContent';
import { EditTextPart, EmptyText, AgentUpdate } from './Parts';
-import { lastVisibleContentIdx } from '~/utils/activityLabels';
import { MessageContext, SearchContext } from '~/Providers';
import PendingSkillCall from './Parts/PendingSkillCall';
+import ActivityPhaseGroup from './ActivityPhaseGroup';
import ApprovalProvider from './ApprovalContext';
import MemoryArtifacts from './MemoryArtifacts';
+import Sources from '~/components/Web/Sources';
import ToolCallGroup from './ToolCallGroup';
import Container from './Container';
import Part from './Part';
@@ -147,6 +149,14 @@ type ContentPartsProps = {
| ((value: number) => void | React.Dispatch<React.SetStateAction<number>>)
| null
| undefined;
+ /** Internal recursion guard for nested phase segments. */
+ nestedActivityPhase?: boolean;
+ /** Absolute transcript index represented by `content[0]` in a phase slice. */
+ contentIndexOffset?: number;
+ /** Message-wide steer attribution retained across nested phase segments. */
+ resumeAuthors?: ReadonlyMap<number, string | undefined>;
+ /** Message-wide tool-group expansion overrides retained across phase slices. */
+ toolGroupExpansionState?: Map<string, ToolCallGroupExpansionState>;
};
/**
@@ -172,15 +182,20 @@ const ContentParts = memo(function ContentParts({
isCreatedByUser,
isLatestMessage,
createdAt,
+ nestedActivityPhase = false,
+ contentIndexOffset = 0,
+ resumeAuthors,
+ toolGroupExpansionState,
}: ContentPartsProps) {
const attachmentMap = useMemo(() => mapAttachments(attachments ?? []), [attachments]);
const effectiveIsSubmitting = isLatestMessage ? isSubmitting : false;
- const toolGroupExpansionRef = useRef(new Map<string, ToolCallGroupExpansionState>());
+ const localToolGroupExpansionRef = useRef(new Map<string, ToolCallGroupExpansionState>());
+ const expansionState = toolGroupExpansionState ?? localToolGroupExpansionRef.current;
const fallbackScopeRef = useRef({ messageId, scope: 0 });
if (fallbackScopeRef.current.messageId !== messageId) {
if (!effectiveIsSubmitting) {
fallbackScopeRef.current.scope += 1;
- toolGroupExpansionRef.current.clear();
+ expansionState.clear();
}
fallbackScopeRef.current.messageId = messageId;
}
@@ -189,12 +204,12 @@ const ContentParts = memo(function ContentParts({
const handleGroupExpansionChange = useCallback(
(groupId: string, state: ToolCallGroupExpansionState) => {
if (!state.userOverride) {
- toolGroupExpansionRef.current.delete(groupId);
+ expansionState.delete(groupId);
return;
}
- toolGroupExpansionRef.current.set(groupId, state);
+ expansionState.set(groupId, state);
},
- [],
+ [expansionState],
);
/**
@@ -256,6 +271,7 @@ const ContentParts = memo(function ContentParts({
const renderPart = useCallback(
(part: TMessageContentParts, idx: number, isLastPart: boolean) => {
+ const localIdx = idx - contentIndexOffset;
return (
<PartWithContext
key={`provider-${messageId}-${idx}`}
@@ -267,7 +283,7 @@ const ContentParts = memo(function ContentParts({
conversationId={conversationId}
isLatestMessage={isLatestMessage}
isCreatedByUser={isCreatedByUser}
- nextType={content?.[idx + 1]?.type}
+ nextType={content?.[localIdx + 1]?.type}
isSubmitting={effectiveIsSubmitting}
partAttachments={filterAttachmentsForPart(
attachmentMap[getToolCallId(part)],
@@ -279,6 +295,7 @@ const ContentParts = memo(function ContentParts({
[
attachmentMap,
content,
+ contentIndexOffset,
conversationId,
effectiveIsSubmitting,
isCreatedByUser,
@@ -290,6 +307,7 @@ const ContentParts = memo(function ContentParts({
const renderGroupedPart = useCallback(
(part: TMessageContentParts, idx: number, isLastPart: boolean, onToolExpand?: () => void) => {
+ const localIdx = idx - contentIndexOffset;
return (
<PartWithContext
key={`provider-${messageId}-${idx}`}
@@ -301,7 +319,7 @@ const ContentParts = memo(function ContentParts({
conversationId={conversationId}
isLatestMessage={isLatestMessage}
isCreatedByUser={isCreatedByUser}
- nextType={content?.[idx + 1]?.type}
+ nextType={content?.[localIdx + 1]?.type}
isSubmitting={effectiveIsSubmitting}
partAttachments={filterAttachmentsForPart(
attachmentMap[getToolCallId(part)],
@@ -315,6 +333,7 @@ const ContentParts = memo(function ContentParts({
[
attachmentMap,
content,
+ contentIndexOffset,
conversationId,
effectiveIsSubmitting,
isCreatedByUser,
@@ -331,18 +350,19 @@ const ContentParts = memo(function ContentParts({
* for the top-level `authorHeader`. Read BEFORE applying the current
* part's own handoff, so a resume point that IS an agent update keeps the
* pre-handoff author and lets the real marker announce the transition. */
- const { sequentialParts, postSteerAuthors } = useMemo(() => {
+ const { sequentialParts, detectedResumeAuthors } = useMemo(() => {
const parts: PartWithIndex[] = [];
const authors = new Map<number, string | undefined>();
if (!content) {
- return { sequentialParts: parts, postSteerAuthors: authors };
+ return { sequentialParts: parts, detectedResumeAuthors: authors };
}
let prevType: string | undefined;
let activeAgentId: string | undefined;
- content.forEach((part, idx) => {
+ content.forEach((part, localIdx) => {
if (!part) {
return;
}
+ const idx = localIdx + contentIndexOffset;
if (prevType === ContentTypes.STEER && part.type !== ContentTypes.STEER) {
authors.set(idx, activeAgentId);
}
@@ -352,8 +372,9 @@ const ContentParts = memo(function ContentParts({
prevType = part.type;
parts.push({ part, idx });
});
- return { sequentialParts: parts, postSteerAuthors: authors };
- }, [content]);
+ return { sequentialParts: parts, detectedResumeAuthors: authors };
+ }, [content, contentIndexOffset]);
+ const postSteerAuthors = resumeAuthors ?? detectedResumeAuthors;
const groupedParts = useMemo(
() =>
@@ -398,10 +419,11 @@ const ContentParts = memo(function ContentParts({
if (edit === true && enterEdit && setSiblingIdx) {
return (
<>
- {(content ?? []).map((part, idx) => {
+ {(content ?? []).map((part, localIdx) => {
if (!part) {
return null;
}
+ const idx = localIdx + contentIndexOffset;
const isTextPart =
part?.type === ContentTypes.TEXT ||
typeof (part as unknown as Agents.MessageContentText)?.text === 'string';
@@ -434,18 +456,92 @@ const ContentParts = memo(function ContentParts({
);
}
+ const phaseSegments = nestedActivityPhase ? undefined : groupActivityPhases(content);
+ if (phaseSegments != null) {
+ const relativeGlobalLastContentIdx = lastVisibleContentIdx(content ?? []);
+ const globalLastContentIdx =
+ relativeGlobalLastContentIdx < 0 ? -1 : relativeGlobalLastContentIdx + contentIndexOffset;
+ const renderSegment = (
+ segmentContent: Array<TMessageContentParts | undefined>,
+ segmentStartIndex: number,
+ key: string,
+ ) => {
+ const localLastContentIdx = globalLastContentIdx - segmentStartIndex;
+ return (
+ <ContentParts
+ key={key}
+ content={segmentContent}
+ messageId={messageId}
+ createdAt={createdAt}
+ authorHeader={authorHeader}
+ conversationId={conversationId}
+ attachments={attachments}
+ searchResults={searchResults}
+ isCreatedByUser={isCreatedByUser}
+ isLast={isLast && segmentContent[localLastContentIdx] != null}
+ isSubmitting={isSubmitting}
+ isLatestMessage={isLatestMessage}
+ nestedActivityPhase
+ contentIndexOffset={segmentStartIndex}
+ resumeAuthors={postSteerAuthors}
+ toolGroupExpansionState={expansionState}
+ />
+ );
+ };
+ const hasParallelContent = content?.some((part) => part?.groupId != null) === true;
+ return (
+ <ApprovalProvider>
+ <SearchContext.Provider value={{ searchResults }}>
+ <MemoryArtifacts attachments={attachments} />
+ {hasParallelContent && (
+ <Sources messageId={messageId} conversationId={conversationId || undefined} />
+ )}
+ {renderPendingSkills()}
+ {phaseSegments.map((segment, index) =>
+ segment.type === 'phase' ? (
+ <ActivityPhaseGroup
+ key={`activity-phase-${messageId}-${segment.labelIndex}`}
+ labelPart={segment.labelPart}
+ hasContent={segment.hasContent}
+ showCursor={
+ isLast &&
+ effectiveIsSubmitting &&
+ segment.labelIndex + contentIndexOffset === globalLastContentIdx
+ }
+ >
+ {renderSegment(
+ segment.content,
+ segment.startIndex + contentIndexOffset,
+ `phase-content-${index}`,
+ )}
+ </ActivityPhaseGroup>
+ ) : (
+ renderSegment(
+ segment.content,
+ segment.startIndex + contentIndexOffset,
+ `phase-adjacent-${index}`,
+ )
+ ),
+ )}
+ </SearchContext.Provider>
+ </ApprovalProvider>
+ );
+ }
+
const safeContent = content ?? [];
const showEmptyCursor = safeContent.length === 0 && effectiveIsSubmitting;
/** Skips trailing BLANK label reservations — they render nothing, and
* counting one as last would strip the streaming cursor from the last
* VISIBLE part until the next delta. */
- const lastContentIdx = lastVisibleContentIdx(safeContent);
+ const relativeLastContentIdx = lastVisibleContentIdx(safeContent);
+ const lastContentIdx =
+ relativeLastContentIdx < 0 ? -1 : relativeLastContentIdx + contentIndexOffset;
// Parallel content: use dedicated renderer with columns (TMessageContentParts includes ContentMetadata)
const hasParallelContent = safeContent.some((part) => part?.groupId != null);
if (hasParallelContent) {
- return (
- <ApprovalProvider>
+ const parallelContent = (
+ <>
{renderPendingSkills()}
<ParallelContentRenderer
content={content}
@@ -457,61 +553,70 @@ const ContentParts = memo(function ContentParts({
isSubmitting={effectiveIsSubmitting}
renderPart={renderPart}
renderResumeAttribution={renderResumeAttribution}
+ showDecorations={!nestedActivityPhase}
+ contentIndexOffset={contentIndexOffset}
/>
- </ApprovalProvider>
+ </>
+ );
+ return nestedActivityPhase ? (
+ parallelContent
+ ) : (
+ <ApprovalProvider>{parallelContent}</ApprovalProvider>
);
}
// Sequential content: render parts in order (90% of cases)
- return (
- <ApprovalProvider>
- <SearchContext.Provider value={{ searchResults }}>
- <MemoryArtifacts attachments={attachments} />
- {renderPendingSkills()}
- {showEmptyCursor && (
- <Container>
- <EmptyText />
- </Container>
- )}
- {groupedParts.flatMap((group) => {
- const firstIdx = group.type === 'single' ? group.part.idx : (group.parts[0]?.idx ?? -1);
- const nodes: ReactElement[] = [];
- const attribution = renderResumeAttribution(firstIdx);
- if (attribution != null) {
- nodes.push(attribution);
- }
- if (group.type === 'single') {
- const { part, idx } = group.part;
- nodes.push(renderPart(part, idx, idx === lastContentIdx));
- return nodes;
- }
- const { groupId } = group;
- nodes.push(
- <ToolCallGroup
- key={`tool-group-${groupId}`}
- parts={group.parts}
- isSubmitting={effectiveIsSubmitting}
- /** The label part is CONSUMED into the header, not listed in
- * `parts` — a filled label at the content tail must still
- * mark its group as last or nothing holds the streaming
- * cursor until the next delta. */
- isLast={
- group.parts.some((p) => p.idx === lastContentIdx) ||
- group.labelPart?.idx === lastContentIdx
- }
- renderPart={renderGroupedPart}
- lastContentIdx={lastContentIdx}
- groupAttachments={group.groupAttachments}
- initialExpansionState={toolGroupExpansionRef.current.get(groupId)}
- onExpansionChange={(state) => handleGroupExpansionChange(groupId, state)}
- labelPart={group.labelPart}
- />,
- );
+ const sequentialContent = (
+ <SearchContext.Provider value={{ searchResults }}>
+ {!nestedActivityPhase && <MemoryArtifacts attachments={attachments} />}
+ {!nestedActivityPhase && renderPendingSkills()}
+ {showEmptyCursor && (
+ <Container>
+ <EmptyText />
+ </Container>
+ )}
+ {groupedParts.flatMap((group) => {
+ const firstIdx = group.type === 'single' ? group.part.idx : (group.parts[0]?.idx ?? -1);
+ const nodes: ReactElement[] = [];
+ const attribution = renderResumeAttribution(firstIdx);
+ if (attribution != null) {
+ nodes.push(attribution);
+ }
+ if (group.type === 'single') {
+ const { part, idx } = group.part;
+ nodes.push(renderPart(part, idx, idx === lastContentIdx));
return nodes;
- })}
- </SearchContext.Provider>
- </ApprovalProvider>
+ }
+ const { groupId } = group;
+ nodes.push(
+ <ToolCallGroup
+ key={`tool-group-${groupId}`}
+ parts={group.parts}
+ isSubmitting={effectiveIsSubmitting}
+ /** The label part is CONSUMED into the header, not listed in
+ * `parts` — a filled label at the content tail must still
+ * mark its group as last or nothing holds the streaming
+ * cursor until the next delta. */
+ isLast={
+ group.parts.some((p) => p.idx === lastContentIdx) ||
+ group.labelPart?.idx === lastContentIdx
+ }
+ renderPart={renderGroupedPart}
+ lastContentIdx={lastContentIdx}
+ groupAttachments={group.groupAttachments}
+ initialExpansionState={expansionState.get(groupId)}
+ onExpansionChange={(state) => handleGroupExpansionChange(groupId, state)}
+ labelPart={group.labelPart}
+ />,
+ );
+ return nodes;
+ })}
+ </SearchContext.Provider>
);
+ if (nestedActivityPhase) {
+ return sequentialContent;
+ }
+ return <ApprovalProvider>{sequentialContent}</ApprovalProvider>;
});
export default ContentParts;
diff --git a/client/src/components/Chat/Messages/Content/ParallelContent.tsx b/client/src/components/Chat/Messages/Content/ParallelContent.tsx
index 0da7fc0dd0..23ef8ec695 100644
--- a/client/src/components/Chat/Messages/Content/ParallelContent.tsx
+++ b/client/src/components/Chat/Messages/Content/ParallelContent.tsx
@@ -35,6 +35,7 @@ export type ParallelSection = {
*/
export function groupParallelContent(
content: Array<TMessageContentParts | undefined> | undefined,
+ contentIndexOffset = 0,
): { parallelSections: ParallelSection[]; sequentialParts: PartWithIndex[] } {
if (!content) {
return { parallelSections: [], sequentialParts: [] };
@@ -45,10 +46,11 @@ export function groupParallelContent(
const placeholderAgents = new Map<number, Set<string>>();
const noGroup: PartWithIndex[] = [];
- content.forEach((part, idx) => {
+ content.forEach((part, localIdx) => {
if (!part) {
return;
}
+ const idx = localIdx + contentIndexOffset;
// Read metadata directly from content part (TMessageContentParts includes ContentMetadata)
const { groupId } = part;
@@ -225,6 +227,9 @@ type ParallelContentRendererProps = {
* carries per-agent identity.
*/
renderResumeAttribution?: (idx: number) => React.ReactNode;
+ showDecorations?: boolean;
+ /** Absolute transcript index represented by `content[0]` in a phase slice. */
+ contentIndexOffset?: number;
};
/**
@@ -241,16 +246,20 @@ export const ParallelContentRenderer = memo(function ParallelContentRenderer({
isSubmitting,
renderPart,
renderResumeAttribution,
+ showDecorations = true,
+ contentIndexOffset = 0,
}: ParallelContentRendererProps) {
const { parallelSections, sequentialParts } = useMemo(
- () => groupParallelContent(content),
- [content],
+ () => groupParallelContent(content, contentIndexOffset),
+ [content, contentIndexOffset],
);
/** Same walk-back as `ContentParts`: a trailing BLANK label reservation is
* filtered out of every lane, so counting it as last would leave NO
* rendered part with the last-part cursor until the label fills. */
- const lastContentIdx = lastVisibleContentIdx(content);
+ const relativeLastContentIdx = lastVisibleContentIdx(content);
+ const lastContentIdx =
+ relativeLastContentIdx < 0 ? -1 : relativeLastContentIdx + contentIndexOffset;
// Split sequential parts into before/after parallel sections
const { before, after } = useMemo(() => {
@@ -272,8 +281,10 @@ export const ParallelContentRenderer = memo(function ParallelContentRenderer({
return (
<SearchContext.Provider value={{ searchResults }}>
- <MemoryArtifacts attachments={attachments} />
- <Sources messageId={messageId} conversationId={conversationId || undefined} />
+ {showDecorations && <MemoryArtifacts attachments={attachments} />}
+ {showDecorations && (
+ <Sources messageId={messageId} conversationId={conversationId || undefined} />
+ )}
{/* Sequential content BEFORE parallel sections */}
{before.flatMap(({ part, idx }) => {
diff --git a/client/src/components/Chat/Messages/Content/Part.tsx b/client/src/components/Chat/Messages/Content/Part.tsx
index 076dfbc1cd..082bad9bc4 100644
--- a/client/src/components/Chat/Messages/Content/Part.tsx
+++ b/client/src/components/Chat/Messages/Content/Part.tsx
@@ -67,6 +67,7 @@ const Part = memo(function Part({
if (askUserQuestion) {
return (
<AskUserQuestion
+ key={askUserQuestion.ask_user_question.actionId}
actionId={askUserQuestion.ask_user_question.actionId}
question={askUserQuestion.ask_user_question.question}
/>
diff --git a/client/src/components/Chat/Messages/Content/ToolApproval.tsx b/client/src/components/Chat/Messages/Content/ToolApproval.tsx
index 31ee82f654..3e5a43d25f 100644
--- a/client/src/components/Chat/Messages/Content/ToolApproval.tsx
+++ b/client/src/components/Chat/Messages/Content/ToolApproval.tsx
@@ -73,6 +73,7 @@ export default function ToolApproval({
registerToolCall,
unregisterToolCall,
setDecision,
+ getDecision,
isReady,
getStatus,
getLeadToolCallId,
@@ -80,10 +81,25 @@ export default function ToolApproval({
} = useApprovalContext();
const { submitToolApproval } = useResumeSubmit();
- const [active, setActive] = useState<DecisionType | null>(null);
- const [editText, setEditText] = useState(() => seedArgs(args));
- const [responseText, setResponseText] = useState('');
- const [reason, setReason] = useState('');
+ const retainedDecision = getDecision(actionId, toolCallId);
+ const initialDecision =
+ retainedDecision != null && allowedDecisions.includes(retainedDecision.decision)
+ ? retainedDecision
+ : undefined;
+ const [active, setActive] = useState<DecisionType | null>(
+ () => initialDecision?.decision ?? null,
+ );
+ const [editText, setEditText] = useState(() =>
+ initialDecision?.decision === 'edit'
+ ? (JSON.stringify(initialDecision.editedArguments, null, 2) ?? '{}')
+ : seedArgs(args),
+ );
+ const [responseText, setResponseText] = useState(() =>
+ initialDecision?.decision === 'respond' ? (initialDecision.responseText ?? '') : '',
+ );
+ const [reason, setReason] = useState(() =>
+ initialDecision?.decision === 'reject' ? (initialDecision.reason ?? '') : '',
+ );
useEffect(() => {
registerToolCall(actionId, toolCallId);
diff --git a/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx b/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx
index d206702060..d70a10e0bc 100644
--- a/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx
+++ b/client/src/components/Chat/Messages/Content/ToolCallGroup.tsx
@@ -10,8 +10,8 @@ import type {
FunctionToolCall,
} from 'librechat-data-provider';
import type { PartWithIndex } from './ParallelContent';
+import { cn, getToolDisplayLabel, getBatchActivityLabelPart, getActivityLabelText } from '~/utils';
import { useLocalize, useExpandCollapse, scheduleMessageContentLayoutReconcile } from '~/hooks';
-import { cn, getToolDisplayLabel, getActivityLabelPart, getActivityLabelText } from '~/utils';
import { useMCPIconMap, useMCPServerNames } from '~/hooks/MCP';
import { isBashProgrammaticToolCall } from './routing';
import { ASK_USER_QUESTION } from '~/utils/approval';
@@ -152,7 +152,7 @@ export default function ToolCallGroup({
() => parts.some(({ part }) => hasPendingApprovalInPart(part)),
[parts],
);
- const activityLabel = getActivityLabelPart(labelPart?.part);
+ const activityLabel = getBatchActivityLabelPart(labelPart?.part);
const activityLabelText = getActivityLabelText(activityLabel);
const activityFailed = activityLabel?.status === 'failed' || activityLabel?.status === 'partial';
/** A settled, filled label is itself a completion proof: the PostToolBatch
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ActivityPhaseGroup.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ActivityPhaseGroup.test.tsx
new file mode 100644
index 0000000000..897b42eff0
--- /dev/null
+++ b/client/src/components/Chat/Messages/Content/__tests__/ActivityPhaseGroup.test.tsx
@@ -0,0 +1,24 @@
+import { render } from '@testing-library/react';
+import { ContentTypes } from 'librechat-data-provider';
+import type { TMessageContentParts } from 'librechat-data-provider';
+import ActivityPhaseGroup from '../ActivityPhaseGroup';
+
+const labelPart = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: 'Compared both release paths',
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ pending: false,
+} as unknown as Extract<TMessageContentParts, { type: ContentTypes.ACTIVITY_LABEL }>;
+
+describe('ActivityPhaseGroup', () => {
+ test('renders a streaming cursor after an active tail phase', () => {
+ const { container } = render(
+ <ActivityPhaseGroup labelPart={labelPart} hasContent showCursor>
+ <div data-testid="phase-content" />
+ </ActivityPhaseGroup>,
+ );
+
+ expect(container.querySelector('.result-thinking')).toBeInTheDocument();
+ });
+});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ApprovalContext.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ApprovalContext.test.tsx
index 78477b3b72..fae45878a2 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ApprovalContext.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ApprovalContext.test.tsx
@@ -95,6 +95,24 @@ describe('useResumeSubmit', () => {
expect(mockApprovalMutate).toHaveBeenCalledTimes(2);
});
+ test('retains a decision across a transient card unregister and re-register', () => {
+ const { result } = renderHook(() => useApprovalContext(), { wrapper });
+ const decision = { tool_call_id: 'call-1', decision: 'approve' } as const;
+
+ act(() => {
+ result.current.registerToolCall('action-1', 'call-1');
+ result.current.setDecision('action-1', 'call-1', decision);
+ });
+ act(() => result.current.unregisterToolCall('action-1', 'call-1'));
+
+ expect(result.current.getDecisions('action-1')).toEqual([]);
+ expect(result.current.getDecision('action-1', 'call-1')).toEqual(decision);
+
+ act(() => result.current.registerToolCall('action-1', 'call-1'));
+ expect(result.current.getDecisions('action-1')).toEqual([decision]);
+ expect(result.current.isReady('action-1')).toBe(true);
+ });
+
test('keeps approval and ask-answer resume controls inert before the generation epoch exists', () => {
const { result } = renderHook(
() => ({
diff --git a/client/src/components/Chat/Messages/Content/__tests__/AskUserQuestion.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/AskUserQuestion.test.tsx
new file mode 100644
index 0000000000..6601684dd4
--- /dev/null
+++ b/client/src/components/Chat/Messages/Content/__tests__/AskUserQuestion.test.tsx
@@ -0,0 +1,64 @@
+import React from 'react';
+import { RecoilRoot } from 'recoil';
+import { fireEvent, render, screen } from '@testing-library/react';
+import ApprovalProvider from '../ApprovalContext';
+import AskUserQuestion from '../AskUserQuestion';
+
+jest.mock('~/hooks', () => ({
+ useLocalize: () => (key: string) => {
+ const labels: Record<string, string> = {
+ com_ui_your_answer: 'Your answer',
+ com_ui_submit: 'Submit',
+ com_ui_submitting: 'Submitting',
+ };
+ return labels[key] ?? key;
+ },
+}));
+
+jest.mock('~/hooks/Input/useAskAnswerMode', () => ({
+ __esModule: true,
+ default: () => ({
+ popoverVisible: false,
+ collapsed: false,
+ expand: jest.fn(),
+ liveAsk: null,
+ checked: [],
+ toggleChecked: jest.fn(),
+ submitOption: jest.fn(),
+ submitAnswer: jest.fn(),
+ }),
+}));
+
+jest.mock('~/data-provider', () => ({
+ useSubmitToolApprovalMutation: () => ({ mutate: jest.fn() }),
+ useSubmitAskAnswerMutation: () => ({ mutate: jest.fn() }),
+}));
+
+jest.mock('~/store/agents', () => ({
+ useGetEphemeralAgent: () => () => undefined,
+}));
+
+jest.mock('~/Providers/ChatContext', () => ({
+ ChatContext: jest.requireActual('react').createContext(null),
+}));
+
+const tree = (key: string) => (
+ <RecoilRoot>
+ <ApprovalProvider>
+ <AskUserQuestion key={key} actionId="ask-1" question={{ question: 'Which environment?' }} />
+ </ApprovalProvider>
+ </RecoilRoot>
+);
+
+describe('AskUserQuestion', () => {
+ test('restores a typed answer after the card remounts inside the same message', () => {
+ const view = render(tree('direct'));
+ fireEvent.change(screen.getByRole('textbox', { name: 'Your answer' }), {
+ target: { value: 'Use staging first' },
+ });
+
+ view.rerender(tree('phase-slice'));
+
+ expect(screen.getByRole('textbox', { name: 'Your answer' })).toHaveValue('Use staging first');
+ });
+});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx
index 63d29a47bb..61f5b2cdb8 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ContentParts.test.tsx
@@ -1,23 +1,33 @@
import React from 'react';
import { ContentTypes } from 'librechat-data-provider';
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
import type { TMessageContentParts } from 'librechat-data-provider';
+import { groupSequentialToolCalls } from '~/utils';
jest.mock('~/utils', () => ({
+ cn: (...classes: Array<string | false | null | undefined>) => classes.filter(Boolean).join(' '),
mapAttachments: () => ({}),
filterAttachmentsForPart: (attachments: unknown) => attachments,
- groupSequentialToolCalls: (parts: Array<{ part: unknown; idx: number }>) =>
- parts.map((p) => ({ type: 'single' as const, part: p })),
+ groupSequentialToolCalls: jest.fn(),
}));
-jest.mock('~/Providers', () => ({
- MessageContext: {
- Provider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
- },
- SearchContext: {
- Provider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
- },
-}));
+jest.mock('~/Providers', () => {
+ const react = jest.requireActual<typeof import('react')>('react');
+ return {
+ MessageContext: {
+ Provider: ({
+ children,
+ value,
+ }: {
+ children: React.ReactElement<{ idx?: number }>;
+ value: { partIndex: number };
+ }) => react.cloneElement(children, { idx: value.partIndex }),
+ },
+ SearchContext: {
+ Provider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+ },
+ };
+});
jest.mock('../Parts', () => ({
EditTextPart: () => <div data-testid="edit-text-part" />,
@@ -41,7 +51,30 @@ jest.mock('../Parts/PendingSkillCall', () => ({
jest.mock('../ToolCallGroup', () => ({
__esModule: true,
- default: () => <div data-testid="tool-call-group" />,
+ default: ({
+ initialExpansionState,
+ onExpansionChange,
+ }: {
+ initialExpansionState?: { isExpanded: boolean; userOverride: boolean };
+ onExpansionChange?: (state: { isExpanded: boolean; userOverride: boolean }) => void;
+ }) => (
+ <button
+ data-testid="tool-call-group"
+ data-initial-expanded={
+ initialExpansionState == null ? 'unset' : String(initialExpansionState.isExpanded)
+ }
+ onClick={() => onExpansionChange?.({ isExpanded: false, userOverride: true })}
+ />
+ ),
+}));
+
+jest.mock('../ActivityPhaseGroup', () => ({
+ __esModule: true,
+ default: ({ children, showCursor }: { children: React.ReactNode; showCursor?: boolean }) => (
+ <div data-testid="activity-phase-group" data-show-cursor={String(showCursor === true)}>
+ {children}
+ </div>
+ ),
}));
jest.mock('../Container', () => ({
@@ -53,8 +86,8 @@ jest.mock('../Container', () => ({
jest.mock('../Part', () => ({
__esModule: true,
- default: ({ part }: { part: TMessageContentParts }) => (
- <div data-testid={`real-part-${part.type}`} />
+ default: ({ part, idx }: { part: TMessageContentParts; idx: number }) => (
+ <div data-testid={`real-part-${part.type}`} data-index={idx} />
),
}));
@@ -63,13 +96,15 @@ jest.mock('../ParallelContent', () => ({
* renderer does for its sequential stretches, so the wiring is testable. */
ParallelContentRenderer: ({
content,
+ contentIndexOffset = 0,
renderResumeAttribution,
}: {
content?: Array<TMessageContentParts | undefined>;
+ contentIndexOffset?: number;
renderResumeAttribution?: (idx: number) => React.ReactNode;
}) => (
- <div data-testid="parallel-renderer">
- {content?.map((_, idx) => renderResumeAttribution?.(idx))}
+ <div data-testid="parallel-renderer" data-index-offset={contentIndexOffset}>
+ {content?.map((_, idx) => renderResumeAttribution?.(idx + contentIndexOffset))}
</div>
),
}));
@@ -85,6 +120,12 @@ const baseProps = {
content: [],
};
+beforeEach(() => {
+ jest
+ .mocked(groupSequentialToolCalls)
+ .mockImplementation((parts) => parts.map((part) => ({ type: 'single', part })));
+});
+
describe('ContentParts — interim skill cards', () => {
it('renders a PendingSkillCall per manual skill on assistant messages', () => {
render(<ContentParts {...baseProps} manualSkills={['brand-guidelines', 'pptx']} />);
@@ -258,4 +299,129 @@ describe('ContentParts — post-steer author re-attribution', () => {
expect(screen.getAllByTestId('author-header')).toHaveLength(1);
expect(screen.queryByTestId('post-steer-agent-update')).toBeNull();
});
+
+ it('retains steer attribution when resumed content moves into a phase slice', () => {
+ const phase = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: 'Reconciled both release paths',
+ activity_label_type: 'phase',
+ activity_start_index: 2,
+ activity_count: 2,
+ pending: false,
+ } as unknown as TMessageContentParts;
+ render(
+ <ContentParts
+ {...baseProps}
+ content={[textPart('a'), steerPart, textPart('resumed'), phase]}
+ authorHeader={header}
+ />,
+ );
+
+ expect(screen.getByTestId('activity-phase-group')).toBeTruthy();
+ expect(screen.getAllByTestId('author-header')).toHaveLength(1);
+ expect(screen.getAllByTestId(`real-part-${ContentTypes.TEXT}`)[1]).toHaveAttribute(
+ 'data-index',
+ '2',
+ );
+ });
+});
+
+describe('ContentParts — activity phase state', () => {
+ it('keeps a streaming cursor when a completed phase marker is the visible tail', () => {
+ const phase = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: 'Compared both search results',
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ pending: false,
+ } as unknown as TMessageContentParts;
+
+ render(
+ <ContentParts
+ {...baseProps}
+ content={[
+ { type: ContentTypes.TEXT, text: 'working' } as unknown as TMessageContentParts,
+ phase,
+ ]}
+ isLast
+ isSubmitting
+ isLatestMessage
+ />,
+ );
+
+ expect(screen.getByTestId('activity-phase-group')).toHaveAttribute('data-show-cursor', 'true');
+ });
+
+ it('carries the absolute index offset into a parallel phase segment', () => {
+ const phase = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: 'Compared both agent results',
+ activity_label_type: 'phase',
+ activity_start_index: 1,
+ activity_count: 2,
+ pending: false,
+ } as unknown as TMessageContentParts;
+ const parallel = {
+ type: ContentTypes.TEXT,
+ text: 'lane result',
+ groupId: 1,
+ } as unknown as TMessageContentParts;
+
+ render(
+ <ContentParts
+ {...baseProps}
+ content={[
+ { type: ContentTypes.TEXT, text: 'before' } as unknown as TMessageContentParts,
+ parallel,
+ phase,
+ ]}
+ />,
+ );
+
+ expect(screen.getByTestId('parallel-renderer')).toHaveAttribute('data-index-offset', '1');
+ });
+
+ it('retains a tool-group expansion override when a completed phase remounts the group', () => {
+ jest.mocked(groupSequentialToolCalls).mockImplementation((parts) => {
+ const toolParts = parts.filter(({ part }) => part.type === ContentTypes.TOOL_CALL);
+ if (toolParts.length > 0) {
+ return [{ type: 'tool-group', parts: toolParts }];
+ }
+ return parts.map((part) => ({ type: 'single', part }));
+ });
+ const tools = [
+ {
+ type: ContentTypes.TOOL_CALL,
+ [ContentTypes.TOOL_CALL]: { id: 'tool-1', name: 'search', args: {}, output: 'one' },
+ },
+ {
+ type: ContentTypes.TOOL_CALL,
+ [ContentTypes.TOOL_CALL]: { id: 'tool-2', name: 'search', args: {}, output: 'two' },
+ },
+ ] as unknown as TMessageContentParts[];
+ const pendingPhase = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: '',
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ pending: true,
+ } as unknown as TMessageContentParts;
+ const { rerender } = render(<ContentParts {...baseProps} content={[...tools, pendingPhase]} />);
+
+ const pendingGroup = screen.getByTestId('tool-call-group');
+ expect(pendingGroup).toHaveAttribute('data-initial-expanded', 'unset');
+ fireEvent.click(pendingGroup);
+
+ const completedPhase = {
+ ...pendingPhase,
+ [ContentTypes.ACTIVITY_LABEL]: 'Compared both search results',
+ pending: false,
+ } as unknown as TMessageContentParts;
+ rerender(<ContentParts {...baseProps} content={[...tools, completedPhase]} />);
+
+ expect(screen.getByTestId('activity-phase-group')).toBeInTheDocument();
+ expect(screen.getByTestId('tool-call-group')).toHaveAttribute('data-initial-expanded', 'false');
+ });
});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ParallelContent.test.ts b/client/src/components/Chat/Messages/Content/__tests__/ParallelContent.test.ts
new file mode 100644
index 0000000000..2bcff82a2f
--- /dev/null
+++ b/client/src/components/Chat/Messages/Content/__tests__/ParallelContent.test.ts
@@ -0,0 +1,23 @@
+import { ContentTypes } from 'librechat-data-provider';
+import type { TMessageContentParts } from 'librechat-data-provider';
+import { groupParallelContent } from '../ParallelContent';
+
+describe('groupParallelContent', () => {
+ test('reports absolute indices for a dense phase segment', () => {
+ const sequential = {
+ type: ContentTypes.TEXT,
+ text: 'before lanes',
+ } as unknown as TMessageContentParts;
+ const parallel = {
+ type: ContentTypes.TEXT,
+ text: 'lane result',
+ groupId: 1,
+ agentId: 'agent-1',
+ } as unknown as TMessageContentParts;
+
+ const grouped = groupParallelContent([sequential, parallel], 4);
+
+ expect(grouped.sequentialParts).toEqual([{ part: sequential, idx: 4 }]);
+ expect(grouped.parallelSections[0]?.columns[0]?.parts).toEqual([{ part: parallel, idx: 5 }]);
+ });
+});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx
index 0b5a2afcdf..94905f7f49 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ToolApproval.test.tsx
@@ -102,4 +102,22 @@ describe('ToolApproval', () => {
fireEvent.click(approveSecond);
expect(submit).toBeEnabled();
});
+
+ test('restores a selected decision when the card remounts inside the same message', () => {
+ const tree = (key: string) => (
+ <RecoilRoot>
+ <ApprovalProvider>
+ <ToolApproval key={key} approval={approval()} toolCallId="call-1" args={{ a: 1 }} />
+ </ApprovalProvider>
+ </RecoilRoot>
+ );
+ const view = render(tree('direct'));
+ fireEvent.click(screen.getByRole('button', { name: 'Approve' }));
+ expect(screen.getByRole('button', { name: 'Approve' })).toHaveAttribute('aria-pressed', 'true');
+
+ view.rerender(tree('phase-slice'));
+
+ expect(screen.getByRole('button', { name: 'Approve' })).toHaveAttribute('aria-pressed', 'true');
+ expect(screen.getByRole('button', { name: 'Submit' })).toBeEnabled();
+ });
});
diff --git a/client/src/components/Chat/Messages/Content/__tests__/ToolCallGroup.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/ToolCallGroup.test.tsx
index 38129e3428..0426219539 100644
--- a/client/src/components/Chat/Messages/Content/__tests__/ToolCallGroup.test.tsx
+++ b/client/src/components/Chat/Messages/Content/__tests__/ToolCallGroup.test.tsx
@@ -65,7 +65,7 @@ jest.mock('~/utils', () => ({
: name,
/** Real implementations: the group header resolves its text through these,
* so stubbing them out would hide the header logic under test. */
- getActivityLabelPart: jest.requireActual('~/utils/activityLabels').getActivityLabelPart,
+ getBatchActivityLabelPart: jest.requireActual('~/utils/activityLabels').getBatchActivityLabelPart,
getActivityLabelText: jest.requireActual('~/utils/activityLabels').getActivityLabelText,
}));
diff --git a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
index 170a0953ad..5f0ae63520 100644
--- a/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
+++ b/client/src/hooks/SSE/__tests__/useStepHandler.spec.ts
@@ -3357,6 +3357,110 @@ describe('useStepHandler', () => {
expect(response?.content?.[0]).toMatchObject({ [ContentTypes.TEXT]: 'kept a' });
});
+ it('does not merge final-answer text into a retained commentary phase', () => {
+ const commentary = {
+ type: ContentTypes.TEXT,
+ [ContentTypes.TEXT]: 'Checked the current deployment. ',
+ phase: 'commentary',
+ } as TMessageContentParts;
+ const submission = createSubmission({
+ editedContent: { index: 0, type: ContentTypes.TEXT },
+ initialResponse: createResponseMessage({ content: [textPart('kept'), commentary] }),
+ } as never);
+ (submission as { editPrefixLength?: number }).editPrefixLength = 2;
+ const responseMessage = submission.initialResponse as TMessage;
+ let currentMessages: TMessage[] = [responseMessage];
+ mockGetMessages.mockImplementation(() => currentMessages);
+ mockSetMessages.mockImplementation((messages: TMessage[]) => {
+ currentMessages = messages;
+ });
+
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP,
+ data: createRunStep({
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'msg-1', phase: 'final_answer' },
+ },
+ }),
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ { event: StepEvents.ON_MESSAGE_DELTA, data: createMessageDelta('step-1', 'Done') },
+ submission,
+ );
+ });
+
+ const response = currentMessages.find((message) => !message.isCreatedByUser);
+ expect(response?.content?.[1]).toMatchObject({
+ [ContentTypes.TEXT]: 'Checked the current deployment. ',
+ phase: 'commentary',
+ });
+ expect(response?.content?.[2]).toMatchObject({
+ [ContentTypes.TEXT]: 'Done',
+ phase: 'final_answer',
+ });
+ });
+
+ it.each([
+ [undefined, 'commentary'],
+ ['commentary', undefined],
+ ] as const)(
+ 'does not merge phased and unphased text (%s → %s)',
+ (retainedPhase, incomingPhase) => {
+ const retained = {
+ type: ContentTypes.TEXT,
+ [ContentTypes.TEXT]: 'Retained text. ',
+ ...(retainedPhase != null && { phase: retainedPhase }),
+ } as TMessageContentParts;
+ const submission = createSubmission({
+ editedContent: { index: 0, type: ContentTypes.TEXT },
+ initialResponse: createResponseMessage({ content: [textPart('kept'), retained] }),
+ } as never);
+ (submission as { editPrefixLength?: number }).editPrefixLength = 2;
+ const responseMessage = submission.initialResponse as TMessage;
+ let currentMessages: TMessage[] = [responseMessage];
+ mockGetMessages.mockImplementation(() => currentMessages);
+ mockSetMessages.mockImplementation((messages: TMessage[]) => {
+ currentMessages = messages;
+ });
+
+ const { result } = renderHook(() => useStepHandler(createHookParams()));
+ act(() => {
+ result.current.stepHandler(
+ {
+ event: StepEvents.ON_RUN_STEP,
+ data: createRunStep({
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: {
+ message_id: 'msg-1',
+ ...(incomingPhase != null && { phase: incomingPhase }),
+ },
+ },
+ }),
+ },
+ submission,
+ );
+ result.current.stepHandler(
+ { event: StepEvents.ON_MESSAGE_DELTA, data: createMessageDelta('step-1', 'New text') },
+ submission,
+ );
+ });
+
+ const response = currentMessages.find((message) => !message.isCreatedByUser);
+ expect(response?.content?.[1]).toMatchObject(retained);
+ expect(response?.content?.[2]).toMatchObject({
+ [ContentTypes.TEXT]: 'New text',
+ ...(incomingPhase != null && { phase: incomingPhase }),
+ });
+ },
+ );
+
/**
* Post-sync a delta continues at the snapshot's NEXT absolute slot. With
* the offset still applied it would jump past that slot and leave a hole
diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.ts
index 6f29a92599..13634ea004 100644
--- a/client/src/hooks/SSE/useResumableSSE.ts
+++ b/client/src/hooks/SSE/useResumableSSE.ts
@@ -1353,8 +1353,45 @@ export default function useResumableSSE(
(currentSubmission.initialResponse as TMessage | undefined)?.content?.length ??
0)
: 0;
- const offsetEvent =
- prefixLength > 0 ? { ...event, index: event.index + prefixLength } : event;
+ const phasePart = event.part as TActivityLabelEvent['part'] & {
+ activity_label_type?: 'phase';
+ activity_start_index?: number;
+ };
+ let offsetEvent = event;
+ if (prefixLength > 0) {
+ let offsetPart: TActivityLabelEvent['part'] & {
+ activity_label_type?: 'phase';
+ activity_start_index?: number;
+ } = phasePart;
+ if (
+ phasePart.activity_label_type === 'phase' &&
+ typeof phasePart.activity_start_index === 'number'
+ ) {
+ let activityStartIndex = phasePart.activity_start_index + prefixLength;
+ const targetContent = messages[index]?.content;
+ /** The first completion text/think part can merge into the
+ * retained edit tail at prefixLength - 1. Tool/nonmatching starts
+ * occupy the ordinary +prefix slot, so only fold back across the
+ * recognizable empty merge slot. */
+ if (
+ phasePart.activity_start_index === 0 &&
+ activityStartIndex > 0 &&
+ targetContent?.[activityStartIndex] == null &&
+ targetContent?.[activityStartIndex - 1] != null
+ ) {
+ activityStartIndex -= 1;
+ }
+ offsetPart = {
+ ...phasePart,
+ activity_start_index: activityStartIndex,
+ };
+ }
+ offsetEvent = {
+ ...event,
+ index: event.index + prefixLength,
+ part: offsetPart,
+ };
+ }
const updated = applyActivityLabelPart(messages[index], offsetEvent);
if (updated !== messages[index]) {
const nextMessages = [...messages];
diff --git a/client/src/hooks/SSE/useStepHandler.ts b/client/src/hooks/SSE/useStepHandler.ts
index fe3e9f0948..e3d49790e7 100644
--- a/client/src/hooks/SSE/useStepHandler.ts
+++ b/client/src/hooks/SSE/useStepHandler.ts
@@ -59,7 +59,12 @@ type TStepEvent =
| { event: StepEvents.ON_SUBAGENT_UPDATE; data: SubagentUpdateEvent }
| { event: StepEvents.ON_SANDBOX_STARTING; data: SandboxStartingEvent };
-type MessageDeltaUpdate = { type: ContentTypes.TEXT; text: string; tool_call_ids?: string[] };
+type MessageDeltaUpdate = {
+ type: ContentTypes.TEXT;
+ text: string;
+ tool_call_ids?: string[];
+ phase?: 'commentary' | 'final_answer';
+};
type ReasoningDeltaUpdate = { type: ContentTypes.THINK; think: string };
@@ -343,6 +348,7 @@ export default function useStepHandler({
editPrefixOffset: number,
incomingContentType: string,
existingContent?: TMessageContentParts[],
+ incomingPhase?: 'commentary' | 'final_answer',
): number => {
/** Only apply -1 adjustment for TEXT or THINK types when they match existing content */
if (
@@ -350,8 +356,16 @@ export default function useStepHandler({
(incomingContentType === ContentTypes.TEXT || incomingContentType === ContentTypes.THINK)
) {
const targetIndex = serverIndex + editPrefixOffset - 1;
- const existingType = existingContent?.[targetIndex]?.type;
- if (existingType === incomingContentType) {
+ const existingPart = existingContent?.[targetIndex];
+ const existingType = existingPart?.type;
+ const existingPhase =
+ existingPart?.type === ContentTypes.TEXT ? existingPart.phase : undefined;
+ /** Match final assembly: phased and legacy/unphased text cannot share
+ * a content part because the phase controls client grouping. */
+ const phaseCompatible =
+ incomingContentType !== ContentTypes.TEXT ||
+ (incomingPhase ?? null) === (existingPhase ?? null);
+ if (existingType === incomingContentType && phaseCompatible) {
return targetIndex;
}
}
@@ -435,9 +449,12 @@ export default function useStepHandler({
typeof contentPart.text === 'string'
) {
const currentContent = updatedContent[index] as MessageDeltaUpdate;
+ const incomingContent = contentPart as MessageDeltaUpdate;
+ const phase = incomingContent.phase ?? currentContent.phase;
const update: MessageDeltaUpdate = {
type: ContentTypes.TEXT,
- text: (currentContent.text || '') + contentPart.text,
+ text: (currentContent.text || '') + incomingContent.text,
+ ...(phase != null && { phase }),
};
if ('tool_call_ids' in contentPart && contentPart.tool_call_ids != null) {
@@ -944,16 +961,29 @@ export default function useStepHandler({
if (contentPart == null) {
continue;
}
+ const messageCreation =
+ runStep.stepDetails.type === StepTypes.MESSAGE_CREATION
+ ? (runStep.stepDetails.message_creation as {
+ phase?: 'commentary' | 'final_answer';
+ })
+ : undefined;
+ const phase = messageCreation?.phase;
+ const phasedContentPart =
+ contentPart.type === ContentTypes.TEXT &&
+ (phase === 'commentary' || phase === 'final_answer')
+ ? { ...contentPart, phase }
+ : contentPart;
const currentIndex = calculateContentIndex(
runStep.index,
editPrefixOffset,
- contentPart.type || '',
+ phasedContentPart.type || '',
updatedResponse.content,
+ phase,
);
updatedResponse = updateContent(
updatedResponse,
currentIndex,
- contentPart,
+ phasedContentPart,
false,
getStepMetadata(runStep),
);
diff --git a/client/src/utils/__tests__/activityLabels.spec.ts b/client/src/utils/__tests__/activityLabels.spec.ts
index 5adda8aa93..37545d7af1 100644
--- a/client/src/utils/__tests__/activityLabels.spec.ts
+++ b/client/src/utils/__tests__/activityLabels.spec.ts
@@ -1,6 +1,10 @@
import { ContentTypes } from 'librechat-data-provider';
import type { TActivityLabelEvent, TMessage, TMessageContentParts } from 'librechat-data-provider';
-import { applyActivityLabelPart, lastVisibleContentIdx } from '../activityLabels';
+import {
+ applyActivityLabelPart,
+ groupActivityPhases,
+ lastVisibleContentIdx,
+} from '../activityLabels';
const buildMessage = (content: TMessage['content']): TMessage =>
({ messageId: 'm1', isCreatedByUser: false, content }) as TMessage;
@@ -32,6 +36,25 @@ describe('applyActivityLabelPart', () => {
expect(updated).toBe(message);
});
+ it('applies a bounds-only update to a completed phase', () => {
+ const existing = labelPart({ activity_label: 'Fixed the session', pending: false });
+ Object.assign(existing, {
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ });
+ const incoming = { ...existing, activity_start_index: 1 };
+ const message = buildMessage([existing as never]);
+
+ const updated = applyActivityLabelPart(message, { index: 0, part: incoming });
+
+ expect(updated).not.toBe(message);
+ expect((updated.content as unknown[])[0]).toMatchObject({
+ activity_start_index: 1,
+ activity_count: 2,
+ });
+ });
+
it('never lets a stale pending placeholder overwrite a resolved label', () => {
const resolved = labelPart({
activity_label: 'Searched runtime release notes',
@@ -75,4 +98,57 @@ describe('lastVisibleContentIdx', () => {
expect(lastVisibleContentIdx([])).toBe(-1);
expect(lastVisibleContentIdx(undefined)).toBe(-1);
});
+
+ it('skips large sparse trailing gaps', () => {
+ expect(lastVisibleContentIdx([undefined, tool, undefined, undefined])).toBe(1);
+ const sparse = new Array<TMessageContentParts | undefined>(10_000);
+ sparse[1] = tool;
+ expect(lastVisibleContentIdx(sparse)).toBe(1);
+ });
+});
+
+describe('groupActivityPhases', () => {
+ const text = { type: ContentTypes.TEXT, text: 'final answer' } as TMessageContentParts;
+ const tool = {
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 't1', name: 'web_search', args: '{}', output: 'ok' },
+ } as unknown as TMessageContentParts;
+
+ it('carries absolute offsets while consuming a completed parent marker', () => {
+ const phase = labelPart({ activity_label: 'Compared both release paths', pending: false });
+ Object.assign(phase, {
+ activity_label_type: 'phase',
+ activity_start_index: 1,
+ activity_count: 2,
+ });
+ const segments = groupActivityPhases([text, tool, tool, phase as never, text]);
+ expect(segments).toHaveLength(3);
+ expect(segments?.[1]).toMatchObject({ type: 'phase', labelIndex: 3, startIndex: 1 });
+ if (segments?.[1]?.type === 'phase') {
+ expect(segments[1].content).toEqual([tool, tool]);
+ }
+ });
+
+ it('leaves pending or empty parent markers on the feature-off path', () => {
+ const pending = labelPart();
+ Object.assign(pending, { activity_label_type: 'phase', activity_start_index: 0 });
+ expect(groupActivityPhases([tool, pending as never])).toBeUndefined();
+ });
+
+ it('preserves a completed summary when every phase child was filtered out', () => {
+ const phase = labelPart({ activity_label: 'Reconciled both release paths', pending: false });
+ Object.assign(phase, {
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ });
+
+ expect(groupActivityPhases([labelPart() as never, phase as never])).toEqual([
+ expect.objectContaining({
+ type: 'phase',
+ labelIndex: 1,
+ hasContent: false,
+ }),
+ ]);
+ });
});
diff --git a/client/src/utils/__tests__/groupToolCalls.test.ts b/client/src/utils/__tests__/groupToolCalls.test.ts
index a785836849..2c02356600 100644
--- a/client/src/utils/__tests__/groupToolCalls.test.ts
+++ b/client/src/utils/__tests__/groupToolCalls.test.ts
@@ -12,6 +12,9 @@ const toolCall = (id: string): TMessageContentParts =>
const think = (text: string): TMessageContentParts =>
({ type: ContentTypes.THINK, [ContentTypes.THINK]: text }) as unknown as TMessageContentParts;
+const text = (value: string, phase?: 'commentary' | 'final_answer'): TMessageContentParts =>
+ ({ type: ContentTypes.TEXT, [ContentTypes.TEXT]: value, phase }) as TMessageContentParts;
+
const label = (text: string): TMessageContentParts =>
({
type: ContentTypes.ACTIVITY_LABEL,
@@ -72,6 +75,26 @@ describe('groupSequentialToolCalls with activity labels', () => {
});
});
+ it('nests typed commentary with its labeled tool batch, but never final text', () => {
+ const commentary = groupSequentialToolCalls(
+ withIndex([
+ text('I will compare both releases.', 'commentary'),
+ toolCall('t1'),
+ label('Compared both releases'),
+ ]),
+ );
+ expect(commentary).toHaveLength(1);
+ expect(commentary[0]).toMatchObject({ type: 'tool-group' });
+ expect((commentary[0] as { parts: PartWithIndex[] }).parts).toHaveLength(2);
+
+ const final = groupSequentialToolCalls(
+ withIndex([text('Here is the answer.', 'final_answer'), toolCall('t1'), label('Found it')]),
+ );
+ expect(final).toHaveLength(2);
+ expect(final[0]).toMatchObject({ type: 'single' });
+ expect(final[1]).toMatchObject({ type: 'tool-group' });
+ });
+
/** An empty orphan label has nothing to render and no block to delimit. */
it('drops an empty orphan label entirely', () => {
expect(groupSequentialToolCalls(withIndex([label('')]))).toEqual([]);
diff --git a/client/src/utils/activityLabels.ts b/client/src/utils/activityLabels.ts
index 5cf1eca87d..acb2e0cba8 100644
--- a/client/src/utils/activityLabels.ts
+++ b/client/src/utils/activityLabels.ts
@@ -1,7 +1,48 @@
import { ContentTypes } from 'librechat-data-provider';
import type { TMessage, TActivityLabelEvent, TMessageContentParts } from 'librechat-data-provider';
-type ActivityLabelPart = Extract<TMessageContentParts, { type: ContentTypes.ACTIVITY_LABEL }>;
+type ActivityLabelPart = Extract<TMessageContentParts, { type: ContentTypes.ACTIVITY_LABEL }> & {
+ activity_label_type?: 'phase';
+ activity_start_index?: number;
+ activity_count?: number;
+ agent_ids?: string[];
+};
+
+export type ActivityPhaseSegment =
+ | {
+ type: 'content';
+ content: Array<TMessageContentParts | undefined>;
+ startIndex: number;
+ }
+ | {
+ type: 'phase';
+ content: Array<TMessageContentParts | undefined>;
+ startIndex: number;
+ labelPart: ActivityLabelPart;
+ labelIndex: number;
+ hasContent: boolean;
+ };
+
+function isVisibleContentPart(part: TMessageContentParts | undefined): boolean {
+ return (
+ part != null &&
+ !(
+ part.type === ContentTypes.ACTIVITY_LABEL &&
+ getActivityLabelText(getActivityLabelPart(part)).length === 0
+ )
+ );
+}
+
+export function isPhaseActivityLabel(part: ActivityLabelPart | undefined): boolean {
+ return part?.activity_label_type === 'phase';
+}
+
+export function getBatchActivityLabelPart(
+ part: TMessageContentParts | undefined,
+): ActivityLabelPart | undefined {
+ const label = getActivityLabelPart(part);
+ return label != null && !isPhaseActivityLabel(label) ? label : undefined;
+}
/** Returns the activity-label content part when `part` is one, else undefined. */
export function getActivityLabelPart(
@@ -26,6 +67,78 @@ export function getActivityLabelText(part: ActivityLabelPart | undefined): strin
return typeof label === 'string' ? label.trim() : '';
}
+/**
+ * Partitions completed phase markers into collapsed parent groups while
+ * carrying absolute start offsets alongside dense content slices. Empty/pending
+ * markers deliberately return no phase segment, preserving feature-off UI.
+ */
+export function groupActivityPhases(
+ content: Array<TMessageContentParts | undefined> | undefined,
+): ActivityPhaseSegment[] | undefined {
+ if (!content) {
+ return undefined;
+ }
+ const completed = content
+ .map((part, index) => ({ part: getActivityLabelPart(part), index }))
+ .filter(
+ ({ part }) =>
+ isPhaseActivityLabel(part) &&
+ part?.pending !== true &&
+ getActivityLabelText(part).length > 0 &&
+ typeof part?.activity_start_index === 'number',
+ );
+ if (completed.length === 0) {
+ return undefined;
+ }
+
+ const segments: ActivityPhaseSegment[] = [];
+ let cursor = 0;
+ /** Dense, disjoint slices copy every part at most once. `startIndex` carries
+ * the absolute transcript position into the recursive renderer. */
+ const slice = (start: number, end: number) => {
+ const segmentContent = content.slice(start, end);
+ return {
+ content: segmentContent,
+ startIndex: start,
+ hasContent: segmentContent.some(isVisibleContentPart),
+ };
+ };
+ for (const { part, index } of completed) {
+ if (!part) continue;
+ const start = Math.max(
+ cursor,
+ Math.min(index, Math.max(0, part.activity_start_index ?? index)),
+ );
+ if (start > cursor) {
+ const adjacent = slice(cursor, start);
+ segments.push({
+ type: 'content',
+ content: adjacent.content,
+ startIndex: adjacent.startIndex,
+ });
+ }
+ const phase = slice(start, index);
+ segments.push({
+ type: 'phase',
+ content: phase.content,
+ startIndex: phase.startIndex,
+ labelPart: part,
+ labelIndex: index,
+ hasContent: phase.hasContent,
+ });
+ cursor = index + 1;
+ }
+ if (cursor < content.length) {
+ const adjacent = slice(cursor, content.length);
+ segments.push({
+ type: 'content',
+ content: adjacent.content,
+ startIndex: adjacent.startIndex,
+ });
+ }
+ return segments;
+}
+
/**
* Last content index that actually renders something. Trailing BLANK label
* reservations are invisible (every batch publishes one at batch end), so
@@ -39,18 +152,25 @@ export function lastVisibleContentIdx(
): number {
const parts = content ?? [];
let last = parts.length - 1;
- while (last > 0) {
- const tail = parts[last];
- if (
- tail?.type === ContentTypes.ACTIVITY_LABEL &&
- getActivityLabelText(getActivityLabelPart(tail)).length === 0
- ) {
- last -= 1;
- } else {
- break;
+ while (last >= 0 && last in parts) {
+ if (isVisibleContentPart(parts[last])) {
+ return last;
+ }
+ last -= 1;
+ }
+ if (last < 0) {
+ return -1;
+ }
+ /** Streaming/resume arrays can retain absolute indices as true holes. Jump
+ * between defined slots instead of walking the whole index space. */
+ const definedIndices = Object.keys(parts);
+ for (let i = definedIndices.length - 1; i >= 0; i -= 1) {
+ const index = Number(definedIndices[i]);
+ if (index <= last && isVisibleContentPart(parts[index])) {
+ return index;
}
}
- return last;
+ return -1;
}
/**
@@ -94,10 +214,14 @@ export function applyActivityLabelPart(message: TMessage, event: TActivityLabelE
}
const content = Array.isArray(message.content) ? message.content : [];
const existing = getActivityLabelPart(content[index] as TMessageContentParts | undefined);
+ const incoming = part as ActivityLabelPart;
if (
existing != null &&
existing[ContentTypes.ACTIVITY_LABEL] === part[ContentTypes.ACTIVITY_LABEL] &&
- existing.pending === part.pending
+ existing.pending === part.pending &&
+ existing.activity_label_type === incoming.activity_label_type &&
+ existing.activity_start_index === incoming.activity_start_index &&
+ existing.activity_count === incoming.activity_count
) {
return message;
}
diff --git a/client/src/utils/groupToolCalls.ts b/client/src/utils/groupToolCalls.ts
index 7f4b365731..2d6b72e087 100644
--- a/client/src/utils/groupToolCalls.ts
+++ b/client/src/utils/groupToolCalls.ts
@@ -1,7 +1,7 @@
import { Constants, ContentTypes, ToolCallTypes } from 'librechat-data-provider';
import type { TMessageContentParts, Agents } from 'librechat-data-provider';
import type { PartWithIndex } from '~/components/Chat/Messages/Content/ParallelContent';
-import { getActivityLabelPart, getActivityLabelText } from '~/utils/activityLabels';
+import { getBatchActivityLabelPart, getActivityLabelText } from '~/utils/activityLabels';
export type GroupedPart =
| { type: 'single'; part: PartWithIndex }
@@ -95,12 +95,21 @@ export function groupSequentialToolCalls(parts: PartWithIndex[]): GroupedPart[]
};
for (const item of parts) {
- if (isGroupableToolCall(item.part) || item.part.type === ContentTypes.THINK) {
+ const isCommentary =
+ item.part.type === ContentTypes.TEXT &&
+ (item.part as { phase?: string }).phase === 'commentary';
+ if (isGroupableToolCall(item.part) || item.part.type === ContentTypes.THINK || isCommentary) {
currentBlock.push(item);
continue;
}
if (item.part.type === ContentTypes.ACTIVITY_LABEL) {
- const hasText = getActivityLabelText(getActivityLabelPart(item.part)).length > 0;
+ const batchLabel = getBatchActivityLabelPart(item.part);
+ if (batchLabel == null) {
+ flushWithoutLabel();
+ result.push({ type: 'single', part: item });
+ continue;
+ }
+ const hasText = getActivityLabelText(batchLabel).length > 0;
if (!hasText) {
/** A reserved-but-unfilled slot (and a failed/blank fill) must be
* INVISIBLE. Every batch now publishes its reservation immediately,
diff --git a/librechat.example.yaml b/librechat.example.yaml
index 3d3f95eaa9..310cd8ae43 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -602,6 +602,13 @@ endpoints:
# activityPrompt: 'Write a 5-9 word past-tense label...'
# activityMaxPerRun: 20 # cost cap per response
# activityCharLimit: 600 # per-entry prompt truncation
+ # Parent phase summaries are an independent opt-in. They collapse 2+
+ # logical activities before the answer into one run-level summary.
+ # activityPhaseLabel: true
+ # activityPhaseModel: 'claude-3-5-haiku' # falls back to activity/title/run model
+ # activityPhaseEndpoint: 'anthropic' # falls back to activity/run endpoint
+ # activityPhasePrompt: 'Summarize the completed agent phase...'
+ # activityPhaseMaxPerRun: 5 # cost cap per response
modelDisplayLabel: 'Claude (Compatible)'
# Groq Example
diff --git a/package-lock.json b/package-lock.json
index 049c663eae..40fb5aa5ae 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -62,7 +62,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "^4.3.3",
- "@librechat/agents": "^3.4.3",
+ "@librechat/agents": "^3.4.4",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
@@ -10627,9 +10627,9 @@
}
},
"node_modules/@librechat/agents": {
- "version": "3.4.3",
- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.4.3.tgz",
- "integrity": "sha512-adFenD8ezDF4ZbKvzamw/eGzo9tpGLdM8Hom5G2ekvhEUlRSvneURJXCib7EJ45mCPDjxihhfDE7EQa2mOwMAg==",
+ "version": "3.4.4",
+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.4.4.tgz",
+ "integrity": "sha512-Sv1+my/28jqjV+Dz+RQjxM53itVVcQNOfI9hJ4puxpdjZpDYCPDQzUJT73d9yvI5IO1NoDYA8wULlIJJ5FCI9w==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "^0.115.0",
@@ -42721,7 +42721,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "^4.3.3",
- "@librechat/agents": "^3.4.3",
+ "@librechat/agents": "^3.4.4",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.29.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/package.json b/packages/api/package.json
index 63e8bb2a00..b77b2188d6 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -113,7 +113,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "^4.3.3",
- "@librechat/agents": "^3.4.3",
+ "@librechat/agents": "^3.4.4",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.29.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/src/agents/activityLabels/__tests__/host.spec.ts b/packages/api/src/agents/activityLabels/__tests__/host.spec.ts
index 5de40f7428..c41a09659f 100644
--- a/packages/api/src/agents/activityLabels/__tests__/host.spec.ts
+++ b/packages/api/src/agents/activityLabels/__tests__/host.spec.ts
@@ -3,6 +3,7 @@ import type { EndpointDbMethods, ServerRequest } from '~/types';
import {
mapCollectedMetadataToUsage,
resolveActivityConfig,
+ resolveActivityPhaseConfig,
resolveActivityLabelModel,
} from '../host';
@@ -123,6 +124,52 @@ describe('resolveActivityConfig', () => {
});
});
+describe('resolveActivityPhaseConfig', () => {
+ it('is independently opt-in and inherits activity model/endpoint tuning', () => {
+ const config = resolveActivityPhaseConfig(
+ appConfig({
+ openAI: {
+ activityLabel: true,
+ activityModel: 'batch-model',
+ activityEndpoint: 'anthropic',
+ },
+ }),
+ 'openAI',
+ );
+ expect(config).toMatchObject({
+ enabled: false,
+ model: 'batch-model',
+ endpoint: 'anthropic',
+ });
+ });
+
+ it('prefers dedicated phase settings and reuses activityCharLimit', () => {
+ const config = resolveActivityPhaseConfig(
+ appConfig({
+ openAI: {
+ activityPhaseLabel: true,
+ activityPhaseModel: 'phase-model',
+ activityModel: 'batch-model',
+ activityPhaseEndpoint: 'google',
+ activityEndpoint: 'anthropic',
+ activityPhasePrompt: 'phase prompt',
+ activityPhaseMaxPerRun: 3,
+ activityCharLimit: 240,
+ },
+ }),
+ 'openAI',
+ );
+ expect(config).toEqual({
+ enabled: true,
+ model: 'phase-model',
+ endpoint: 'google',
+ prompt: 'phase prompt',
+ maxPerRun: 3,
+ charLimit: 240,
+ });
+ });
+});
+
describe('resolveActivityLabelModel model precedence', () => {
const db = {} as EndpointDbMethods;
const resolve = (endpointConfig: Record<string, unknown>) =>
diff --git a/packages/api/src/agents/activityLabels/__tests__/wiring.spec.ts b/packages/api/src/agents/activityLabels/__tests__/wiring.spec.ts
index 8833e2fc30..d1abaf5406 100644
--- a/packages/api/src/agents/activityLabels/__tests__/wiring.spec.ts
+++ b/packages/api/src/agents/activityLabels/__tests__/wiring.spec.ts
@@ -179,6 +179,22 @@ describe('synthesizeActivityLabelGapEvents', () => {
];
expect(synthesizeActivityLabelGapEvents(parts, parts, meta)).toEqual([]);
});
+
+ it('re-emits a completed phase when its reconciled bounds changed', () => {
+ const snapshot: LooseContentPart[] = [
+ {
+ type: 'activity_label',
+ activity_label: 'Inspected and fixed the session',
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ pending: false,
+ },
+ ];
+ const fresh: LooseContentPart[] = [{ ...snapshot[0], activity_start_index: 1 }];
+
+ expect(synthesizeActivityLabelGapEvents(snapshot, fresh, meta)).toHaveLength(1);
+ });
});
describe('createActivityLabelWiring close gate', () => {
diff --git a/packages/api/src/agents/activityLabels/host.ts b/packages/api/src/agents/activityLabels/host.ts
index e4f937bfc7..2dae191f1d 100644
--- a/packages/api/src/agents/activityLabels/host.ts
+++ b/packages/api/src/agents/activityLabels/host.ts
@@ -11,6 +11,16 @@ import { resolveConfigHeaders } from '~/utils/headers';
import { omitTitleOptions } from '~/agents/client';
import { createSafeUser } from '~/utils/env';
+/** Additive phase fields may precede the rebuilt data-provider artifact in a
+ * package-local typecheck, so keep the endpoint view structural here. */
+type ActivityEndpoint = TEndpoint & {
+ activityPhaseLabel?: boolean;
+ activityPhaseModel?: string;
+ activityPhaseEndpoint?: string;
+ activityPhasePrompt?: string;
+ activityPhaseMaxPerRun?: number;
+};
+
/** Cache-token details in the LangChain-standard normalized shape. */
interface CacheTokenDetails {
cache_read?: number;
@@ -134,6 +144,16 @@ export interface ResolvedActivityConfig {
charLimit?: number;
}
+/** Effective parent activity-phase settings for one endpoint. */
+export interface ResolvedActivityPhaseConfig {
+ enabled: boolean;
+ model?: string;
+ endpoint?: string;
+ prompt?: string;
+ maxPerRun?: number;
+ charLimit?: number;
+}
+
/**
* Reads the per-endpoint `activity*` settings, mirroring how titles resolve
* theirs: an `endpoints.all` block wins over the named endpoint, which wins
@@ -149,17 +169,17 @@ export interface ResolvedActivityConfig {
* `titleModel` fallback. Global still wins per field, so a real
* `all.activityLabel` keeps overriding the endpoint.
*/
-function pickEndpointField<K extends keyof TEndpoint>(
+function pickEndpointField<K extends keyof ActivityEndpoint>(
appConfig: AppConfig | undefined,
endpoint: string,
- customEndpointConfig: Partial<TEndpoint> | undefined,
+ customEndpointConfig: Partial<ActivityEndpoint> | undefined,
key: K,
publicEndpoint?: string,
-): TEndpoint[K] | undefined {
+): ActivityEndpoint[K] | undefined {
const endpoints = appConfig?.endpoints as
- | (Record<string, TEndpoint | undefined> & { all?: TEndpoint })
+ | (Record<string, ActivityEndpoint | undefined> & { all?: ActivityEndpoint })
| undefined;
- const all = endpoints?.all as Partial<TEndpoint> | undefined;
+ const all = endpoints?.all as Partial<ActivityEndpoint> | undefined;
/** The PUBLIC endpoint the request came in on, when it differs from the
* backing provider. `initializeAgent` rewrites `agent.endpoint` to the
* provider (an agents-endpoint run backed by OpenAI reads `openAI`), so
@@ -169,9 +189,11 @@ function pickEndpointField<K extends keyof TEndpoint>(
* mirroring how request-path options resolve. */
const publicBlock =
publicEndpoint != null && publicEndpoint !== endpoint
- ? (endpoints?.[publicEndpoint] as Partial<TEndpoint> | undefined)
+ ? (endpoints?.[publicEndpoint] as Partial<ActivityEndpoint> | undefined)
: undefined;
- const named = (endpoints?.[endpoint] ?? customEndpointConfig) as Partial<TEndpoint> | undefined;
+ const named = (endpoints?.[endpoint] ?? customEndpointConfig) as
+ | Partial<ActivityEndpoint>
+ | undefined;
return all?.[key] ?? publicBlock?.[key] ?? named?.[key];
}
@@ -181,7 +203,7 @@ export function resolveActivityConfig(
customEndpointConfig?: Partial<TEndpoint>,
publicEndpoint?: string,
): ResolvedActivityConfig {
- const pick = <K extends keyof TEndpoint>(key: K): TEndpoint[K] | undefined =>
+ const pick = <K extends keyof ActivityEndpoint>(key: K): ActivityEndpoint[K] | undefined =>
pickEndpointField(appConfig, endpoint, customEndpointConfig, key, publicEndpoint);
return {
enabled: pick('activityLabel') === true,
@@ -194,6 +216,24 @@ export function resolveActivityConfig(
};
}
+export function resolveActivityPhaseConfig(
+ appConfig: AppConfig | undefined,
+ endpoint: string,
+ customEndpointConfig?: Partial<TEndpoint>,
+ publicEndpoint?: string,
+): ResolvedActivityPhaseConfig {
+ const pick = <K extends keyof ActivityEndpoint>(key: K): ActivityEndpoint[K] | undefined =>
+ pickEndpointField(appConfig, endpoint, customEndpointConfig, key, publicEndpoint);
+ return {
+ enabled: pick('activityPhaseLabel') === true,
+ model: pick('activityPhaseModel') ?? pick('activityModel'),
+ endpoint: pick('activityPhaseEndpoint') ?? pick('activityEndpoint'),
+ prompt: pick('activityPhasePrompt'),
+ maxPerRun: pick('activityPhaseMaxPerRun'),
+ charLimit: pick('activityCharLimit'),
+ };
+}
+
/**
* Resolves provider + client options for the label model, mirroring
* `titleConvo`'s resolution. Model precedence: the endpoint's
@@ -208,16 +248,24 @@ export async function resolveActivityLabelModel({
publicEndpoint,
ids,
db,
-}: ResolveActivityLabelModelParams): Promise<ActivityLabelLLM> {
+ phase = false,
+}: ResolveActivityLabelModelParams & { phase?: boolean }): Promise<ActivityLabelLLM> {
const appConfig = req.config as AppConfig | undefined;
const agentEndpoint = agent.endpoint ?? '';
let providerConfig = getProviderConfig({ provider: agentEndpoint, appConfig });
- const activity = resolveActivityConfig(
- appConfig,
- agentEndpoint,
- providerConfig.customEndpointConfig,
- publicEndpoint,
- );
+ const activity = phase
+ ? resolveActivityPhaseConfig(
+ appConfig,
+ agentEndpoint,
+ providerConfig.customEndpointConfig,
+ publicEndpoint,
+ )
+ : resolveActivityConfig(
+ appConfig,
+ agentEndpoint,
+ providerConfig.customEndpointConfig,
+ publicEndpoint,
+ );
/**
* Captured from the ORIGINATING endpoint, before any `activityEndpoint`
@@ -385,6 +433,13 @@ export async function resolveActivityLabelModel({
};
}
+/** Phase-model resolution shares credentials and sanitization with child labels. */
+export function resolveActivityPhaseLabelModel(
+ params: ResolveActivityLabelModelParams,
+): Promise<ActivityLabelLLM> {
+ return resolveActivityLabelModel({ ...params, phase: true });
+}
+
/**
* Bounded wait for in-flight label fills so a label resolving during the
* final batch still reaches the durable log and the saved message before the
diff --git a/packages/api/src/agents/activityLabels/index.ts b/packages/api/src/agents/activityLabels/index.ts
index f40c4b0c44..dc891e3fa7 100644
--- a/packages/api/src/agents/activityLabels/index.ts
+++ b/packages/api/src/agents/activityLabels/index.ts
@@ -3,6 +3,7 @@ export {
buildPrompt,
classifyBatch,
createActivityLabelHook,
+ stringifyActivityEvidence,
} from './runtime';
export type {
ActivityLabelBatchMeta,
@@ -23,12 +24,15 @@ export type { ActivityLabelHostDeps, LooseContentPart } from './wiring';
export {
mapCollectedMetadataToUsage,
resolveActivityConfig,
+ resolveActivityPhaseConfig,
resolveActivityLabelModel,
+ resolveActivityPhaseLabelModel,
settlePendingLabelFills,
} from './host';
export type {
ActivityLabelAgent,
ResolvedActivityConfig,
+ ResolvedActivityPhaseConfig,
ActivityLabelUsage,
CollectedMetadataEntry,
ResolveActivityLabelModelParams,
diff --git a/packages/api/src/agents/activityLabels/runtime.ts b/packages/api/src/agents/activityLabels/runtime.ts
index 21e9de5451..75e227f9d3 100644
--- a/packages/api/src/agents/activityLabels/runtime.ts
+++ b/packages/api/src/agents/activityLabels/runtime.ts
@@ -49,6 +49,7 @@ export interface ActivityLabelBatchMeta {
export interface ActivityLabelBlockContext {
thinkingExcerpts?: string[];
lastAssistantText?: string;
+ lastAssistantPhase?: 'commentary' | 'final_answer';
}
/**
@@ -317,7 +318,7 @@ function stringifyBounded(value: unknown, limit: number): string {
return out.join('').slice(0, limit + 1);
}
-function stringifyUnknown(value: unknown, limit: number): string {
+export function stringifyActivityEvidence(value: unknown, limit: number): string {
if (value == null) {
return '';
}
@@ -398,7 +399,7 @@ export function buildPrompt(
.join('\n'),
);
}
- if (context?.lastAssistantText) {
+ if (context?.lastAssistantText && context.lastAssistantPhase !== 'final_answer') {
sections.push(
`Intent (assistant's last message): ${truncate(context.lastAssistantText, INTENT_CHAR_LIMIT)}`,
);
@@ -426,11 +427,11 @@ export function buildPrompt(
omitted += 1;
continue;
}
- const input = truncate(stringifyUnknown(entry.toolInput, charLimit), charLimit);
+ const input = truncate(stringifyActivityEvidence(entry.toolInput, charLimit), charLimit);
const outcome =
entry.status === 'error'
? `ERROR: ${truncate(entry.error ?? 'unknown error', charLimit)}`
- : truncate(stringifyUnknown(entry.toolOutput, charLimit), charLimit);
+ : truncate(stringifyActivityEvidence(entry.toolOutput, charLimit), charLimit);
const line = `- ${entry.toolName}(${input}) → ${outcome}`;
lines.push(line);
used += line.length;
diff --git a/packages/api/src/agents/activityLabels/wiring.ts b/packages/api/src/agents/activityLabels/wiring.ts
index ee36b1c7ef..2e3583bc4b 100644
--- a/packages/api/src/agents/activityLabels/wiring.ts
+++ b/packages/api/src/agents/activityLabels/wiring.ts
@@ -17,6 +17,7 @@ export interface LooseContentPart {
groupId?: unknown;
tool_call?: { id?: unknown };
pending?: boolean;
+ phase?: unknown;
[key: string]: unknown;
}
@@ -48,6 +49,7 @@ export function captureActivityBlockContext(
): ActivityLabelBlockContext {
const thinkingExcerpts: string[] = [];
let lastAssistantText: string | undefined;
+ let lastAssistantPhase: ActivityLabelBlockContext['lastAssistantPhase'];
let collectThinking = true;
for (let i = parts.length - 1; i >= 0; i--) {
const part = parts[i];
@@ -68,6 +70,9 @@ export function captureActivityBlockContext(
const text = textValue(part.text).trim();
if (text.length > 0) {
lastAssistantText = text.slice(-INTENT_CHARS);
+ if (part.phase === 'commentary' || part.phase === 'final_answer') {
+ lastAssistantPhase = part.phase;
+ }
break;
}
continue;
@@ -84,7 +89,7 @@ export function captureActivityBlockContext(
}
}
}
- return { thinkingExcerpts, lastAssistantText };
+ return { thinkingExcerpts, lastAssistantText, lastAssistantPhase };
}
/**
@@ -128,9 +133,9 @@ interface ActivityLabelGapEvent {
* label publish is fire-and-forget and the sync payload carries only the
* snapshot, so a label claimed or resolved in that window would otherwise
* never reach the reconnecting client. Compares by index: a fresh label part
- * whose text or pending state differs from the snapshot's (or that has no
- * snapshot counterpart) is re-emitted. Idempotent - the client applier
- * ignores duplicates and refuses stale pending placeholders.
+ * whose text, pending state, or phase bounds differ from the snapshot's (or
+ * that has no snapshot counterpart) is re-emitted. Idempotent - the client
+ * applier ignores duplicates and refuses stale pending placeholders.
*/
export function synthesizeActivityLabelGapEvents(
snapshotContent: ReadonlyArray<LooseContentPart | null | undefined>,
@@ -147,6 +152,9 @@ export function synthesizeActivityLabelGapEvents(
const isSameLabel =
snapshot?.type === ContentTypes.ACTIVITY_LABEL &&
snapshot[ContentTypes.ACTIVITY_LABEL] === part[ContentTypes.ACTIVITY_LABEL] &&
+ snapshot.activity_label_type === part.activity_label_type &&
+ snapshot.activity_start_index === part.activity_start_index &&
+ snapshot.activity_count === part.activity_count &&
snapshot.pending === part.pending;
if (isSameLabel) {
continue;
@@ -218,7 +226,7 @@ export function createActivityLabelWiring(deps: ActivityLabelHostDeps): {
const initialLabels: Array<{ index: number; text: string }> = [];
for (let i = 0; i < resumedParts.length; i++) {
const part = resumedParts[i];
- if (part?.type !== ContentTypes.ACTIVITY_LABEL) {
+ if (part?.type !== ContentTypes.ACTIVITY_LABEL || part.activity_label_type === 'phase') {
continue;
}
initialGeneratedCount += 1;
diff --git a/packages/api/src/agents/activityPhases/index.ts b/packages/api/src/agents/activityPhases/index.ts
new file mode 100644
index 0000000000..2bc3e7914d
--- /dev/null
+++ b/packages/api/src/agents/activityPhases/index.ts
@@ -0,0 +1 @@
+export * from './runtime';
diff --git a/packages/api/src/agents/activityPhases/runtime.spec.ts b/packages/api/src/agents/activityPhases/runtime.spec.ts
new file mode 100644
index 0000000000..a529e0fb3c
--- /dev/null
+++ b/packages/api/src/agents/activityPhases/runtime.spec.ts
@@ -0,0 +1,710 @@
+import { GraphEvents } from '@librechat/agents';
+import { ContentTypes, StepTypes } from 'librechat-data-provider';
+import type { PostToolBatchHookInput } from '@librechat/agents';
+import type { LooseContentPart } from '~/agents/activityLabels/wiring';
+import type { GenerateActivityPhasePayload } from './runtime';
+import {
+ ACTIVITY_PHASE_INSTRUCTION,
+ createActivityPhaseWiring,
+ createAssistantPhaseStampingHandlers,
+} from './runtime';
+
+const batch = (id: string): PostToolBatchHookInput =>
+ ({
+ hook_event_name: 'PostToolBatch',
+ runId: 'run-1',
+ entries: [
+ {
+ toolName: 'web_search',
+ toolInput: { query: id },
+ toolUseId: id,
+ status: 'success',
+ toolOutput: `${id}-result`,
+ },
+ ],
+ }) as PostToolBatchHookInput;
+
+async function flushDetached(): Promise<void> {
+ for (let i = 0; i < 4; i += 1) {
+ await new Promise((resolve) => setImmediate(resolve));
+ }
+}
+
+describe('createActivityPhaseWiring', () => {
+ it('claims one parent phase before forwarding the final text step', async () => {
+ const parts: LooseContentPart[] = [];
+ const forwarded: unknown[] = [];
+ const emitLabelEvent = jest.fn(async () => undefined);
+ const generatePhase = jest.fn(async () => ({ label: 'Resolved the release compatibility' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent,
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+
+ parts.push({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'tool-1' },
+ });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ parts.push({
+ type: ContentTypes.TOOL_CALL,
+ tool_call: { id: 'tool-2' },
+ });
+ await wiring.hook(batch('tool-2'), new AbortController().signal);
+
+ const handlers = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: {
+ handle: (_event, data) => {
+ forwarded.push(data);
+ },
+ },
+ });
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ index: 2,
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: {
+ message_id: 'message-1',
+ content_type: 'text',
+ phase: 'final_answer',
+ },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ expect(forwarded).toHaveLength(1);
+ expect(parts[2]).toMatchObject({
+ type: ContentTypes.ACTIVITY_LABEL,
+ activity_label_type: 'phase',
+ activity_start_index: 0,
+ activity_count: 2,
+ pending: true,
+ });
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledWith(
+ expect.objectContaining({
+ closingTextPhase: 'final_answer',
+ phaseIndex: 0,
+ totalActivityCount: 2,
+ activities: expect.any(Array),
+ prompt: ACTIVITY_PHASE_INSTRUCTION,
+ }),
+ );
+ expect(parts[2]).toMatchObject({
+ activity_label: 'Resolved the release compatibility',
+ pending: false,
+ });
+ expect(emitLabelEvent).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not spend a phase call on one logical activity', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ ];
+ const generatePhase = jest.fn(async () => ({ label: 'unused' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ const handler = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })?.[GraphEvents.ON_RUN_STEP];
+ handler?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ await flushDetached();
+ expect(generatePhase).not.toHaveBeenCalled();
+ expect(parts).toHaveLength(1);
+ });
+
+ it('keeps reasoning attached to a tool batch across commentary', async () => {
+ const parts: LooseContentPart[] = [];
+ const generatePhase = jest.fn(async () => ({ label: 'unused' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ const handlers = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ [GraphEvents.ON_REASONING_DELTA]: { handle: jest.fn() },
+ });
+
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'reasoning-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'think' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ handlers?.[GraphEvents.ON_REASONING_DELTA]?.handle(
+ GraphEvents.ON_REASONING_DELTA,
+ {
+ id: 'reasoning-step',
+ delta: { content: { type: ContentTypes.THINK, think: 'Compared both auth paths.' } },
+ },
+ undefined,
+ undefined,
+ );
+ parts.push({ type: ContentTypes.THINK, think: 'Compared both auth paths.' });
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'commentary-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'commentary' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ expect(wiring.snapshot()).toMatchObject({
+ activityCount: 0,
+ pendingReasoning: [{ key: 'root', text: 'Compared both auth paths.' }],
+ });
+
+ parts.push({ type: ContentTypes.TEXT, text: 'I will verify the middleware.' });
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ expect(wiring.snapshot()).toMatchObject({
+ activityCount: 1,
+ activities: [expect.objectContaining({ thinkingExcerpts: ['Compared both auth paths.'] })],
+ pendingReasoning: [],
+ });
+
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ await flushDetached();
+ expect(generatePhase).not.toHaveBeenCalled();
+ expect(parts.some((part) => part.activity_label_type === 'phase')).toBe(false);
+ });
+
+ it('counts a top-level handoff as a logical phase activity', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'handoff-1' } },
+ ];
+ let generatedActivities: GenerateActivityPhasePayload['activities'] | undefined;
+ const generatePhase = jest.fn(async (payload: GenerateActivityPhasePayload) => {
+ generatedActivities = payload.activities;
+ return { label: 'Transferred ownership and verified the account state' };
+ });
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ const handoff = batch('handoff-1');
+ handoff.entries[0].toolName = 'lc_transfer_to_billing_agent';
+ await wiring.hook(handoff, new AbortController().signal);
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+
+ wiring
+ .handlers({ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() } })
+ ?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledTimes(1);
+ expect(generatedActivities).toHaveLength(2);
+ expect(generatedActivities?.[0]?.entries?.[0]?.toolName).toBe('lc_transfer_to_billing_agent');
+ });
+
+ it('keeps reasoning attached to an unphased parallel tool batch', async () => {
+ const parts: LooseContentPart[] = [];
+ const generatePhase = jest.fn(async () => ({ label: 'unused' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ const handlers = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ [GraphEvents.ON_REASONING_DELTA]: { handle: jest.fn() },
+ });
+
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'lane-reasoning',
+ agentId: 'agent-a',
+ groupId: 'lane-a',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'think' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ handlers?.[GraphEvents.ON_REASONING_DELTA]?.handle(
+ GraphEvents.ON_REASONING_DELTA,
+ {
+ id: 'lane-reasoning',
+ delta: { content: { type: ContentTypes.THINK, think: 'Checked the lane input.' } },
+ },
+ undefined,
+ undefined,
+ );
+ parts.push({ type: ContentTypes.THINK, think: 'Checked the lane input.' });
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'lane-text',
+ agentId: 'agent-a',
+ groupId: 'lane-a',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ expect(wiring.snapshot()).toMatchObject({
+ activityCount: 0,
+ pendingReasoning: [{ key: 'agent-a', text: 'Checked the lane input.' }],
+ });
+
+ parts.push({ type: ContentTypes.TEXT, text: 'I will inspect the tool result.' });
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } });
+ await wiring.hook(
+ { ...batch('tool-1'), executingAgentId: 'agent-a' },
+ new AbortController().signal,
+ );
+ expect(wiring.snapshot()).toMatchObject({
+ activityCount: 1,
+ activities: [expect.objectContaining({ thinkingExcerpts: ['Checked the lane input.'] })],
+ pendingReasoning: [],
+ });
+
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'root-text',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ await flushDetached();
+ expect(generatePhase).not.toHaveBeenCalled();
+ expect(parts.some((part) => part.activity_label_type === 'phase')).toBe(false);
+ });
+
+ it('anchors parallel standalone reasoning to each lane content part', async () => {
+ const parts: LooseContentPart[] = [];
+ const stepIndexes = new Map([
+ ['reasoning-a', 0],
+ ['reasoning-b', 1],
+ ]);
+ let generatedActivities: GenerateActivityPhasePayload['activities'] | undefined;
+ const generatePhase = jest.fn(async (payload: GenerateActivityPhasePayload) => {
+ generatedActivities = payload.activities;
+ return { label: 'Reconciled both agent analyses' };
+ });
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ getStepIndex: (stepId) => stepIndexes.get(stepId),
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ const handlers = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ [GraphEvents.ON_REASONING_DELTA]: { handle: jest.fn() },
+ });
+ const emitReasoning = (id: string, agentId: string, index: number, text: string) => {
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id,
+ index,
+ agentId,
+ groupId: agentId,
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'think' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ parts[index] = { type: ContentTypes.THINK, think: text, agentId, groupId: index + 1 };
+ handlers?.[GraphEvents.ON_REASONING_DELTA]?.handle(
+ GraphEvents.ON_REASONING_DELTA,
+ {
+ id,
+ delta: { content: { type: ContentTypes.THINK, think: text } },
+ },
+ undefined,
+ undefined,
+ );
+ };
+ emitReasoning('reasoning-a', 'agent-a', 0, 'Checked the first path.');
+ emitReasoning('reasoning-b', 'agent-b', 1, 'Checked the second path.');
+
+ expect(wiring.snapshot().pendingReasoning).toEqual([
+ expect.objectContaining({ key: 'agent-a', startIndex: 0 }),
+ expect.objectContaining({ key: 'agent-b', startIndex: 1 }),
+ ]);
+
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'root-final',
+ index: 2,
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledWith(
+ expect.objectContaining({ activities: expect.arrayContaining([expect.any(Object)]) }),
+ );
+ expect(generatedActivities).toHaveLength(2);
+ expect(parts[2]).toMatchObject({ activity_start_index: 0, activity_count: 2 });
+ });
+
+ it('restores bounded activity state after a HITL pause', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TEXT, text: 'Hidden intermediate output' },
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ ];
+ const first = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase: jest.fn(async () => ({})),
+ });
+ await first.hook(batch('tool-1'), new AbortController().signal);
+ /** `hide_sequential_outputs` reshapes the persisted prefix after the pause
+ * snapshot, so restoration must re-anchor by tool id rather than index. */
+ parts.shift();
+
+ let generatedActivities: GenerateActivityPhasePayload['activities'] | undefined;
+ const generatePhase = jest.fn(async (payload: GenerateActivityPhasePayload) => {
+ generatedActivities = payload.activities;
+ return { label: 'Completed the resumed investigation' };
+ });
+ const resumed = createActivityPhaseWiring({
+ initialSnapshot: first.snapshot(),
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-2' } });
+ await resumed.hook(batch('tool-2'), new AbortController().signal);
+ resumed
+ .handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })
+ ?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledWith(
+ expect.objectContaining({ activities: expect.arrayContaining([expect.any(Object)]) }),
+ );
+ expect(generatedActivities).toHaveLength(2);
+ expect(parts[parts.length - 1]).toMatchObject({ activity_start_index: 0 });
+ });
+
+ it('bounds persisted evidence while preserving the full activity count', async () => {
+ const parts: LooseContentPart[] = [];
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase: jest.fn(async () => ({})),
+ });
+ for (let index = 0; index < 20; index += 1) {
+ const id = `tool-${index}`;
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id } });
+ await wiring.hook(batch(id), new AbortController().signal);
+ }
+
+ const snapshot = wiring.snapshot();
+ expect(snapshot.activityCount).toBe(20);
+ expect(snapshot.activities).toHaveLength(13);
+ });
+
+ it('keeps a parallel lane final inside the run-wide phase', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ ];
+ const generatePhase = jest.fn(async () => ({ label: 'Combined both agent outcomes' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-2' } });
+ await wiring.hook(batch('tool-2'), new AbortController().signal);
+ const handler = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })?.[GraphEvents.ON_RUN_STEP];
+ const finalStep = {
+ id: 'lane-final',
+ groupId: 'lane-a',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ };
+ handler?.handle(GraphEvents.ON_RUN_STEP, finalStep, undefined, undefined);
+ await flushDetached();
+ expect(generatePhase).not.toHaveBeenCalled();
+
+ handler?.handle(
+ GraphEvents.ON_RUN_STEP,
+ { ...finalStep, id: 'root-final', groupId: undefined },
+ undefined,
+ undefined,
+ );
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps unphased parallel text inside the run-wide fallback phase', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ ];
+ const generatePhase = jest.fn(async () => ({ label: 'Combined both agent outcomes' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-2' } });
+ await wiring.hook(batch('tool-2'), new AbortController().signal);
+ const handler = wiring.handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })?.[GraphEvents.ON_RUN_STEP];
+ const textStep = {
+ id: 'lane-text',
+ groupId: 'lane-a',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text' },
+ },
+ };
+ handler?.handle(GraphEvents.ON_RUN_STEP, textStep, undefined, undefined);
+ await flushDetached();
+ expect(generatePhase).not.toHaveBeenCalled();
+
+ handler?.handle(
+ GraphEvents.ON_RUN_STEP,
+ { ...textStep, id: 'root-text', groupId: undefined },
+ undefined,
+ undefined,
+ );
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledTimes(1);
+ });
+
+ it('preserves mixed batch failures as a partial phase outcome', async () => {
+ const mixed = batch('tool-1');
+ mixed.entries.push({
+ toolName: 'web_search',
+ toolInput: { query: 'failed' },
+ toolUseId: 'tool-1b',
+ status: 'error',
+ error: 'unavailable',
+ });
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1b' } },
+ ];
+ const generatePhase = jest.fn(async () => ({ label: 'Recovered part of the search scope' }));
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase,
+ });
+ await wiring.hook(mixed, new AbortController().signal);
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-2' } });
+ await wiring.hook(batch('tool-2'), new AbortController().signal);
+ wiring
+ .handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })
+ ?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ await flushDetached();
+ expect(generatePhase).toHaveBeenCalledWith(expect.objectContaining({ status: 'partial' }));
+ expect(parts[parts.length - 1]).toMatchObject({ status: 'partial' });
+ });
+
+ it('collects usage after a committed blank phase result', async () => {
+ const parts: LooseContentPart[] = [
+ { type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-1' } },
+ ];
+ const collectUsage = jest.fn(async () => undefined);
+ const wiring = createActivityPhaseWiring({
+ getContentParts: () => parts,
+ bumpIndexOffset: jest.fn(),
+ emitLabelEvent: jest.fn(async () => undefined),
+ trackPendingFill: jest.fn(),
+ generatePhase: jest.fn(async () => ({ collectUsage })),
+ });
+ await wiring.hook(batch('tool-1'), new AbortController().signal);
+ parts.push({ type: ContentTypes.TOOL_CALL, tool_call: { id: 'tool-2' } });
+ await wiring.hook(batch('tool-2'), new AbortController().signal);
+ wiring
+ .handlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ })
+ ?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'final-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', content_type: 'text', phase: 'final_answer' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+
+ await flushDetached();
+ expect(collectUsage).toHaveBeenCalledWith(undefined);
+ expect(parts[parts.length - 1]).toMatchObject({ activity_label: '', pending: false });
+ });
+});
+
+describe('createAssistantPhaseStampingHandlers', () => {
+ it('stamps commentary onto persisted text deltas for child activity-label intent', () => {
+ const received: unknown[] = [];
+ const handlers = createAssistantPhaseStampingHandlers({
+ [GraphEvents.ON_RUN_STEP]: { handle: jest.fn() },
+ [GraphEvents.ON_MESSAGE_DELTA]: {
+ handle: (_event, data) => {
+ received.push(data);
+ },
+ },
+ });
+ handlers?.[GraphEvents.ON_RUN_STEP]?.handle(
+ GraphEvents.ON_RUN_STEP,
+ {
+ id: 'commentary-step',
+ stepDetails: {
+ type: StepTypes.MESSAGE_CREATION,
+ message_creation: { message_id: 'm', phase: 'commentary' },
+ },
+ },
+ undefined,
+ undefined,
+ );
+ handlers?.[GraphEvents.ON_MESSAGE_DELTA]?.handle(
+ GraphEvents.ON_MESSAGE_DELTA,
+ {
+ id: 'commentary-step',
+ delta: { content: { type: ContentTypes.TEXT, text: 'I will compare both paths.' } },
+ },
+ undefined,
+ undefined,
+ );
+ expect(received[0]).toMatchObject({
+ delta: { content: { type: ContentTypes.TEXT, phase: 'commentary' } },
+ });
+ });
+});
diff --git a/packages/api/src/agents/activityPhases/runtime.ts b/packages/api/src/agents/activityPhases/runtime.ts
new file mode 100644
index 0000000000..577a896230
--- /dev/null
+++ b/packages/api/src/agents/activityPhases/runtime.ts
@@ -0,0 +1,717 @@
+import { GraphEvents } from '@librechat/agents';
+import { ContentTypes, StepTypes } from 'librechat-data-provider';
+import type { EventHandler, HookCallback, HookInputByEvent } from '@librechat/agents';
+import type { LooseContentPart } from '~/agents/activityLabels/wiring';
+import { stringifyActivityEvidence } from '~/agents/activityLabels/runtime';
+
+type PostToolBatchInput = HookInputByEvent['PostToolBatch'];
+type BatchEntry = PostToolBatchInput['entries'][number];
+
+export type AssistantTextPhase = 'commentary' | 'final_answer';
+
+export interface ActivityPhaseEntry {
+ label?: string;
+ entries?: Array<{
+ toolName: string;
+ toolInput: unknown;
+ toolOutput?: unknown;
+ error?: string;
+ status: 'success' | 'error';
+ }>;
+ thinkingExcerpts?: string[];
+ agentId?: string;
+ status?: 'success' | 'partial' | 'error';
+}
+
+type TrackedActivity = ActivityPhaseEntry & {
+ startIndex: number;
+ childLabelIndex?: number;
+ /** Stable anchors survive content filtering and prepends across HITL resume. */
+ toolCallIds?: string[];
+};
+
+export interface ActivityPhaseSnapshot {
+ version: 1;
+ generated: number;
+ activityCount: number;
+ failedActivityCount: number;
+ partialActivityCount: number;
+ agentIds: string[];
+ activities: TrackedActivity[];
+ assistantContext: string[];
+ pendingReasoning: Array<{
+ key: string;
+ text: string;
+ agentId?: string;
+ startIndex?: number;
+ }>;
+}
+
+export interface GenerateActivityPhasePayload {
+ activities: ActivityPhaseEntry[];
+ assistantContext?: string[];
+ closingTextPhase?: AssistantTextPhase;
+ phaseIndex: number;
+ totalActivityCount: number;
+ status: 'completed' | 'partial' | 'failed';
+ agentIds: string[];
+ charLimit: number;
+ prompt?: string;
+ signal: AbortSignal;
+}
+
+export interface GeneratedActivityPhase {
+ label?: string;
+ collectUsage?: (label?: string) => void | Promise<void>;
+}
+
+export interface ActivityPhaseHostDeps {
+ maxPerRun?: number;
+ charLimit?: number;
+ prompt?: string;
+ abortSignal?: AbortSignal;
+ initialSnapshot?: ActivityPhaseSnapshot;
+ getContentParts: () => Array<LooseContentPart | null | undefined>;
+ getStepIndex?: (stepId: string) => number | undefined;
+ bumpIndexOffset: () => void;
+ emitLabelEvent: (index: number, part: LooseContentPart) => Promise<unknown>;
+ trackPendingFill: (fillDone: Promise<void>) => void;
+ isClosed?: () => boolean;
+ generatePhase: (payload: GenerateActivityPhasePayload) => Promise<GeneratedActivityPhase>;
+}
+
+export interface ActivityPhaseWiring {
+ hook: HookCallback<'PostToolBatch'>;
+ handlers: (
+ handlers: Record<string, EventHandler> | undefined,
+ ) => Record<string, EventHandler> | undefined;
+ /** A steer is a hard semantic boundary; incomplete evidence is discarded. */
+ drop: () => void;
+ /** Bounded state needed to continue the same phase after a HITL pause. */
+ snapshot: () => ActivityPhaseSnapshot;
+}
+
+const DEFAULT_MAX_PER_RUN = 5;
+const DEFAULT_CHAR_LIMIT = 600;
+const MIN_ACTIVITIES = 2;
+const MAX_CONTEXT_ITEMS = 6;
+const MAX_EXCERPT_CHARS = 600;
+const OUTPUT_CHAR_LIMIT = 160;
+const PHASE_TIMEOUT_MS = 12_000;
+/** Twelve enter the SDK prompt; one extra preserves its omitted-activity row. */
+const MAX_RETAINED_ACTIVITIES = 13;
+const MAX_RETAINED_TOOL_ENTRIES = 6;
+
+export const ACTIVITY_PHASE_INSTRUCTION = `Summarize what this phase of an agent run accomplished. The result appears as the header of one collapsed parent group containing several activities.
+
+Rules:
+- One line, 8 to 18 words, past tense
+- Lead with the concrete outcome and name the most distinctive subject
+- Synthesize the phase; do not enumerate, count, or restate individual activities
+- Describe failures plainly when they are the phase's material outcome
+- Never mention tool names, calls, arguments, reasoning, commentary, or activity counts
+- Output only the summary — no quotes, no trailing punctuation, no preamble
+
+Examples:
+- Reconciled authentication behavior and fixed the failing session refresh path
+- Compared deployment options and documented the safest production rollout
+- Investigated database latency but could not confirm the suspected index regression
+
+Bad examples:
+- Used three tools to inspect files and run tests
+- Searched code, read configuration, and updated middleware`;
+
+interface DeltaPart {
+ text?: unknown;
+ think?: unknown;
+}
+
+function textValue(value: unknown): string {
+ if (typeof value === 'string') {
+ return value;
+ }
+ const nested = (value as { value?: unknown } | null | undefined)?.value;
+ return typeof nested === 'string' ? nested : '';
+}
+
+function normalizeLabel(value: string | undefined): string {
+ const firstLine = value?.split(/\r?\n/).find((line) => line.trim().length > 0) ?? '';
+ const normalized = firstLine.replace(/\s+/g, ' ').trim();
+ return normalized.length > OUTPUT_CHAR_LIMIT
+ ? `${normalized.slice(0, OUTPUT_CHAR_LIMIT - 1)}…`
+ : normalized;
+}
+
+function deltaText(data: unknown, key: 'text' | 'think'): string {
+ const raw = (data as { delta?: { content?: unknown } } | null)?.delta?.content;
+ let parts: unknown[] = [];
+ if (Array.isArray(raw)) {
+ parts = raw;
+ } else if (raw != null) {
+ parts = [raw];
+ }
+ return parts.map((part) => textValue((part as DeltaPart | null)?.[key])).join('');
+}
+
+function buildSignal(signal?: AbortSignal): AbortSignal {
+ const timeout = AbortSignal.timeout(PHASE_TIMEOUT_MS);
+ return signal != null && typeof AbortSignal.any === 'function'
+ ? AbortSignal.any([signal, timeout])
+ : timeout;
+}
+
+function findLastPartIndex(
+ parts: ReadonlyArray<LooseContentPart | null | undefined>,
+ type: string,
+): number {
+ for (let i = parts.length - 1; i >= 0; i--) {
+ if (parts[i]?.type === type) {
+ return i;
+ }
+ }
+ return Math.max(0, parts.length - 1);
+}
+
+function findBatchStart(
+ parts: ReadonlyArray<LooseContentPart | null | undefined>,
+ toolCallIds: Set<string>,
+): number {
+ let first = -1;
+ for (let i = 0; i < parts.length; i++) {
+ const part = parts[i];
+ if (
+ part?.type === ContentTypes.TOOL_CALL &&
+ typeof part.tool_call?.id === 'string' &&
+ toolCallIds.has(part.tool_call.id)
+ ) {
+ first = first < 0 ? i : Math.min(first, i);
+ }
+ }
+ return first >= 0 ? first : Math.max(0, parts.length - 1);
+}
+
+function findTrackedStart(
+ parts: ReadonlyArray<LooseContentPart | null | undefined>,
+ activity: TrackedActivity,
+): number {
+ if (activity.toolCallIds != null && activity.toolCallIds.length > 0) {
+ const toolStart = findBatchStart(parts, new Set(activity.toolCallIds));
+ if (
+ parts[toolStart]?.type === ContentTypes.TOOL_CALL &&
+ activity.toolCallIds.includes(String(parts[toolStart]?.tool_call?.id ?? ''))
+ ) {
+ return toolStart;
+ }
+ }
+ const excerpt = activity.thinkingExcerpts?.[0]?.trim();
+ if (excerpt) {
+ const needle = excerpt.slice(0, 80);
+ for (let i = 0; i < parts.length; i++) {
+ if (parts[i]?.type === ContentTypes.THINK && textValue(parts[i]?.think).includes(needle)) {
+ return i;
+ }
+ }
+ }
+ return Math.min(activity.startIndex, Math.max(0, parts.length - 1));
+}
+
+function findReasoningStart(
+ parts: ReadonlyArray<LooseContentPart | null | undefined>,
+ text: string,
+ startIndex?: number,
+): number {
+ const needle = text.trim().slice(0, 80);
+ const matches = (part: LooseContentPart | null | undefined) =>
+ part?.type === ContentTypes.THINK && textValue(part.think).includes(needle);
+ if (startIndex != null && matches(parts[startIndex])) {
+ return startIndex;
+ }
+ for (let index = 0; index < parts.length; index += 1) {
+ if (matches(parts[index])) {
+ return index;
+ }
+ }
+ return startIndex ?? findLastPartIndex(parts, ContentTypes.THINK);
+}
+
+/** Persists Open Responses text-phase metadata onto LibreChat text parts.
+ * Installed for existing batch labels too, so commentary can supply intent
+ * even when parent phase summaries are disabled. */
+export function createAssistantPhaseStampingHandlers(
+ handlers: Record<string, EventHandler> | undefined,
+): Record<string, EventHandler> | undefined {
+ if (handlers == null) {
+ return handlers;
+ }
+ const phases = new Map<string, AssistantTextPhase>();
+ const wrapped = { ...handlers };
+ const runStepHandler = handlers[GraphEvents.ON_RUN_STEP];
+ if (runStepHandler != null) {
+ wrapped[GraphEvents.ON_RUN_STEP] = {
+ handle: (event, data, metadata, graph) => {
+ const step = data as {
+ id?: string;
+ stepDetails?: { message_creation?: { phase?: string } };
+ };
+ const phase = step.stepDetails?.message_creation?.phase;
+ if (step.id && (phase === 'commentary' || phase === 'final_answer')) {
+ phases.set(step.id, phase);
+ }
+ return runStepHandler.handle(event, data, metadata, graph);
+ },
+ };
+ }
+ const messageHandler = handlers[GraphEvents.ON_MESSAGE_DELTA];
+ if (messageHandler != null) {
+ wrapped[GraphEvents.ON_MESSAGE_DELTA] = {
+ handle: (event, data, metadata, graph) => {
+ const phase = phases.get((data as { id?: string }).id ?? '');
+ const delta = (data as { delta?: { content?: unknown } }).delta;
+ const raw = delta?.content;
+ if (phase == null || raw == null) {
+ return messageHandler.handle(event, data, metadata, graph);
+ }
+ const stamp = (part: unknown) =>
+ (part as { type?: string } | null)?.type === ContentTypes.TEXT
+ ? { ...(part as Record<string, unknown>), phase }
+ : part;
+ const forwarded = {
+ ...(data as Record<string, unknown>),
+ delta: {
+ ...delta,
+ content: Array.isArray(raw) ? raw.map(stamp) : stamp(raw),
+ },
+ };
+ return messageHandler.handle(event, forwarded, metadata, graph);
+ },
+ };
+ }
+ return wrapped;
+}
+
+/**
+ * Collects run-wide logical activities and emits one parent summary at a text
+ * boundary. The summary call is detached; the boundary only pays the cheap
+ * synchronous slot claim needed to keep streamed content indices stable.
+ */
+export function createActivityPhaseWiring(deps: ActivityPhaseHostDeps): ActivityPhaseWiring {
+ const maxPerRun = deps.maxPerRun ?? DEFAULT_MAX_PER_RUN;
+ const charLimit = deps.charLimit ?? DEFAULT_CHAR_LIMIT;
+ const content = deps.getContentParts();
+ const initialSnapshot = deps.initialSnapshot?.version === 1 ? deps.initialSnapshot : undefined;
+ let generated = Math.max(
+ initialSnapshot?.generated ?? 0,
+ content.filter(
+ (part) => part?.type === ContentTypes.ACTIVITY_LABEL && part.activity_label_type === 'phase',
+ ).length,
+ );
+ let activities: TrackedActivity[] =
+ initialSnapshot?.activities.map((activity) => ({
+ ...activity,
+ startIndex: findTrackedStart(content, activity),
+ })) ?? [];
+ let activityCount = initialSnapshot?.activityCount ?? activities.length;
+ let failedActivityCount =
+ initialSnapshot?.failedActivityCount ??
+ activities.filter((activity) => activity.status === 'error').length;
+ let partialActivityCount =
+ initialSnapshot?.partialActivityCount ??
+ activities.filter((activity) => activity.status === 'partial').length;
+ const contributingAgentIds = new Set(initialSnapshot?.agentIds ?? []);
+ let assistantContext = (initialSnapshot?.assistantContext ?? []).slice(-MAX_CONTEXT_ITEMS);
+ const pendingReasoning = new Map<string, { text: string; agentId?: string; startIndex?: number }>(
+ (initialSnapshot?.pendingReasoning ?? []).map(({ key, text, agentId, startIndex }) => [
+ key,
+ {
+ text: text.slice(-MAX_EXCERPT_CHARS),
+ ...(agentId != null && { agentId }),
+ ...(startIndex != null && { startIndex }),
+ },
+ ]),
+ );
+ const reasoningStepKeys = new Map<string, string>();
+ const stepKinds = new Map<
+ string,
+ { kind: 'text' | 'think'; phase?: AssistantTextPhase; captureContext?: boolean }
+ >();
+
+ const clear = () => {
+ activities = [];
+ assistantContext = [];
+ pendingReasoning.clear();
+ reasoningStepKeys.clear();
+ stepKinds.clear();
+ activityCount = 0;
+ failedActivityCount = 0;
+ partialActivityCount = 0;
+ contributingAgentIds.clear();
+ };
+
+ const trackActivity = (activity: TrackedActivity) => {
+ activityCount += 1;
+ if (activity.status === 'error') {
+ failedActivityCount += 1;
+ } else if (activity.status === 'partial') {
+ partialActivityCount += 1;
+ }
+ if (activity.agentId != null) {
+ contributingAgentIds.add(activity.agentId);
+ }
+ if (activities.length < MAX_RETAINED_ACTIVITIES) {
+ activities.push(activity);
+ }
+ };
+
+ const snapshot = (): ActivityPhaseSnapshot => ({
+ version: 1,
+ generated,
+ activityCount,
+ failedActivityCount,
+ partialActivityCount,
+ agentIds: [...contributingAgentIds],
+ activities: activities.map((activity) => ({
+ ...activity,
+ ...(activity.entries != null && {
+ entries: activity.entries.slice(0, MAX_RETAINED_TOOL_ENTRIES).map((entry) => ({
+ ...entry,
+ toolInput: stringifyActivityEvidence(entry.toolInput, charLimit),
+ ...(entry.toolOutput != null && {
+ toolOutput: stringifyActivityEvidence(entry.toolOutput, charLimit),
+ }),
+ ...(entry.error != null && { error: entry.error.slice(0, charLimit) }),
+ })),
+ }),
+ ...(activity.thinkingExcerpts != null && {
+ thinkingExcerpts: activity.thinkingExcerpts.map((text) => text.slice(-MAX_EXCERPT_CHARS)),
+ }),
+ })),
+ assistantContext: assistantContext.slice(-MAX_CONTEXT_ITEMS),
+ pendingReasoning: [...pendingReasoning].map(([key, reasoning]) => ({
+ key,
+ text: reasoning.text.slice(-MAX_EXCERPT_CHARS),
+ ...(reasoning.agentId != null && { agentId: reasoning.agentId }),
+ ...(reasoning.startIndex != null && { startIndex: reasoning.startIndex }),
+ })),
+ });
+
+ const addPendingReasoning = (onlyKey?: string) => {
+ let selected = [...pendingReasoning.entries()] as Array<
+ readonly [string, { text: string; agentId?: string; startIndex?: number }]
+ >;
+ if (onlyKey != null) {
+ const reasoning = pendingReasoning.get(onlyKey);
+ selected = reasoning == null ? [] : [[onlyKey, reasoning] as const];
+ }
+ for (const [key, reasoning] of selected) {
+ const text = reasoning.text.trim();
+ if (text) {
+ const parts = deps.getContentParts();
+ trackActivity({
+ thinkingExcerpts: [text.slice(0, MAX_EXCERPT_CHARS)],
+ ...(reasoning.agentId != null && { agentId: reasoning.agentId }),
+ status: 'success',
+ startIndex: findReasoningStart(parts, text, reasoning.startIndex),
+ });
+ }
+ pendingReasoning.delete(key);
+ }
+ };
+
+ const resolveActivities = (snapshot: TrackedActivity[]): ActivityPhaseEntry[] => {
+ const parts = deps.getContentParts();
+ return snapshot.map(
+ ({ childLabelIndex, toolCallIds, startIndex: _startIndex, ...activity }) => {
+ const matchesToolIds = (part: LooseContentPart | null | undefined): boolean => {
+ if (part?.type !== ContentTypes.ACTIVITY_LABEL || part.activity_label_type === 'phase') {
+ return false;
+ }
+ if (toolCallIds == null || toolCallIds.length === 0) {
+ return true;
+ }
+ const childIds = Array.isArray(part.tool_call_ids) ? part.tool_call_ids : [];
+ return childIds.some((id) => typeof id === 'string' && toolCallIds.includes(id));
+ };
+ let child = childLabelIndex == null ? undefined : parts[childLabelIndex];
+ if (!matchesToolIds(child) && toolCallIds != null && toolCallIds.length > 0) {
+ child = parts.find(matchesToolIds);
+ }
+ if (!matchesToolIds(child)) {
+ return activity;
+ }
+ const label =
+ child?.pending !== true ? textValue(child?.[ContentTypes.ACTIVITY_LABEL]).trim() : '';
+ return label ? { ...activity, label, entries: undefined } : activity;
+ },
+ );
+ };
+
+ const close = (closingTextPhase?: AssistantTextPhase, hardBoundary = false) => {
+ addPendingReasoning();
+ if (generated >= maxPerRun) {
+ clear();
+ return;
+ }
+ if (activityCount < MIN_ACTIVITIES) {
+ if (hardBoundary) clear();
+ return;
+ }
+
+ generated += 1;
+ const phaseIndex = generated - 1;
+ const snapshot = [...activities];
+ const contextSnapshot = [...assistantContext];
+ const totalActivityCount = activityCount;
+ const failedCount = failedActivityCount;
+ const partialCount = partialActivityCount;
+ let startIndex = Math.min(...snapshot.map((activity) => activity.startIndex));
+ const currentParts = deps.getContentParts();
+ /** Pull leading commentary/reasoning into the parent card. A prior phase
+ * marker or steer is the only hard UI boundary; plain text can be
+ * intermediate context on providers that do not expose phase metadata. */
+ for (let i = startIndex - 1; i >= 0; i--) {
+ const prior = currentParts[i];
+ if (
+ prior?.type === ContentTypes.STEER ||
+ (prior?.type === ContentTypes.ACTIVITY_LABEL && prior.activity_label_type === 'phase') ||
+ (prior?.type === ContentTypes.TEXT && prior.phase === 'final_answer')
+ ) {
+ break;
+ }
+ startIndex = i;
+ }
+ const agentIds = [...contributingAgentIds];
+ let phaseStatus: 'ok' | 'partial' | 'failed' = 'ok';
+ if (failedCount === totalActivityCount) {
+ phaseStatus = 'failed';
+ } else if (failedCount > 0 || partialCount > 0) {
+ phaseStatus = 'partial';
+ }
+ const index = deps.getContentParts().length;
+ const part: LooseContentPart = {
+ type: ContentTypes.ACTIVITY_LABEL,
+ [ContentTypes.ACTIVITY_LABEL]: '',
+ activity_label_type: 'phase',
+ activity_start_index: startIndex,
+ activity_count: totalActivityCount,
+ ...(agentIds.length > 0 && { agent_ids: agentIds }),
+ status: phaseStatus,
+ pending: true,
+ };
+ deps.getContentParts().push(part);
+ deps.bumpIndexOffset();
+ void Promise.resolve(deps.emitLabelEvent(index, part)).catch(() => undefined);
+ clear();
+
+ const task = (async () => {
+ let generatedPhase: GeneratedActivityPhase = {};
+ try {
+ generatedPhase = await deps.generatePhase({
+ activities: resolveActivities(snapshot),
+ ...(contextSnapshot.length > 0 && { assistantContext: contextSnapshot }),
+ ...(closingTextPhase != null && { closingTextPhase }),
+ phaseIndex,
+ totalActivityCount,
+ status: phaseStatus === 'ok' ? 'completed' : phaseStatus,
+ agentIds,
+ charLimit,
+ prompt: deps.prompt ?? ACTIVITY_PHASE_INSTRUCTION,
+ signal: buildSignal(deps.abortSignal),
+ });
+ } catch {
+ generatedPhase = {};
+ }
+ if (deps.isClosed?.() === true) {
+ return;
+ }
+ const label = normalizeLabel(generatedPhase.label);
+ const next: LooseContentPart = {
+ ...part,
+ [ContentTypes.ACTIVITY_LABEL]: label,
+ pending: false,
+ };
+ try {
+ await deps.emitLabelEvent(index, next);
+ Object.assign(part, next);
+ } catch {
+ // A failed durable fill leaves the pending marker invisible and unbilled.
+ return;
+ }
+ try {
+ if (generatedPhase.collectUsage != null) {
+ await generatedPhase.collectUsage(label || undefined);
+ }
+ } catch {
+ // The committed UI projection must not regress when accounting fails.
+ }
+ })();
+ deps.trackPendingFill(task);
+ };
+
+ const hook: HookCallback<'PostToolBatch'> = async (input: PostToolBatchInput) => {
+ if (input.agentId != null || input.entries.length === 0 || deps.abortSignal?.aborted) {
+ return {};
+ }
+ /** A top-level handoff is intentionally one logical phase activity. The
+ * child-label hook skips it because a transfer card cannot join a tool
+ * group; the parent phase can contain that card and should summarize the
+ * material agent transition. `input.agentId` above still excludes nested
+ * subagent internals. */
+ const reasoningKey = input.executingAgentId ?? 'root';
+ const reasoning = pendingReasoning.get(reasoningKey)?.text.trim();
+ const ids = new Set(input.entries.map((entry) => entry.toolUseId));
+ const parts = deps.getContentParts();
+ let childLabelIndex: number | undefined;
+ for (let i = parts.length - 1; i >= 0; i--) {
+ const part = parts[i];
+ if (part?.type !== ContentTypes.ACTIVITY_LABEL || part.activity_label_type === 'phase') {
+ continue;
+ }
+ const childIds = Array.isArray(part.tool_call_ids) ? part.tool_call_ids : [];
+ if (childIds.some((id) => typeof id === 'string' && ids.has(id))) {
+ childLabelIndex = i;
+ break;
+ }
+ }
+ const entries = input.entries.map((entry: BatchEntry) => ({
+ toolName: entry.toolName,
+ toolInput: entry.toolInput,
+ toolOutput: entry.toolOutput,
+ error: entry.error,
+ status: entry.status,
+ }));
+ const failures = entries.filter((entry) => entry.status === 'error').length;
+ let activityStatus: TrackedActivity['status'] = 'success';
+ if (failures === entries.length) {
+ activityStatus = 'error';
+ } else if (failures > 0) {
+ activityStatus = 'partial';
+ }
+ trackActivity({
+ entries,
+ ...(reasoning ? { thinkingExcerpts: [reasoning.slice(0, MAX_EXCERPT_CHARS)] } : {}),
+ ...(input.executingAgentId != null && { agentId: input.executingAgentId }),
+ status: activityStatus,
+ startIndex: findBatchStart(parts, ids),
+ toolCallIds: [...ids],
+ ...(childLabelIndex != null && { childLabelIndex }),
+ });
+ pendingReasoning.delete(reasoningKey);
+ return {};
+ };
+
+ const wrapHandlers = (
+ handlers: Record<string, EventHandler> | undefined,
+ ): Record<string, EventHandler> | undefined => {
+ if (handlers == null) {
+ return handlers;
+ }
+ const phaseHandlers = createAssistantPhaseStampingHandlers(handlers) ?? handlers;
+ const wrapped = { ...phaseHandlers };
+ const runStepHandler = phaseHandlers[GraphEvents.ON_RUN_STEP];
+ if (runStepHandler != null) {
+ wrapped[GraphEvents.ON_RUN_STEP] = {
+ handle: (event, data, metadata, graph) => {
+ const step = data as {
+ id?: string;
+ agentId?: string;
+ groupId?: string | number;
+ stepDetails?: {
+ type?: string;
+ message_creation?: { content_type?: string; phase?: string };
+ };
+ };
+ if (step.stepDetails?.type === StepTypes.MESSAGE_CREATION && step.id) {
+ const creation = step.stepDetails.message_creation;
+ const kind = creation?.content_type === 'think' ? 'think' : 'text';
+ const phase =
+ creation?.phase === 'commentary' || creation?.phase === 'final_answer'
+ ? creation.phase
+ : undefined;
+ if (kind === 'think') {
+ stepKinds.set(step.id, { kind });
+ const reasoningKey = step.agentId ?? 'root';
+ reasoningStepKeys.set(step.id, reasoningKey);
+ const result = runStepHandler.handle(event, data, metadata, graph);
+ if (!pendingReasoning.has(reasoningKey)) {
+ const startIndex = deps.getStepIndex?.(step.id);
+ pendingReasoning.set(reasoningKey, {
+ text: '',
+ ...(step.agentId != null && { agentId: step.agentId }),
+ ...(startIndex != null && { startIndex }),
+ });
+ }
+ return result;
+ } else {
+ if (phase === 'final_answer' && step.groupId == null) {
+ addPendingReasoning(step.agentId ?? 'root');
+ stepKinds.set(step.id, { kind, phase, captureContext: false });
+ close(phase, true);
+ } else {
+ if (phase == null && step.groupId == null) {
+ addPendingReasoning(step.agentId ?? 'root');
+ }
+ const closesPhase =
+ phase == null && step.groupId == null && activityCount >= MIN_ACTIVITIES;
+ stepKinds.set(step.id, {
+ kind,
+ ...(phase != null && { phase }),
+ captureContext: !closesPhase,
+ });
+ if (closesPhase) {
+ close(undefined, false);
+ } else {
+ assistantContext.push('');
+ if (assistantContext.length > MAX_CONTEXT_ITEMS) assistantContext.shift();
+ }
+ }
+ }
+ }
+ return runStepHandler.handle(event, data, metadata, graph);
+ },
+ };
+ }
+
+ const messageHandler = phaseHandlers[GraphEvents.ON_MESSAGE_DELTA];
+ if (messageHandler != null) {
+ wrapped[GraphEvents.ON_MESSAGE_DELTA] = {
+ handle: (event, data, metadata, graph) => {
+ const id = (data as { id?: string }).id;
+ const tracked = id ? stepKinds.get(id) : undefined;
+ if (tracked?.kind === 'text' && tracked.captureContext === true) {
+ const text = deltaText(data, 'text');
+ if (text) {
+ const last = assistantContext.length - 1;
+ const next = `${last >= 0 ? assistantContext[last] : ''}${text}`.slice(
+ -MAX_EXCERPT_CHARS,
+ );
+ if (last >= 0) assistantContext[last] = next;
+ else assistantContext.push(next);
+ if (assistantContext.length > MAX_CONTEXT_ITEMS) assistantContext.shift();
+ }
+ }
+ return messageHandler.handle(event, data, metadata, graph);
+ },
+ };
+ }
+
+ const reasoningHandler = phaseHandlers[GraphEvents.ON_REASONING_DELTA];
+ if (reasoningHandler != null) {
+ wrapped[GraphEvents.ON_REASONING_DELTA] = {
+ handle: (event, data, metadata, graph) => {
+ const id = (data as { id?: string }).id;
+ const reasoningKey = id ? reasoningStepKeys.get(id) : undefined;
+ const reasoning = reasoningKey ? pendingReasoning.get(reasoningKey) : undefined;
+ if (reasoning != null) {
+ reasoning.text = `${reasoning.text}${deltaText(data, 'think')}`.slice(
+ -MAX_EXCERPT_CHARS,
+ );
+ }
+ return reasoningHandler.handle(event, data, metadata, graph);
+ },
+ };
+ }
+ return wrapped;
+ };
+
+ return { hook, handlers: wrapHandlers, drop: clear, snapshot };
+}
diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts
index 8e1b408073..b7fa363488 100644
--- a/packages/api/src/agents/index.ts
+++ b/packages/api/src/agents/index.ts
@@ -42,4 +42,5 @@ export * from './hitl';
export * from './hooks';
export * from './steering';
export * from './activityLabels';
+export * from './activityPhases';
export * from './toolValidation';
diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts
index a41fe79aee..800d3ccfe4 100644
--- a/packages/api/src/agents/run.ts
+++ b/packages/api/src/agents/run.ts
@@ -1184,6 +1184,7 @@ export async function createRun({
subagentUsageSink,
steering,
activityLabel,
+ activityPhase,
hitlCapable = false,
toolInputValidationErrors,
streaming = true,
@@ -1262,6 +1263,8 @@ export async function createRun({
* the hook returns immediately and generates off the critical path.
*/
activityLabel?: { hook: HookCallback<'PostToolBatch'> };
+ /** Run-wide parent phase collector; registered after child batch labels. */
+ activityPhase?: { hook: HookCallback<'PostToolBatch'> };
/**
* Whether the caller implements the HITL pause/resume lifecycle (inspects
* `run.getInterrupt()`, persists a pending action, exposes a resume route). Gates the
@@ -1631,6 +1634,10 @@ export async function createRun({
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', { hooks: [activityLabel.hook] });
}
+ if (activityPhase != null) {
+ hooks = hooks ?? new HookRegistry();
+ hooks.register('PostToolBatch', { hooks: [activityPhase.hook] });
+ }
if (steering != null && isSteeringSupported()) {
hooks = hooks ?? new HookRegistry();
hooks.register('PostToolBatch', { hooks: [steering.hook] });
diff --git a/packages/api/src/stream/ApprovalLifecycle.ts b/packages/api/src/stream/ApprovalLifecycle.ts
index 2bf081c666..29797a09cf 100644
--- a/packages/api/src/stream/ApprovalLifecycle.ts
+++ b/packages/api/src/stream/ApprovalLifecycle.ts
@@ -1,6 +1,7 @@
import { logger } from '@librechat/data-schemas';
import type { Agents } from 'librechat-data-provider';
import type { IJobStoreV2, JobMetadataPatch, SteerQueueItem } from '~/stream/interfaces/IJobStore';
+import type { ActivityPhaseSnapshot } from '~/agents/activityPhases/runtime';
import {
isPendingActionExpired,
isPendingActionStale,
@@ -22,6 +23,7 @@ export interface ApprovalLifecycleCallbacks {
export interface ApprovalPauseOptions {
discoveredTools?: string[];
+ activityPhaseSnapshot?: ActivityPhaseSnapshot;
/** Generation identity observed by the interrupted run. */
expectedCreatedAt?: number;
/** Hold Stop/resume until the paused assistant row is durably unfinished. */
@@ -88,6 +90,7 @@ export class ApprovalLifecycle {
}
const expectedCreatedAt = options.expectedCreatedAt ?? job.createdAt;
const discoveredTools = options.discoveredTools;
+ const activityPhaseSnapshot = options.activityPhaseSnapshot;
/** The normal receipt TTL matches a running job, but a review pause can
* live for 24h or an explicit later expiry. The store extends every
* receipt in the SAME CAS that closes running enqueues: a separate pass
@@ -116,6 +119,7 @@ export class ApprovalLifecycle {
...(discoveredTools != null && discoveredTools.length > 0
? { discoveredTools: [...discoveredTools] }
: {}),
+ ...(activityPhaseSnapshot != null ? { activityPhaseSnapshot } : {}),
},
expectCreatedAt: expectedCreatedAt,
steerReceiptTtlSeconds: pauseReceiptTtl,
diff --git a/packages/api/src/stream/GenerationJobManager.ts b/packages/api/src/stream/GenerationJobManager.ts
index c63417ae33..fb34d95a22 100644
--- a/packages/api/src/stream/GenerationJobManager.ts
+++ b/packages/api/src/stream/GenerationJobManager.ts
@@ -2380,6 +2380,7 @@ class GenerationJobManagerClass {
// Surface deferred tools discovered before the pause so the resume route can
// replay them into createRun (the rebuilt graph passes `messages: []`).
discoveredTools: jobData.discoveredTools,
+ activityPhaseSnapshot: jobData.activityPhaseSnapshot,
// Surface the owning replica's seal capability so the steer route can
// honour it instead of probing its own (possibly older) SDK.
preemptCapable: jobData.preemptCapable,
diff --git a/packages/api/src/stream/__tests__/pendingAction.spec.ts b/packages/api/src/stream/__tests__/pendingAction.spec.ts
index ba7ce549a3..189e68f68a 100644
--- a/packages/api/src/stream/__tests__/pendingAction.spec.ts
+++ b/packages/api/src/stream/__tests__/pendingAction.spec.ts
@@ -76,6 +76,37 @@ describe('ApprovalLifecycle via GenerationJobManager.approvals (in-memory)', ()
expect(paused?.metadata.discoveredTools).toEqual(['save_issue_mcp_linear']);
});
+ test('persists activity phase state in the same transition as the pause', async () => {
+ const streamId = 'stream-pause-activity-phase';
+ await manager.createJob(streamId, 'user-1');
+ const activityPhaseSnapshot = {
+ version: 1 as const,
+ generated: 0,
+ activityCount: 1,
+ failedActivityCount: 0,
+ partialActivityCount: 0,
+ agentIds: [],
+ activities: [
+ {
+ label: 'Inspected the deployment',
+ status: 'success' as const,
+ startIndex: 0,
+ },
+ ],
+ assistantContext: ['Checking the remaining replicas'],
+ pendingReasoning: [],
+ };
+
+ expect(
+ await manager.approvals.pause(streamId, buildAction(streamId), {
+ activityPhaseSnapshot,
+ }),
+ ).toBe(true);
+
+ const paused = await manager.getJob(streamId);
+ expect(paused?.metadata.activityPhaseSnapshot).toEqual(activityPhaseSnapshot);
+ });
+
test('does not write a stale pause or discoveries onto a replacement job', async () => {
const streamId = 'stream-pause-replaced';
const original = await manager.createJob(streamId, 'user-1');
diff --git a/packages/api/src/stream/implementations/RedisJobStore.ts b/packages/api/src/stream/implementations/RedisJobStore.ts
index bdfc0d3d8d..697e395960 100644
--- a/packages/api/src/stream/implementations/RedisJobStore.ts
+++ b/packages/api/src/stream/implementations/RedisJobStore.ts
@@ -4053,6 +4053,9 @@ export class RedisJobStore implements IJobStoreV2 {
isTemporary: data.isTemporary != null ? data.isTemporary === '1' : undefined,
// Deferred tools discovered before a HITL pause; replayed into createRun on resume.
discoveredTools: data.discoveredTools ? JSON.parse(data.discoveredTools) : undefined,
+ activityPhaseSnapshot: data.activityPhaseSnapshot
+ ? JSON.parse(data.activityPhaseSnapshot)
+ : undefined,
/** The owning replica's seal capability. `serializeJob` writes every
* boolean generically, but this mapper is explicit — omitting it here
* drops the flag on every read, so the steer route would compute
diff --git a/packages/api/src/stream/interfaces/IJobStore.ts b/packages/api/src/stream/interfaces/IJobStore.ts
index 9191d8b6e2..8e97b9f562 100644
--- a/packages/api/src/stream/interfaces/IJobStore.ts
+++ b/packages/api/src/stream/interfaces/IJobStore.ts
@@ -1,5 +1,6 @@
import type { Agents, TFile, TPendingSteer } from 'librechat-data-provider';
import type { StandardGraph } from '@librechat/agents';
+import type { ActivityPhaseSnapshot } from '~/agents/activityPhases/runtime';
import type { RecoveredSteerPayload } from '../SteerRecovery';
/**
@@ -89,6 +90,8 @@ export interface SerializableJobData {
* the discovered tool schemas.
*/
discoveredTools?: string[];
+ /** Bounded collector state for continuing a phase across HITL resume. */
+ activityPhaseSnapshot?: ActivityPhaseSnapshot;
/**
* Whether the replica that OWNS this generation can seal mid-stream
* (`PreemptBoundary` wiring). Recorded at createJob because the steer route
@@ -257,6 +260,7 @@ export type JobMetadataPatch = Partial<
| 'isTemporary'
| 'promptTokens'
| 'discoveredTools'
+ | 'activityPhaseSnapshot'
| 'preemptCapable'
| 'generationProtocolVersion'
>
diff --git a/packages/api/src/stream/metadata.ts b/packages/api/src/stream/metadata.ts
index 9524c67ab2..1a4b2e3376 100644
--- a/packages/api/src/stream/metadata.ts
+++ b/packages/api/src/stream/metadata.ts
@@ -42,5 +42,8 @@ export function sanitizeJobMetadata(metadata: Partial<GenerationJobMetadata>): J
if (metadata.discoveredTools) {
patch.discoveredTools = metadata.discoveredTools;
}
+ if (metadata.activityPhaseSnapshot) {
+ patch.activityPhaseSnapshot = metadata.activityPhaseSnapshot;
+ }
return patch;
}
diff --git a/packages/api/src/types/stream.ts b/packages/api/src/types/stream.ts
index 06ba894cc8..53ece61d18 100644
--- a/packages/api/src/types/stream.ts
+++ b/packages/api/src/types/stream.ts
@@ -1,5 +1,6 @@
import type { Agents } from 'librechat-data-provider';
import type { EventEmitter } from 'events';
+import type { ActivityPhaseSnapshot } from '~/agents/activityPhases/runtime';
import type { ServerSentEvent } from './events';
export interface GenerationJobMetadata {
@@ -35,6 +36,8 @@ export interface GenerationJobMetadata {
* without them the rebuilt model would lose the discovered tool schemas.
*/
discoveredTools?: string[];
+ /** Bounded collector state for continuing a phase across HITL resume. */
+ activityPhaseSnapshot?: ActivityPhaseSnapshot;
/** See `SerializableJobData.preemptCapable`. */
preemptCapable?: boolean;
/** Terminal close has atomically stopped new steer acceptance, even if the
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index ce1fcbf11d..5da9c8ca89 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -677,6 +677,16 @@ export const baseEndpointSchema = z.object({
activityMaxPerRun: z.number().int().positive().optional(),
/** Per-entry truncation of tool input/output in the label prompt. Default 600. */
activityCharLimit: z.number().int().positive().optional(),
+ /** Generates one parent summary for each run phase containing 2+ activities. */
+ activityPhaseLabel: z.boolean().optional(),
+ /** Model used for phase summaries. Defaults to activityModel, titleModel, then the run model. */
+ activityPhaseModel: z.string().optional(),
+ /** Endpoint whose credentials the phase summary model uses. Defaults to activityEndpoint. */
+ activityPhaseEndpoint: z.string().optional(),
+ /** Overrides the dedicated phase-summary system prompt. */
+ activityPhasePrompt: z.string().optional(),
+ /** Cost cap: maximum phase summaries generated per run. Default 5. */
+ activityPhaseMaxPerRun: z.number().int().positive().optional(),
/** Maximum characters allowed in a single tool result before truncation. */
maxToolResultChars: z.number().positive().optional(),
});
@@ -1122,6 +1132,11 @@ export const azureEndpointSchema = z
activityPrompt: true,
activityMaxPerRun: true,
activityCharLimit: true,
+ activityPhaseLabel: true,
+ activityPhaseModel: true,
+ activityPhaseEndpoint: true,
+ activityPhasePrompt: true,
+ activityPhaseMaxPerRun: true,
})
.partial(),
);
diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.ts
index 3851b00509..1543c6cdfe 100644
--- a/packages/data-provider/src/types/agents.ts
+++ b/packages/data-provider/src/types/agents.ts
@@ -285,6 +285,9 @@ export namespace Agents {
type: StepTypes.MESSAGE_CREATION;
message_creation: {
message_id: string;
+ /** Provider content kind and Open Responses semantic text channel. */
+ content_type?: 'text' | 'think';
+ phase?: 'commentary' | 'final_answer';
};
};
export type ToolCallsDetails = {
diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.ts
index a634358a8d..c616d9dc11 100644
--- a/packages/data-provider/src/types/assistants.ts
+++ b/packages/data-provider/src/types/assistants.ts
@@ -636,6 +636,8 @@ export type TMessageContentParts =
type: ContentTypes.TEXT;
text?: string | TextData;
tool_call_ids?: string[];
+ /** Open Responses semantic channel for assistant text. */
+ phase?: 'commentary' | 'final_answer';
} & ContentMetadata)
| ({
type: ContentTypes.TOOL_CALL;
@@ -655,7 +657,13 @@ export type TMessageContentParts =
* never sent to the model (stripped before payload formatting). */
type: ContentTypes.ACTIVITY_LABEL;
activity_label?: string;
+ /** Missing means the legacy/per-batch activity label. */
+ activity_label_type?: 'phase';
tool_call_ids?: string[];
+ /** Parent phase bounds and telemetry. */
+ activity_start_index?: number;
+ activity_count?: number;
+ agent_ids?: string[];
/** ok = all tools succeeded, failed = all failed, partial = mixed. */
status?: 'ok' | 'partial' | 'failed';
pending?: boolean;
diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.ts
index e8a8bbe334..8ef436201c 100644
--- a/packages/data-provider/src/types/runs.ts
+++ b/packages/data-provider/src/types/runs.ts
@@ -83,9 +83,9 @@ export enum SteerEvents {
/**
* Activity-label event names. `on_activity_label` streams to live clients
- * when a tool-batch label part is claimed (deterministic counts) and again
- * when the fast-model label resolves; reconnecting clients recover applied
- * labels from `aggregatedContent` like any other content part.
+ * when a tool-batch or parent-phase label part is claimed and again when the
+ * fast-model label resolves; reconnecting clients recover applied labels
+ * from `aggregatedContent` like any other content part.
*/
export enum ActivityLabelEvents {
ON_ACTIVITY_LABEL = 'on_activity_label',
@@ -98,7 +98,12 @@ export type TActivityLabelEvent = {
part: {
type: ContentTypes.ACTIVITY_LABEL;
[ContentTypes.ACTIVITY_LABEL]: string;
+ /** Missing means a per-batch activity label. */
+ activity_label_type?: 'phase';
tool_call_ids?: string[];
+ activity_start_index?: number;
+ activity_count?: number;
+ agent_ids?: string[];
counts?: {
searches: number;
reads: number;
@@ -230,8 +235,8 @@ export type TTokenUsageEvent = {
/** Non-primary buckets fold into session cost/totals but not the live
* context gauge: hidden sequential-agent calls (`sequential`), summary
* passes (`summarization`), isolated subagent runs (`subagent`), and
- * fast-model activity headers (`activity-label`) */
- usage_type?: 'summarization' | 'subagent' | 'sequential' | 'activity-label';
+ * fast-model activity headers (`activity-label`, `activity-phase`) */
+ usage_type?: 'summarization' | 'subagent' | 'sequential' | 'activity-label' | 'activity-phase';
runId?: string;
/** Per-run emission sequence; keeps identical payloads from distinct model calls unique */
seq?: number;