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

🧷 fix: Keep a Failed Summary From Bounding the Conversation History (#15913)

Marco Berettab204216c640d
diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.js
index 248f336a22..5ec6e7db96 100644
--- a/api/app/clients/BaseClient.js
+++ b/api/app/clients/BaseClient.js
@@ -21,6 +21,8 @@ const {
projectModelBoundSourceFiles,
isModelBoundAttachmentFile,
withBalanceReservations,
+ findCheckpointSummaryPart,
+ getSummaryPartText,
} = require('@librechat/api');
const {
Constants,
@@ -1266,11 +1268,11 @@ class BaseClient {
continue;
}
- const summaryBlock = BaseClient.findSummaryContentBlock(msg);
+ const summaryBlock = findCheckpointSummaryPart(msg.content);
if (summaryBlock) {
this.previous_summary = {
...msg,
- summary: BaseClient.getSummaryText(summaryBlock),
+ summary: getSummaryPartText(summaryBlock),
summaryTokenCount: summaryBlock.tokenCount,
};
break;
@@ -1434,34 +1436,6 @@ class BaseClient {
await db.updateMessage(this.options?.req?.user?.id, message);
}
- /** Extracts text from a summary block (handles both legacy `text` field and new `content` array format). */
- static getSummaryText(summaryBlock) {
- if (Array.isArray(summaryBlock.content)) {
- return summaryBlock.content.map((b) => b.text ?? '').join('');
- }
- if (typeof summaryBlock.content === 'string') {
- return summaryBlock.content;
- }
- return summaryBlock.text ?? '';
- }
-
- /** Finds the last summary content block in a message's content array (last-summary-wins). */
- static findSummaryContentBlock(message) {
- if (!Array.isArray(message?.content)) {
- return null;
- }
- let lastSummary = null;
- for (const part of message.content) {
- if (
- part?.type === ContentTypes.SUMMARY &&
- BaseClient.getSummaryText(part).trim().length > 0
- ) {
- lastSummary = part;
- }
- }
- return lastSummary;
- }
-
/**
* Iterate through messages, building an array based on the parentMessageId.
*
@@ -1523,9 +1497,9 @@ class BaseClient {
let resolved = message;
let hasSummary = false;
if (summary) {
- const summaryBlock = BaseClient.findSummaryContentBlock(message);
+ const summaryBlock = findCheckpointSummaryPart(message.content);
if (summaryBlock) {
- const summaryText = BaseClient.getSummaryText(summaryBlock);
+ const summaryText = getSummaryPartText(summaryBlock);
resolved = {
...message,
role: 'system',
diff --git a/api/app/clients/specs/BaseClient.test.js b/api/app/clients/specs/BaseClient.test.js
index 3aa013cc8e..26d8f3ccfb 100644
--- a/api/app/clients/specs/BaseClient.test.js
+++ b/api/app/clients/specs/BaseClient.test.js
@@ -590,47 +590,29 @@ describe('BaseClient', () => {
expect(result[0].content).toEqual([{ type: 'text', text: 'Legacy summary only' }]);
expect(result[0].tokenCount).toBe(15);
});
- });
-
- describe('findSummaryContentBlock', () => {
- it('should find a summary block in the content array', () => {
- const message = {
- content: [
- { type: 'text', text: 'some text' },
- { type: 'summary', text: 'Summary of conversation', tokenCount: 50 },
- ],
- };
- const result = TestClient.constructor.findSummaryContentBlock(message);
- expect(result).toBeTruthy();
- expect(result.text).toBe('Summary of conversation');
- expect(result.tokenCount).toBe(50);
- });
-
- it('should return null when no summary block exists', () => {
- const message = {
- content: [
- { type: 'text', text: 'some text' },
- { type: 'tool_call', tool_call: {} },
- ],
- };
- expect(TestClient.constructor.findSummaryContentBlock(message)).toBeNull();
- });
-
- it('should return null for string content', () => {
- const message = { content: 'just a string' };
- expect(TestClient.constructor.findSummaryContentBlock(message)).toBeNull();
- });
-
- it('should return null for missing content', () => {
- expect(TestClient.constructor.findSummaryContentBlock({})).toBeNull();
- expect(TestClient.constructor.findSummaryContentBlock(null)).toBeNull();
- });
- it('should skip summary blocks with no text', () => {
- const message = {
- content: [{ type: 'summary', tokenCount: 10 }],
- };
- expect(TestClient.constructor.findSummaryContentBlock(message)).toBeNull();
+ it('should not stop traversal at a failed summary, keeping the prior history', () => {
+ /** A summarize round that errored keeps the deltas it streamed, so its
+ * text is a truncated prefix; treating it as the checkpoint would send
+ * it in place of the history it never finished summarizing. */
+ const messagesWithFailedSummary = [
+ { id: '1', parentMessageId: null, text: 'Message 1' },
+ { id: '2', parentMessageId: '1', text: 'Message 2' },
+ {
+ id: '3',
+ parentMessageId: '2',
+ text: '',
+ content: [{ type: 'summary', text: 'Partial sum', tokenCount: 5, failed: true }],
+ },
+ { id: '4', parentMessageId: '3', text: 'Message 4' },
+ ];
+ const result = TestClient.constructor.getMessagesForConversation({
+ messages: messagesWithFailedSummary,
+ parentMessageId: '4',
+ summary: true,
+ });
+ expect(result.map((message) => message.id)).toEqual(['1', '2', '3', '4']);
+ expect(result.every((message) => message.role !== 'system')).toBe(true);
});
});
@@ -3664,6 +3646,7 @@ describe('BaseClient compaction turns', () => {
{
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'checkpoint' }],
+ boundary: { messageId: 'step_summary', contentIndex: 0 },
},
],
},
diff --git a/api/server/controllers/agents/__tests__/responses.unit.spec.js b/api/server/controllers/agents/__tests__/responses.unit.spec.js
index 6f8372072b..b31227f810 100644
--- a/api/server/controllers/agents/__tests__/responses.unit.spec.js
+++ b/api/server/controllers/agents/__tests__/responses.unit.spec.js
@@ -212,6 +212,9 @@ jest.mock('@librechat/api', () => ({
* before SDK formatting; the mock must expose it like any other used
* export or the call throws before the assertions run. */
stripActivityLabelParts: jest.fn((payload) => payload),
+ /** Pass-through by default; the history-strip test swaps in its own result
+ * to prove the formatter receives what this returns. */
+ stripUnusableSummaryParts: jest.fn((payload) => payload),
createOwnedToolEndHandler: jest.fn(
(...args) => new (require('@librechat/agents').ToolEndHandler)(...args),
),
@@ -630,6 +633,42 @@ describe('createResponse controller', () => {
},
);
+ /** The SDK formatter takes the last summary part carrying text as the history
+ * boundary, so a stored summary whose round failed would replace the turns it
+ * never finished summarizing. The formatter must see the stripped history. */
+ it('formats continued history only after unusable summaries are stripped', async () => {
+ const api = require('@librechat/api');
+ const db = require('~/models');
+ const { formatAgentMessages } = require('@librechat/agents');
+ const storedContent = [
+ { type: 'text', text: 'Earlier answer' },
+ { type: 'summary', content: [{ type: 'text', text: 'Partial summ' }], failed: true },
+ ];
+ const stripped = [{ role: 'assistant', content: [{ type: 'text', text: 'Earlier answer' }] }];
+ api.validateResponseRequest.mockReturnValueOnce({
+ request: {
+ model: 'agent-123',
+ input: 'Hello',
+ stream: false,
+ previous_response_id: 'previous',
+ },
+ });
+ db.getConvo.mockResolvedValueOnce({ conversationId: 'previous', user: 'user-123' });
+ db.getMessages.mockResolvedValueOnce([
+ { messageId: 'stored-assistant', isCreatedByUser: false, content: storedContent },
+ ]);
+ api.stripUnusableSummaryParts.mockReturnValueOnce(stripped);
+
+ await createResponse(req, res);
+
+ expect(api.stripUnusableSummaryParts).toHaveBeenCalledWith(
+ expect.arrayContaining([
+ expect.objectContaining({ messageId: 'stored-assistant', content: storedContent }),
+ ]),
+ );
+ expect(formatAgentMessages).toHaveBeenCalledWith(stripped, {}, expect.anything());
+ });
+
it.each([false, true])(
'persists the normalized no-attached decision atomically: stream=%s',
async (stream) => {
diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js
index d491d259fe..4ae39e90a1 100644
--- a/api/server/controllers/agents/client.js
+++ b/api/server/controllers/agents/client.js
@@ -1,9 +1,5 @@
require('events').EventEmitter.defaultMaxListeners = 100;
-const {
- logger,
- MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH,
- MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH,
-} = require('@librechat/data-schemas');
+const { logger, MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH } = require('@librechat/data-schemas');
const { getBufferString, HumanMessage } = require('@librechat/agents/langchain/messages');
const {
createRun,
@@ -109,6 +105,11 @@ const {
traceIdForMessage,
settlePendingLabelFills,
stripActivityLabelParts,
+ stripUnusableSummaryParts,
+ dropUnusableSummaryParts,
+ getLatestEventActorSummary,
+ createAgentEventActorSummary,
+ normalizeAgentEventActorSummary,
getRequestMemories,
getMemoryAgentId,
createMemoryProcessor,
@@ -174,7 +175,6 @@ const {
resolveToolRoleGrants,
createTerminalRunErrorObserver,
isAgentRunCancellation,
- getSummaryPartText,
markCompactionOutcome,
resolvePersistableCodeEnvironmentDecision,
} = require('@librechat/api');
@@ -227,22 +227,6 @@ const loadAgent = (params) =>
const MEMORY_INPUT_CHARS_PER_TOKEN = 8;
-function normalizeEventActorSummary(summary) {
- if (summary == null) {
- return undefined;
- }
- if (
- typeof summary.text !== 'string' ||
- summary.text.length === 0 ||
- summary.text.length > MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH ||
- !Number.isFinite(summary.tokenCount) ||
- summary.tokenCount < 0
- ) {
- throw new RangeError('Event actor summary state is invalid');
- }
- return { text: summary.text, tokenCount: summary.tokenCount };
-}
-
function normalizeEventActorContextMeta(contextMeta) {
if (contextMeta == null) {
return undefined;
@@ -337,24 +321,6 @@ function captureRunContextMeta(client) {
});
}
-function getLatestEventActorSummary(contentParts) {
- if (!Array.isArray(contentParts)) {
- return undefined;
- }
- for (let index = contentParts.length - 1; index >= 0; index -= 1) {
- const part = contentParts[index];
- const text = getSummaryPartText(part);
- if (text.length === 0) {
- continue;
- }
- return normalizeEventActorSummary({
- text,
- tokenCount: Number.isFinite(part.tokenCount) && part.tokenCount >= 0 ? part.tokenCount : 0,
- });
- }
- return undefined;
-}
-
/**
* User-visible text for a failed run. LangChain classifies provider errors by mutating
* `error.message` with a docs URL, so a classified failure becomes typed copy the client localizes
@@ -2117,7 +2083,7 @@ class AgentClient extends BaseClient {
let compactionSemanticIndex;
try {
discoveredToolNames = normalizeAgentEventActorDiscoveredTools(state.discoveredToolNames);
- summary = normalizeEventActorSummary(state.summary);
+ summary = normalizeAgentEventActorSummary(state.summary);
contextMeta = normalizeEventActorContextMeta(state.contextMeta);
compactionSemanticIndex = restoreCompactionSemanticIndexSnapshot(
state.compactionSemanticIndex,
@@ -2206,7 +2172,13 @@ class AgentClient extends BaseClient {
(this.eventActorContinuation === 'warm' ? (this.eventActorDiscoveredToolNames ?? []) : [])),
...(this.run == null ? [] : getRunDiscoveredTools(this.run)),
]);
- const summary = getLatestEventActorSummary(this.contentParts) ?? this.eventActorSummary;
+ /** Stamped where state is assembled, not where each source is read: a
+ * summary inherited from the formatter arrives in the SDK's
+ * `{ text, tokenCount }` shape, and persisting it unstamped would have the
+ * next event refuse its own state and reload the whole history. */
+ const summary = createAgentEventActorSummary(
+ getLatestEventActorSummary(this.contentParts) ?? this.eventActorSummary,
+ );
this.eventActorSummary = summary;
const compactionSemanticIndex = createCompactionSemanticIndexProjection(
this.compactionSemanticIndexSnapshot,
@@ -2590,6 +2562,17 @@ class AgentClient extends BaseClient {
const turnFiles = this.message_file_map?.[message.messageId] ?? message.files;
applyAttachmentOnlyText(formattedMessage, turnFiles);
+ /**
+ * A summarize round that errored or was cut off never reaches the model:
+ * the formatter would take its partial text as the history boundary and
+ * drop everything older. Dropped from the prompt copy here, ahead of the
+ * counts, so the per-index count, the prompt total admission checks, and
+ * the steer-media adjustments below all describe what is actually sent.
+ * The stored message keeps the part — the renderer labels it — so a
+ * canonical recount reads an unstripped surface instead.
+ */
+ const droppedPromptSummary = dropUnusableSummaryParts(formattedMessage);
+
const dbTokenCount = Number(orderedMessages[i].tokenCount);
const hasDbTokenCount = Number.isFinite(dbTokenCount) && dbTokenCount > 0;
/**
@@ -2607,19 +2590,21 @@ class AgentClient extends BaseClient {
let canonicalTokenCount = hasDbTokenCount ? dbTokenCount : 0;
if (needsCanonicalTokenCount) {
/** Without fileContext the memory copy is content-identical to the
- * prompt copy, so the prompt copy is the counting surface; with it,
- * the canonical count must exclude the prepended context. */
+ * prompt copy, so the prompt copy is the counting surface; with it (or
+ * with a dropped summary), the canonical count must be taken from the
+ * message as stored. */
let countSurface = formattedMessage;
- if (message.fileContext) {
+ if (message.fileContext || droppedPromptSummary) {
memoryFormattedMessages[i] = buildMemoryFormattedMessage(message);
countSurface = memoryFormattedMessages[i];
}
canonicalTokenCount = countFormattedMessageTokens(countSurface, encoding);
}
- const promptMessageTokenCount = message.fileContext
- ? countFormattedMessageTokens(formattedMessage, encoding)
- : canonicalTokenCount;
+ const promptMessageTokenCount =
+ message.fileContext || droppedPromptSummary
+ ? countFormattedMessageTokens(formattedMessage, encoding)
+ : canonicalTokenCount;
/* If message has files, calculate image token cost */
if (this.message_file_map && this.message_file_map[message.messageId]) {
@@ -4620,6 +4605,10 @@ class AgentClient extends BaseClient {
intentToolNames: semanticIntentToolNames,
},
};
+ /** The payload reached here already free of unusable summary parts:
+ * `buildMessages` drops them from each prompt copy before counting it,
+ * so the formatter's summary scan cannot take a failed round's prefix as
+ * the history boundary and every count describes what is sent. */
let {
messages: initialMessages,
indexTokenCountMap,
@@ -4719,7 +4708,7 @@ class AgentClient extends BaseClient {
const memoryMessages =
this.processMemory && this.memoryPayload && !isCompactionTurn
? formatAgentMessages(
- stripActivityLabelParts(this.memoryPayload),
+ stripUnusableSummaryParts(stripActivityLabelParts(this.memoryPayload)),
undefined,
toolSet,
skillPrimeResult?.skills,
diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.js
index 1b0aa9c33c..7a986a19cf 100644
--- a/api/server/controllers/agents/client.test.js
+++ b/api/server/controllers/agents/client.test.js
@@ -289,7 +289,7 @@ describe('AgentClient - event actor history adapter', () => {
contextFingerprint: fingerprint,
skillManifest,
discoveredToolNames: ['deferred_tool'],
- summary: { text: 'Earlier compacted context.', tokenCount: 12 },
+ summary: { text: 'Earlier compacted context.', tokenCount: 12, version: 1 },
contextMeta: { calibrationRatio: 1.25, encoding: 'o200k_base' },
compactionSemanticIndex,
}),
@@ -320,6 +320,7 @@ describe('AgentClient - event actor history adapter', () => {
expect(client.eventActorSummary).toEqual({
text: 'Earlier compacted context.',
tokenCount: 12,
+ version: 1,
});
expect(client.contextMeta).toEqual({ calibrationRatio: 1.25, encoding: 'o200k_base' });
expect(client.compactionSemanticIndexSnapshot).toEqual({
@@ -436,6 +437,7 @@ describe('AgentClient - event actor history adapter', () => {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Fresh compacted context.' }],
tokenCount: 18,
+ boundary: { messageId: 'step_summary', contentIndex: 0 },
},
];
client.contextMeta = { calibrationRatio: 1.3, encoding: 'o200k_base' };
@@ -3502,6 +3504,7 @@ describe('AgentClient - startup telemetry', () => {
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'Fresh compacted context.' }],
tokenCount: 18,
+ boundary: { messageId: 'step_summary', contentIndex: 0 },
},
{ type: ContentTypes.TEXT, text: 'Done.' },
);
@@ -3607,6 +3610,7 @@ describe('AgentClient - startup telemetry', () => {
expect(client.eventActorSummary).toEqual({
text: 'Fresh compacted context.',
tokenCount: 18,
+ version: 1,
});
expect(client.contentParts).not.toEqual(
expect.arrayContaining([expect.objectContaining({ type: ContentTypes.SUMMARY })]),
diff --git a/api/server/controllers/agents/responses.js b/api/server/controllers/agents/responses.js
index 8d8612238a..839c5a8a8f 100644
--- a/api/server/controllers/agents/responses.js
+++ b/api/server/controllers/agents/responses.js
@@ -78,6 +78,7 @@ const {
createAggregatorEventHandlers,
getLangfuseTraceMessageFields,
stripActivityLabelParts,
+ stripUnusableSummaryParts,
CHILD_THREAD_READ_ONLY_ERROR,
executeAgentRun,
waitForAgentExecutionWrites,
@@ -1088,7 +1089,11 @@ const executeResponse = async (envelope, { req, res }) => {
allMessages,
true,
);
- const formatted = formatAgentMessages(stripActivityLabelParts(allMessages), {}, toolSet);
+ const formatted = formatAgentMessages(
+ stripUnusableSummaryParts(stripActivityLabelParts(allMessages)),
+ {},
+ toolSet,
+ );
const formattedMessages = formatted.messages;
const initialSummary = formatted.summary;
let indexTokenCountMap = formatted.indexTokenCountMap;
diff --git a/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx b/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
index 939b820505..72d74da27b 100644
--- a/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
+++ b/client/src/hooks/Chat/__tests__/useCompactConversation.spec.tsx
@@ -25,6 +25,7 @@ const summaryPart = (overrides: Record<string, unknown> = {}): ContentPart =>
({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'checkpoint' }],
+ boundary: { messageId: 'step_summary', contentIndex: 0 },
...overrides,
}) as ContentPart;
@@ -110,6 +111,7 @@ describe('useCompactConversation', () => {
it.each([
['still streaming', summaryPart({ summarizing: true })],
['failed', summaryPart({ failed: true })],
+ ['stored without a boundary', summaryPart({ boundary: undefined })],
])('lets an interrupted compaction (summary %s) be retried', (_label, part) => {
mockLatestMessage = leaf({ text: '', content: [part] });
const { result } = renderHook(() => useCompactConversation());
diff --git a/e2e/setup/fake-model.js b/e2e/setup/fake-model.js
index 33df00e837..0545b42ce9 100644
--- a/e2e/setup/fake-model.js
+++ b/e2e/setup/fake-model.js
@@ -32,6 +32,7 @@ const ASSERT_MANUAL_SKILL_MARKER = 'E2E_ASSERT_MANUAL_SKILL:';
const INVOKE_SKILL_MARKER = 'E2E_INVOKE_SKILL:';
const ASSERT_PROVIDER_FILE_MARKER = 'E2E_ASSERT_PROVIDER_FILE:';
const ASSERT_AGENT_CONTEXT_MARKER = 'E2E_ASSERT_AGENT_CONTEXT:';
+const ASSERT_HISTORY_MARKER = 'E2E_ASSERT_HISTORY:';
const ASSERT_QUOTE_MARKER = 'E2E_ASSERT_QUOTE:';
const REPLY_MARKER = 'E2E_REPLY:';
const THINK_REPLY_MARKER = 'E2E_THINK_REPLY:';
@@ -86,6 +87,8 @@ const MANUAL_SKILL_ASSERTION_FINAL_TEXT = 'E2E manual skill assertion passed';
const SKILL_TOOL_ASSERTION_FINAL_TEXT = 'E2E skill tool assertion passed';
const PROVIDER_FILE_ASSERTION_FINAL_TEXT = 'E2E provider file assertion passed';
const AGENT_CONTEXT_ASSERTION_FINAL_TEXT = 'E2E agent context assertion passed';
+const HISTORY_ASSERTION_PRESENT_TEXT = 'E2E history assertion present';
+const HISTORY_ASSERTION_ABSENT_TEXT = 'E2E history assertion absent';
const QUOTE_ASSERTION_FINAL_TEXT = 'E2E quote assertion passed';
const STEER_TOOL_FINAL_TEXT = 'E2E steer tool reply done';
const STEER_SPLIT_FINAL_TEXT = 'E2E steer split reply done';
@@ -405,6 +408,32 @@ function agentContextAssertionResponses({ messages, text }) {
};
}
+/**
+ * Answers whether a token from an EARLIER turn still reaches the model. Scans
+ * every prompt message except the current user turn: the marker line carries
+ * the token itself, so counting that turn would make every history pass.
+ * Presence and absence each get their own sentinel, so a spec asserts what the
+ * model saw rather than matching a failure string — a conversation whose
+ * history was replaced by a checkpoint is a correct absence.
+ */
+function historyAssertionResponses({ messages, text }) {
+ const expected = getMarkerValue(text, ASSERT_HISTORY_MARKER);
+ if (!expected) {
+ return null;
+ }
+
+ const latestUserMessage = getLatestUserMessage(messages);
+ const priorMessages = (messages ?? []).filter((message) => message !== latestUserMessage);
+ const priorText = collectPromptText(priorMessages).join('\n');
+ return {
+ responses: [
+ priorText.includes(expected)
+ ? `${HISTORY_ASSERTION_PRESENT_TEXT}: ${expected}`
+ : `${HISTORY_ASSERTION_ABSENT_TEXT}: ${expected}`,
+ ],
+ };
+}
+
/**
* Verifies the quote feature end to end: scans every user message in the prompt
* the model actually received for a Markdown blockquote line containing the
@@ -2821,6 +2850,14 @@ function resolveResponses({ graph, messages, text, toolNames }) {
};
}
+ if (text.includes(ASSERT_HISTORY_MARKER)) {
+ return {
+ responses: [MOCK_REPLY],
+ resolveOnStream: (streamMessages) =>
+ historyAssertionResponses({ messages: streamMessages, text }),
+ };
+ }
+
const providerFileAssertion = providerFileAssertionResponses({ messages, text });
if (providerFileAssertion) {
return providerFileAssertion;
diff --git a/e2e/specs/mock/scenarios/failed-summary-history.spec.ts b/e2e/specs/mock/scenarios/failed-summary-history.spec.ts
new file mode 100644
index 0000000000..50765dac37
--- /dev/null
+++ b/e2e/specs/mock/scenarios/failed-summary-history.spec.ts
@@ -0,0 +1,173 @@
+import { expect, test } from '@playwright/test';
+import { randomUUID } from 'node:crypto';
+import type { Page } from '@playwright/test';
+import { deleteConversations, deleteMessagesByConversation, withMongo } from '../db';
+import { messagesView, sendMessageAndWaitForCompletion } from '../helpers';
+
+const summaryPart = (text: string, extra: Record<string, unknown> = {}) => ({
+ type: 'summary',
+ content: [{ type: 'text', text }],
+ tokenCount: 6,
+ ...extra,
+});
+
+/** Only a completed round's final summary block carries a boundary; the deltas a
+ * failed or interrupted round leaves behind never do. */
+const completedBoundary = { messageId: 'step_summary', contentIndex: 0 };
+
+/** A real turn carrying a passphrase only this conversation's history holds. */
+async function startConversation(page: Page) {
+ const token = `OLDFACT-${randomUUID().slice(0, 8)}`;
+ await page.goto('/c/new');
+ await sendMessageAndWaitForCompletion(page, `Remember this passphrase: ${token}`);
+ const conversationId = new URL(page.url()).pathname.replace('/c/', '');
+ expect(conversationId).not.toBe('new');
+ return { conversationId, token };
+}
+
+/**
+ * Appends a turn whose only content is a summary part, cloning the endpoint and
+ * model of the turn it hangs off. A summarize round that streamed deltas and
+ * then errored cannot be produced through the composer, and the behavior under
+ * test is what the *next* turn sends once such a turn is persisted.
+ */
+async function appendSummaryTurn(conversationId: string, part: Record<string, unknown>) {
+ await withMongo(async (db) => {
+ const rows = await db
+ .collection('messages')
+ .find({ conversationId })
+ .sort({ createdAt: 1 })
+ .toArray();
+ const leaf = rows[rows.length - 1];
+ if (!leaf) {
+ throw new Error(`E2E seed: conversation ${conversationId} has no messages`);
+ }
+ /** Mongo assigns the new row its own `_id`; everything else (endpoint,
+ * model, user, conversation) is cloned from the turn it hangs off. */
+ const fields = { ...leaf };
+ delete fields._id;
+ const now = new Date();
+ await db.collection('messages').insertOne({
+ ...fields,
+ messageId: randomUUID(),
+ parentMessageId: leaf.messageId,
+ isCreatedByUser: false,
+ text: '',
+ content: [part],
+ createdAt: now,
+ updatedAt: now,
+ });
+ });
+}
+
+test.describe('failed summary history', () => {
+ const conversationIds: string[] = [];
+
+ test.afterEach(async () => {
+ const ids = conversationIds.splice(0);
+ if (ids.length === 0) {
+ return;
+ }
+ try {
+ await deleteMessagesByConversation(ids);
+ } finally {
+ await deleteConversations(ids);
+ }
+ });
+
+ /**
+ * A summarize round that errored keeps the deltas it streamed and is stamped
+ * `failed: true`. Taking that prefix as the conversation's history boundary
+ * drops every turn it never summarized, so the passphrase from the opening
+ * turn has to still reach the model on the turn after it.
+ */
+ test('a turn after a failed summarization still sends the earlier history @scenario:failed-summary-keeps-prior-history', async ({
+ page,
+ }) => {
+ const { conversationId, token } = await startConversation(page);
+ conversationIds.push(conversationId);
+ await appendSummaryTurn(
+ conversationId,
+ summaryPart('Partial summary of the conve', { failed: true }),
+ );
+
+ await page.goto(`/c/${conversationId}`);
+ await expect(messagesView(page).getByText(token)).toBeVisible();
+ await sendMessageAndWaitForCompletion(page, `E2E_ASSERT_HISTORY:${token}`);
+
+ await expect(
+ messagesView(page).getByText(`E2E history assertion present: ${token}`),
+ ).toBeVisible({ timeout: 30000 });
+ });
+
+ /**
+ * The same rule for a round that never reported at all: the part is left
+ * mid-stream (`summarizing: true`) with whatever text it produced, which is
+ * no more a checkpoint than an errored round's prefix.
+ */
+ test('a turn after an interrupted summarization still sends the earlier history @scenario:unfinished-summary-keeps-prior-history', async ({
+ page,
+ }) => {
+ const { conversationId, token } = await startConversation(page);
+ conversationIds.push(conversationId);
+ await appendSummaryTurn(
+ conversationId,
+ summaryPart('Partial summary of the conve', { summarizing: true }),
+ );
+
+ await page.goto(`/c/${conversationId}`);
+ await expect(messagesView(page).getByText(token)).toBeVisible();
+ await sendMessageAndWaitForCompletion(page, `E2E_ASSERT_HISTORY:${token}`);
+
+ await expect(
+ messagesView(page).getByText(`E2E history assertion present: ${token}`),
+ ).toBeVisible({ timeout: 30000 });
+ });
+
+ /**
+ * The other half of the same invariant: a summary that completed is still the
+ * conversation's checkpoint, so the turns it covers are replaced by it and
+ * the passphrase no longer reaches the model.
+ */
+ /**
+ * Errored rounds were only stamped `failed` from #14546 on. One stored
+ * earlier kept its streamed deltas with no flag at all, so the only record that
+ * it never finished is the boundary a completed block would have written.
+ */
+ test('a turn after a summarization stored without a boundary still sends the earlier history @scenario:unstamped-summary-keeps-prior-history', async ({
+ page,
+ }) => {
+ const { conversationId, token } = await startConversation(page);
+ conversationIds.push(conversationId);
+ await appendSummaryTurn(conversationId, summaryPart('Partial summary of the conve'));
+
+ await page.goto(`/c/${conversationId}`);
+ await expect(messagesView(page).getByText(token)).toBeVisible();
+ await sendMessageAndWaitForCompletion(page, `E2E_ASSERT_HISTORY:${token}`);
+
+ await expect(
+ messagesView(page).getByText(`E2E history assertion present: ${token}`),
+ ).toBeVisible({ timeout: 30000 });
+ });
+
+ test('a completed summary still replaces the history it covers @scenario:complete-summary-replaces-prior-history', async ({
+ page,
+ }) => {
+ const { conversationId, token } = await startConversation(page);
+ conversationIds.push(conversationId);
+ await appendSummaryTurn(
+ conversationId,
+ summaryPart('The user shared a passphrase and it was acknowledged.', {
+ boundary: completedBoundary,
+ }),
+ );
+
+ await page.goto(`/c/${conversationId}`);
+ await expect(messagesView(page).getByText(token)).toBeVisible();
+ await sendMessageAndWaitForCompletion(page, `E2E_ASSERT_HISTORY:${token}`);
+
+ await expect(
+ messagesView(page).getByText(`E2E history assertion absent: ${token}`),
+ ).toBeVisible({ timeout: 30000 });
+ });
+});
diff --git a/packages/api/src/agents/compaction.spec.ts b/packages/api/src/agents/compaction.spec.ts
index c4cc6a94fe..e5460ca7f7 100644
--- a/packages/api/src/agents/compaction.spec.ts
+++ b/packages/api/src/agents/compaction.spec.ts
@@ -5,16 +5,22 @@ import {
MAX_COMPACTION_SEMANTIC_INDEX_IDENTITY_LENGTH,
MAX_COMPACTION_SEMANTIC_INDEX_SOURCE_CONTENT_INDEX,
MAX_COMPACTION_SEMANTIC_INDEX_TEXT_LENGTH,
+ AGENT_EVENT_ACTOR_SUMMARY_VERSION,
} from '@librechat/data-schemas';
import type { CompactionSemanticIndex, CompactionSemanticIndexSnapshot } from '@librechat/agents';
import type { SummaryContentPart, TMessageContentParts } from 'librechat-data-provider';
import type { ICompactionSemanticIndexProjection } from '@librechat/data-schemas';
import {
createCompactionSemanticIndexProjection,
+ dropUnusableSummaryParts,
+ findCheckpointSummaryPart,
+ getSummaryPartText,
markCompactionOutcome,
resolveFailedTurnContent,
restoreCompactionSemanticIndex,
restoreCompactionSemanticIndexSnapshot,
+ stripUnusableSummaryParts,
+ getLatestEventActorSummary,
} from './compaction';
const index = [
@@ -142,6 +148,9 @@ describe('compaction semantic index continuation projection', () => {
});
});
+/** Only a completed round's final block carries a boundary; streamed deltas never do. */
+const completedBoundary = { messageId: 'step_summary', contentIndex: 0 };
+
describe('markCompactionOutcome', () => {
const summary = (
text: string,
@@ -149,6 +158,7 @@ describe('markCompactionOutcome', () => {
): TMessageContentParts => ({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text }],
+ boundary: completedBoundary,
...overrides,
});
const failure = (error: string): TMessageContentParts => ({ type: ContentTypes.ERROR, error });
@@ -196,7 +206,7 @@ describe('markCompactionOutcome', () => {
markCompactionOutcome(parts);
/** The typed failure is the turn's whole outcome: a truncated summary left
- * beside it would be read back as the conversation's checkpoint. */
+ * beside it would report the same failure a second time. */
expect(parts).toEqual([
{
type: ContentTypes.ERROR,
@@ -235,3 +245,243 @@ describe('resolveFailedTurnContent', () => {
expect(resolveFailedTurnContent(requestBody, 'Something failed')).toEqual({});
});
});
+
+describe('findCheckpointSummaryPart', () => {
+ const legacySummary = { type: ContentTypes.SUMMARY, text: 'Summary of conversation' };
+
+ it('takes the last summary that carries text', () => {
+ const content = [
+ { type: ContentTypes.TEXT, text: 'some text' },
+ {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'First' }],
+ boundary: completedBoundary,
+ },
+ {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Latest' }],
+ boundary: completedBoundary,
+ },
+ ];
+
+ expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Latest');
+ });
+
+ /** Rows persisted before summary `content` blocks carry a bare `text`. */
+ it('reads a legacy summary’s text field', () => {
+ expect(findCheckpointSummaryPart([legacySummary])).toBe(legacySummary);
+ });
+
+ /** A round that failed or never finished holds a truncated prefix of the
+ * history it was summarizing, so the turn offers no checkpoint at all. */
+ it.each([
+ ['failed', { failed: true }],
+ ['still summarizing', { summarizing: true }],
+ ])('offers no checkpoint when the only summary is %s', (_label, state) => {
+ const content = [
+ {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Partial' }],
+ boundary: completedBoundary,
+ ...state,
+ },
+ ];
+
+ expect(findCheckpointSummaryPart(content)).toBeNull();
+ });
+
+ /** A round that errored before failures were stamped kept its deltas and no
+ * flag. Deltas never carry a boundary, so the part still reads as unfinished. */
+ it('offers no checkpoint for a streamed summary that never recorded a boundary', () => {
+ const content = [
+ { type: ContentTypes.TEXT, text: 'An answer' },
+ { type: ContentTypes.SUMMARY, content: [{ type: ContentTypes.TEXT, text: 'Partial' }] },
+ ];
+
+ expect(findCheckpointSummaryPart(content)).toBeNull();
+ });
+
+ it('keeps the last complete summary when a later round never recorded a boundary', () => {
+ const content = [
+ {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Complete' }],
+ boundary: completedBoundary,
+ },
+ { type: ContentTypes.SUMMARY, content: [{ type: ContentTypes.TEXT, text: 'Partial' }] },
+ ];
+
+ expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Complete');
+ });
+
+ it('keeps the last complete summary when a later round failed', () => {
+ const content = [
+ {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Complete' }],
+ boundary: completedBoundary,
+ },
+ { type: ContentTypes.SUMMARY, text: 'Partial', failed: true },
+ ];
+
+ expect(getSummaryPartText(findCheckpointSummaryPart(content))).toBe('Complete');
+ });
+
+ it.each([
+ ['content without a summary', [{ type: ContentTypes.TEXT, text: 'some text' }]],
+ ['an empty summary', [{ type: ContentTypes.SUMMARY, tokenCount: 10 }]],
+ ['a whitespace-only summary', [{ type: ContentTypes.SUMMARY, text: ' \n' }]],
+ ['string content', 'just a string'],
+ ['missing content', undefined],
+ ])('returns null for %s', (_label, content) => {
+ expect(findCheckpointSummaryPart(content)).toBeNull();
+ });
+});
+
+describe('getLatestEventActorSummary', () => {
+ const part = (text: string, extra: Record<string, unknown> = {}) => ({
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text }],
+ boundary: completedBoundary,
+ ...extra,
+ });
+
+ it('stamps the last usable summary as actor state', () => {
+ expect(
+ getLatestEventActorSummary([
+ part('Earlier checkpoint', { tokenCount: 4 }),
+ { type: ContentTypes.TEXT, text: 'An answer' },
+ part('Latest checkpoint', { tokenCount: 9 }),
+ ]),
+ ).toEqual({
+ text: 'Latest checkpoint',
+ tokenCount: 9,
+ version: AGENT_EVENT_ACTOR_SUMMARY_VERSION,
+ });
+ });
+
+ /** A later round that failed, is still running, or never recorded a boundary
+ * holds a truncated prefix; the continuation must keep the real checkpoint. */
+ it.each([
+ ['failed', { failed: true }],
+ ['still summarizing', { summarizing: true }],
+ ['stored without a boundary', { boundary: undefined }],
+ ])('skips a later summary that is %s', (_label, state) => {
+ expect(
+ getLatestEventActorSummary([
+ part('Real checkpoint', { tokenCount: 5 }),
+ part('Parti', state),
+ ]),
+ ).toMatchObject({ text: 'Real checkpoint', tokenCount: 5 });
+ });
+
+ it.each([
+ ['a missing count', {}],
+ ['a negative count', { tokenCount: -3 }],
+ ['a non-finite count', { tokenCount: Number.NaN }],
+ ])('records zero tokens for %s', (_label, extra) => {
+ expect(getLatestEventActorSummary([part('Checkpoint', extra)])).toMatchObject({
+ tokenCount: 0,
+ });
+ });
+
+ it.each([
+ ['content without a usable summary', [part('Parti', { failed: true })]],
+ ['non-array content', 'just a string'],
+ ['missing content', undefined],
+ ])('returns undefined for %s', (_label, content) => {
+ expect(getLatestEventActorSummary(content)).toBeUndefined();
+ });
+});
+
+describe('unusable summary parts', () => {
+ const failedSummary = {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
+ boundary: completedBoundary,
+ failed: true,
+ };
+ const unfinishedSummary = {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
+ boundary: completedBoundary,
+ summarizing: true,
+ };
+ const unstampedSummary = {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Half a checkpoint' }],
+ };
+ const completeSummary = {
+ type: ContentTypes.SUMMARY,
+ content: [{ type: ContentTypes.TEXT, text: 'Earlier turns, compacted.' }],
+ boundary: completedBoundary,
+ };
+ const emptySummary = { type: ContentTypes.SUMMARY, content: [], failed: true };
+ const text = { type: ContentTypes.TEXT, text: 'An answer' };
+
+ /** The formatter reads the last summary part with text as the history
+ * boundary, so an unusable one left on the prompt copy drops the turns it
+ * never summarized. */
+ it.each([
+ ['a failed summary', failedSummary],
+ ['a summary whose round never finished', unfinishedSummary],
+ ['a streamed summary stored without a boundary or a flag', unstampedSummary],
+ ])('drops %s from a prompt copy and keeps the rest of the turn', (_label, summary) => {
+ const message = { role: 'assistant', content: [text, summary] };
+
+ expect(dropUnusableSummaryParts(message)).toBe(true);
+ expect(message.content).toEqual([text]);
+ });
+
+ it('keeps a complete summary, so a real checkpoint still bounds the history', () => {
+ const message = { role: 'assistant', content: [completeSummary, failedSummary] };
+
+ expect(dropUnusableSummaryParts(message)).toBe(true);
+ expect(message.content).toEqual([completeSummary]);
+ });
+
+ /** A formatted prompt copy shares its content array with the stored message
+ * it came from, so the drop must repoint the copy rather than splice: a
+ * splice would reindex the persisted row's parts under every reader that
+ * holds it, including the edit path's `/content/N` provenance. */
+ it('leaves the stored content array it was handed untouched', () => {
+ const stored = [text, failedSummary];
+ const promptCopy = { role: 'assistant', content: stored };
+
+ expect(dropUnusableSummaryParts(promptCopy)).toBe(true);
+ expect(promptCopy.content).not.toBe(stored);
+ expect(stored).toEqual([text, failedSummary]);
+ });
+
+ it.each<[string, { role: string; content?: unknown }]>([
+ ['no unusable summary', { role: 'assistant', content: [completeSummary] }],
+ ['an empty summary, which bounds nothing', { role: 'assistant', content: [emptySummary] }],
+ ['string content', { role: 'user', content: 'Plain text turn' }],
+ ])('reports nothing dropped for %s', (_label, message) => {
+ const before = JSON.stringify(message);
+
+ expect(dropUnusableSummaryParts(message)).toBe(false);
+ expect(JSON.stringify(message)).toBe(before);
+ });
+
+ /** The memory payload is not the caller's to mutate, so that path gets a copy
+ * with the same parts removed and the same positions. */
+ it('strips a payload the caller does not own without touching it', () => {
+ const payload = [
+ { role: 'user', content: [{ type: ContentTypes.TEXT, text: 'First question' }] },
+ { role: 'assistant', content: [text, failedSummary] },
+ ];
+
+ const result = stripUnusableSummaryParts(payload);
+
+ expect(result[0]).toBe(payload[0]);
+ expect(result[1].content).toEqual([text]);
+ expect(payload[1].content).toEqual([text, failedSummary]);
+ });
+
+ it('returns the same payload reference when nothing needed stripping', () => {
+ const payload = [{ role: 'assistant', content: [completeSummary] }];
+
+ expect(stripUnusableSummaryParts(payload)).toBe(payload);
+ });
+});
diff --git a/packages/api/src/agents/compaction.ts b/packages/api/src/agents/compaction.ts
index 2bedcda3a7..e89311178f 100644
--- a/packages/api/src/agents/compaction.ts
+++ b/packages/api/src/agents/compaction.ts
@@ -17,16 +17,113 @@ import type {
TCompactionSemanticIndexEntry,
} from '@librechat/data-schemas';
import type { SummaryContentPart, TMessageContentParts } from 'librechat-data-provider';
+import type { IAgentEventActorSummary } from '@librechat/data-schemas';
+import { createAgentEventActorSummary } from './compatibility';
-/** Text of a summary content part; empty for anything else. */
+/** Text of a summary content part, in any persisted shape — `content` blocks
+ * today, a string `content` or a bare `text` on rows written before them.
+ * Empty for anything else. */
export function getSummaryPartText(part: TMessageContentParts | null | undefined): string {
- if (part?.type !== ContentTypes.SUMMARY || !Array.isArray(part.content)) {
+ if (part?.type !== ContentTypes.SUMMARY) {
return '';
}
- return part.content
- .map((block) => (typeof block?.text === 'string' ? block.text : ''))
- .join('')
- .trim();
+ /** Widened on purpose: rows written before summary `content` blocks hold a
+ * string `content` or a bare `text`, neither of which the part type models. */
+ const content: unknown = part.content;
+ if (typeof content === 'string') {
+ return content.trim();
+ }
+ if (Array.isArray(content)) {
+ let text = '';
+ for (const block of content) {
+ if (block != null && typeof block === 'object' && 'text' in block) {
+ text += typeof block.text === 'string' ? block.text : '';
+ }
+ }
+ return text.trim();
+ }
+ return 'text' in part && typeof part.text === 'string' ? part.text.trim() : '';
+}
+
+/**
+ * A summary that can stand for the history it covers: it carries text, and its
+ * round both finished and did not error. A round that failed or was cut off
+ * keeps whatever deltas it streamed, so its text is a truncated prefix of the
+ * history it was summarizing rather than a checkpoint for it — the same test
+ * `isCompactedLeaf` applies when deciding whether a compaction can be retried.
+ *
+ * `failed` has only been stamped since the server began recording errored
+ * rounds, so the flags alone cannot vouch for older rows. The aggregator gives
+ * the structural answer: deltas stream `content` blocks into the part, and only
+ * a completed round replaces it with the final block, which is the only writer
+ * of `boundary`. A `content`-block summary without one therefore never
+ * finished, however it was stored. Rows in the bare-`text` shape predate that
+ * aggregator and are left to the flags.
+ */
+export function isUsableSummaryPart(part: unknown): part is SummaryContentPart {
+ if (part == null || typeof part !== 'object' || !('type' in part)) {
+ return false;
+ }
+ if (part.type !== ContentTypes.SUMMARY) {
+ return false;
+ }
+ /** Narrowed by the discriminant above: this is the summary union member. */
+ const summary = part as SummaryContentPart;
+ if (summary.failed === true || summary.summarizing === true) {
+ return false;
+ }
+ if (Array.isArray(summary.content) && summary.boundary == null) {
+ return false;
+ }
+ return getSummaryPartText(summary).length > 0;
+}
+
+/**
+ * The summary a message offers as the conversation's checkpoint: the last
+ * usable one in its content (last-summary-wins). Null when the message carries
+ * none — an empty or failed summary leaves the history it hangs off in place.
+ */
+export function findCheckpointSummaryPart(content: unknown): SummaryContentPart | null {
+ if (!Array.isArray(content)) {
+ return null;
+ }
+ let checkpoint: SummaryContentPart | null = null;
+ for (const part of content) {
+ if (isUsableSummaryPart(part)) {
+ checkpoint = part;
+ }
+ }
+ return checkpoint;
+}
+
+/**
+ * The summary a warm event-actor continuation carries forward: the last usable
+ * one in the run's content parts, stamped as actor state. A failed or
+ * unfinished round's partial deltas would otherwise be persisted as actor state
+ * and handed to the next run as its `initialSummary`, which skips durable
+ * history entirely. A missing or invalid token count is recorded as zero.
+ */
+export function getLatestEventActorSummary(
+ contentParts: unknown,
+): IAgentEventActorSummary | undefined {
+ if (!Array.isArray(contentParts)) {
+ return undefined;
+ }
+ for (let index = contentParts.length - 1; index >= 0; index -= 1) {
+ const part: unknown = contentParts[index];
+ if (!isUsableSummaryPart(part)) {
+ continue;
+ }
+ const tokenCount = part.tokenCount;
+ return createAgentEventActorSummary({
+ text: getSummaryPartText(part),
+ tokenCount:
+ typeof tokenCount === 'number' && Number.isFinite(tokenCount) && tokenCount >= 0
+ ? tokenCount
+ : 0,
+ });
+ }
+ return undefined;
}
/** The typed failure a manual compaction reports when it produced no summary. */
@@ -77,12 +174,7 @@ export function markCompactionOutcome(
contentParts: TMessageContentParts[],
{ aborted = false }: { aborted?: boolean } = {},
): void {
- const summary = contentParts.find(
- (part): part is SummaryContentPart =>
- part?.type === ContentTypes.SUMMARY &&
- part.failed !== true &&
- getSummaryPartText(part).length > 0,
- );
+ const summary = contentParts.find(isUsableSummaryPart);
if (summary != null) {
summary.initiatedBy = 'user';
return;
@@ -100,11 +192,11 @@ export function markCompactionOutcome(
if (aborted) {
throw Object.assign(new Error(COMPACTION_FAILED_ERROR), { code: 'COMPACTION_FAILED' });
}
- /** A failed round keeps whatever deltas it streamed, and history loading
- * accepts any nonempty summary as the conversation's checkpoint
- * (`BaseClient.findSummaryContentBlock`). Persisting a truncated one would
- * replace the history it failed to summarize, so the unusable summary goes
- * and the typed failure is the turn's whole outcome. */
+ /** A failed round keeps whatever deltas it streamed, and a summary part with
+ * text is the history boundary for everything downstream. Persisting a
+ * truncated one would stand in for the history it failed to summarize, so
+ * the unusable summary goes and the typed failure is the turn's whole
+ * outcome. */
for (let index = contentParts.length - 1; index >= 0; index -= 1) {
if (contentParts[index]?.type === ContentTypes.SUMMARY) {
contentParts.splice(index, 1);
@@ -113,6 +205,84 @@ export function markCompactionOutcome(
contentParts.push(...compactionFailureContent());
}
+function isSummaryPartWithText(part: unknown): boolean {
+ if (part == null || typeof part !== 'object' || !('type' in part)) {
+ return false;
+ }
+ if (part.type !== ContentTypes.SUMMARY) {
+ return false;
+ }
+ /** Narrowed by the discriminant above: this is the summary union member. */
+ const summary = part as SummaryContentPart;
+ return getSummaryPartText(summary).length > 0;
+}
+
+/** The content of one message with every unusable summary part removed, or the
+ * same array when there was nothing to remove. */
+function withoutUnusableSummaryParts(content: unknown[]): unknown[] {
+ const filtered = content.filter(
+ (part) => isUsableSummaryPart(part) || !isSummaryPartWithText(part),
+ );
+ return filtered.length === content.length ? content : filtered;
+}
+
+/**
+ * Points one model-facing message at content free of the summary parts that
+ * cannot bound history, and reports whether anything went. The SDK's summary
+ * scan takes the last summary part carrying text as the conversation's history
+ * boundary and drops every message before it, reading neither `failed` nor
+ * `summarizing`: a round that errored or was cut off keeps the deltas it
+ * streamed, so leaving that part in would replace the history it never
+ * finished summarizing with the prefix it produced. An empty summary is left
+ * alone — it bounds nothing, and the renderer owns how it appears.
+ *
+ * The message gets a NEW content array rather than a spliced one, because a
+ * formatted prompt copy shares its content array with the stored message it
+ * came from: splicing would reindex the persisted row's parts under every
+ * reader that holds it. This belongs on a prompt copy before its token count
+ * is taken, so the count, the prompt total an admission check reads, and any
+ * later per-index adjustment all describe what the model actually receives.
+ */
+export function dropUnusableSummaryParts(message: { content?: unknown }): boolean {
+ const content = message?.content;
+ if (!Array.isArray(content)) {
+ return false;
+ }
+ const filtered = withoutUnusableSummaryParts(content);
+ if (filtered === content) {
+ return false;
+ }
+ message.content = filtered;
+ return true;
+}
+
+/**
+ * The same rule for a payload whose messages the caller may not touch:
+ * returns a payload of messages carrying no unusable summary part, leaving the
+ * input and its messages untouched and returning the same reference when
+ * nothing needed dropping. Message positions are preserved, so an index-keyed
+ * token map stays aligned.
+ */
+export function stripUnusableSummaryParts<T extends { content?: unknown }>(payload: T[]): T[] {
+ if (!Array.isArray(payload)) {
+ return payload;
+ }
+ let changed = false;
+ const result = payload.map((message) => {
+ const content = message?.content;
+ if (!Array.isArray(content)) {
+ return message;
+ }
+ const filtered = withoutUnusableSummaryParts(content);
+ if (filtered === content) {
+ return message;
+ }
+ changed = true;
+ return { ...message, content: filtered };
+ });
+ return changed ? result : payload;
+}
+
function snapshotEntry(
entry: CompactionSemanticIndexEntry,
): TCompactionSemanticIndexEntry | undefined {
diff --git a/packages/api/src/agents/compatibility.spec.ts b/packages/api/src/agents/compatibility.spec.ts
index 56093bd94b..991062ea54 100644
--- a/packages/api/src/agents/compatibility.spec.ts
+++ b/packages/api/src/agents/compatibility.spec.ts
@@ -1,8 +1,10 @@
import {
agentContextFingerprintsMatch,
createAgentContextFingerprint,
+ createAgentEventActorSummary,
createInitializedAgentContextFingerprint,
normalizeAgentEventActorDiscoveredTools,
+ normalizeAgentEventActorSummary,
type AgentTurnSemanticContext,
} from './compatibility';
@@ -212,3 +214,52 @@ describe('agent context compatibility', () => {
expect(fingerprint('First schema').digest).not.toBe(fingerprint('Updated schema').digest);
});
});
+
+describe('event actor summary state', () => {
+ it('stamps the provenance version on a summary a run records', () => {
+ expect(
+ createAgentEventActorSummary({ text: 'Earlier turns, compacted.', tokenCount: 12 }),
+ ).toEqual({ text: 'Earlier turns, compacted.', tokenCount: 12, version: 1 });
+ });
+
+ it.each([
+ ['nothing to stamp', undefined],
+ ['a null summary', null],
+ ])('records %s as no state at all', (_label, summary) => {
+ expect(createAgentEventActorSummary(summary)).toBeUndefined();
+ });
+
+ /** A summary the formatter reconstructed from durable history arrives in the
+ * SDK's shape; stamping it is what keeps the next event on the warm path. */
+ it('stamps a summary inherited in the SDK shape', () => {
+ expect(createAgentEventActorSummary({ text: 'Reconstructed.', tokenCount: 9 })).toMatchObject({
+ version: 1,
+ });
+ });
+ it('restores a versioned summary for a warm continuation', () => {
+ const stored = { text: 'Earlier turns, compacted.', tokenCount: 12, version: 1 };
+
+ expect(normalizeAgentEventActorSummary(stored)).toEqual(stored);
+ });
+
+ it('treats an absent summary as nothing to carry forward', () => {
+ expect(normalizeAgentEventActorSummary(undefined)).toBeUndefined();
+ });
+
+ /** A state written before the version kept only `{ text, tokenCount }`, so a
+ * round that failed reads exactly like a checkpoint. Refusing it sends the
+ * run down the cold path, which rebuilds from durable history. */
+ it.each([
+ ['no version, as written before it existed', { text: 'Half a checkpoint', tokenCount: 4 }],
+ [
+ 'a version this build does not know',
+ { text: 'Half a checkpoint', tokenCount: 4, version: 2 },
+ ],
+ ['empty text', { text: '', tokenCount: 4, version: 1 }],
+ ['a negative token count', { text: 'Checkpoint', tokenCount: -1, version: 1 }],
+ ])('refuses a stored summary with %s', (_label, stored) => {
+ expect(() => normalizeAgentEventActorSummary(stored)).toThrow(
+ 'Event actor summary state is invalid',
+ );
+ });
+});
diff --git a/packages/api/src/agents/compatibility.ts b/packages/api/src/agents/compatibility.ts
index dfdb2154c6..f0e5662375 100644
--- a/packages/api/src/agents/compatibility.ts
+++ b/packages/api/src/agents/compatibility.ts
@@ -1,8 +1,11 @@
import { createHash } from 'node:crypto';
import {
+ AGENT_EVENT_ACTOR_SUMMARY_VERSION,
MAX_AGENT_EVENT_ACTOR_DISCOVERED_TOOLS,
+ MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH,
MAX_AGENT_EVENT_ACTOR_TOOL_NAME_LENGTH,
} from '@librechat/data-schemas';
+import type { IAgentEventActorSummary } from '@librechat/data-schemas';
export const AGENT_CONTEXT_FINGERPRINT_VERSION = 1;
export const AGENT_GRAPH_SCHEMA_VERSION = 1;
@@ -105,6 +108,55 @@ export function normalizeAgentEventActorDiscoveredTools(
return [...normalized].sort((left, right) => left.localeCompare(right));
}
+/**
+ * The summary a run records as event-actor state, stamped with the provenance
+ * version. The version records the writer, not a judgement about this summary:
+ * a build that reaches here has already filtered unusable summaries out of
+ * every source it reads — the turn's own content parts, a validated restore,
+ * or the formatter over the stripped payload. Stamping at the point state is
+ * assembled is what keeps an inherited `{ text, tokenCount }` from the SDK
+ * from being refused by the next event and forcing a cold reload.
+ */
+export function createAgentEventActorSummary(
+ summary: { text: string; tokenCount: number } | null | undefined,
+): IAgentEventActorSummary | undefined {
+ if (summary == null) {
+ return undefined;
+ }
+ return {
+ text: summary.text,
+ tokenCount: summary.tokenCount,
+ version: AGENT_EVENT_ACTOR_SUMMARY_VERSION,
+ };
+}
+
+/**
+ * A stored event-actor summary a warm continuation may carry forward. Throws
+ * for anything it cannot vouch for, including a state written before the
+ * version existed: those kept only `{ text, tokenCount }`, so a round that
+ * failed or never finished reads exactly like a checkpoint, and a warm run
+ * would continue from a truncated prefix. Refusing one costs a cold
+ * continuation, which rebuilds context from durable history.
+ */
+export function normalizeAgentEventActorSummary(
+ summary: IAgentEventActorSummary | null | undefined,
+): IAgentEventActorSummary | undefined {
+ if (summary == null) {
+ return undefined;
+ }
+ if (
+ typeof summary.text !== 'string' ||
+ summary.text.length === 0 ||
+ summary.text.length > MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH ||
+ !Number.isFinite(summary.tokenCount) ||
+ summary.tokenCount < 0 ||
+ summary.version !== AGENT_EVENT_ACTOR_SUMMARY_VERSION
+ ) {
+ throw new RangeError('Event actor summary state is invalid');
+ }
+ return createAgentEventActorSummary(summary);
+}
+
export function createSkillContentDigest(body: string): string {
return createHash('sha256').update(body).digest('base64url');
}
diff --git a/packages/data-provider/src/messages.spec.ts b/packages/data-provider/src/messages.spec.ts
index 6dc333301c..600478fdc0 100644
--- a/packages/data-provider/src/messages.spec.ts
+++ b/packages/data-provider/src/messages.spec.ts
@@ -203,6 +203,7 @@ describe('isCompactedLeaf', () => {
const summary = (overrides: Record<string, unknown> = {}) => ({
type: ContentTypes.SUMMARY,
content: [{ type: ContentTypes.TEXT, text: 'checkpoint' }],
+ boundary: { messageId: 'step_summary', contentIndex: 0 },
...overrides,
});
@@ -216,6 +217,7 @@ describe('isCompactedLeaf', () => {
['a summary next to text', [summary(), { type: ContentTypes.TEXT, text: 'reply' }]],
['a summary still streaming', [summary({ summarizing: true })]],
['a failed summary', [summary({ failed: true })]],
+ ['a streamed summary that never recorded a boundary', [summary({ boundary: undefined })]],
['an empty summary', [summary({ content: [] })]],
])('is false for %s', (_label, content) => {
expect(isCompactedLeaf({ content } as TMessage)).toBe(false);
diff --git a/packages/data-provider/src/messages.ts b/packages/data-provider/src/messages.ts
index 09bd24c76e..df952ba58a 100644
--- a/packages/data-provider/src/messages.ts
+++ b/packages/data-provider/src/messages.ts
@@ -228,7 +228,9 @@ export function isCompactedLeaf(message?: Pick<TMessage, 'content'> | null): boo
if (part?.type !== ContentTypes.SUMMARY) {
return false;
}
- if (part.summarizing === true || part.failed === true) {
+ /** No `boundary` means the round never completed: only the final summary
+ * block carries one, so a part holding streamed deltas alone lacks it. */
+ if (part.summarizing === true || part.failed === true || part.boundary == null) {
continue;
}
const hasText = (part.content ?? []).some(
diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.ts
index feb39b8823..0b463796ad 100644
--- a/packages/data-schemas/src/index.ts
+++ b/packages/data-schemas/src/index.ts
@@ -51,6 +51,7 @@ export {
} from './methods';
export { FAVORITE_ITEM_TYPES } from './types/favorite';
export {
+ AGENT_EVENT_ACTOR_SUMMARY_VERSION,
MAX_AGENT_EVENT_ACTOR_DISCOVERED_TOOLS,
MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH,
MAX_AGENT_EVENT_ACTOR_SKILLS,
diff --git a/packages/data-schemas/src/schema/convo.ts b/packages/data-schemas/src/schema/convo.ts
index e8692fe9c2..db0946e7ae 100644
--- a/packages/data-schemas/src/schema/convo.ts
+++ b/packages/data-schemas/src/schema/convo.ts
@@ -141,6 +141,7 @@ const convoSchema: Schema<IConversation> = new Schema(
maxlength: MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH,
},
tokenCount: { type: Number, min: 0, required: true },
+ version: { type: Number, min: 1 },
},
_id: false,
default: undefined,
diff --git a/packages/data-schemas/src/types/convo.ts b/packages/data-schemas/src/types/convo.ts
index f61cc993bd..afb3889bbc 100644
--- a/packages/data-schemas/src/types/convo.ts
+++ b/packages/data-schemas/src/types/convo.ts
@@ -12,6 +12,14 @@ export const MAX_AGENT_EVENT_ACTOR_DISCOVERED_TOOLS = 128;
export const MAX_AGENT_EVENT_ACTOR_TOOL_NAME_LENGTH = 512;
export const MAX_AGENT_EVENT_ACTOR_SUMMARY_LENGTH = 1_000_000;
export const MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH = 128;
+/**
+ * Provenance of a stored event-actor summary. States written before this
+ * version kept only `{ text, tokenCount }`, so a round that failed or never
+ * finished is indistinguishable from a checkpoint once persisted. A restore
+ * requires the current version, which is what lets a warm continuation trust
+ * the summary instead of rebuilding from durable history.
+ */
+export const AGENT_EVENT_ACTOR_SUMMARY_VERSION = 1;
export interface ISubagentThreadLease {
token: string;
@@ -48,6 +56,8 @@ export interface IAgentEventActorSkillIdentity {
export interface IAgentEventActorSummary {
text: string;
tokenCount: number;
+ /** {@link AGENT_EVENT_ACTOR_SUMMARY_VERSION}; absent on pre-version states. */
+ version?: number;
}
/**