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

📦 chore: bump `@librechat/agents` SDK to v3.9.6 (#16354)

Danny Avila3c08a7dd0459
diff --git a/api/package.json b/api/package.json
index 3548ab93d7..e588bfb8ea 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": "5.1.6",
- "@librechat/agents": "^3.9.3",
+ "@librechat/agents": "^3.9.6",
"@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 a76dd8e650..ae72f09200 100644
--- a/api/server/controllers/agents/client.js
+++ b/api/server/controllers/agents/client.js
@@ -173,6 +173,7 @@ const {
restoreCompactionSemanticIndexSnapshot,
MAX_AGENT_CONTEXT_SKILLS,
isAgentFadingTier,
+ isCurrentAgentFadingTier,
isAgentFadingTierEntries,
resolveRunContextMeta,
resolveRunFadingTiers,
@@ -297,7 +298,7 @@ function resolveRunSeeds(client) {
const encodingMatch = prevMeta.encoding === currentEncoding;
const calibrationRatio =
encodingMatch && prevMeta.calibrationRatio > 0 ? prevMeta.calibrationRatio : undefined;
- const fadingTier = isAgentFadingTier(prevMeta.fading) ? prevMeta.fading : undefined;
+ const fadingTier = isCurrentAgentFadingTier(prevMeta.fading) ? prevMeta.fading : undefined;
const fadingTiers = resolveRunFadingTiers(prevMeta.fadingTiers);
logger.debug(
`[AgentClient] contextMeta from parent: ratio=${prevMeta.calibrationRatio}, encoding=${prevMeta.encoding}, current=${currentEncoding}, seeded=${calibrationRatio ?? 'none'}, fading=${fadingTier ? `${fadingTier.budgetTokens}/${fadingTier.masked}` : 'none'}, agents=${fadingTiers ? Object.keys(fadingTiers).length : 0}`,
diff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.js
index 4cc2f02655..a5725c12dd 100644
--- a/api/server/controllers/agents/client.test.js
+++ b/api/server/controllers/agents/client.test.js
@@ -3547,9 +3547,9 @@ describe('AgentClient - startup telemetry', () => {
client.contextMeta = {
calibrationRatio: 1.25,
encoding: client.getEncoding(),
- fading: { v: 1, budgetTokens: 20_000, masked: true },
+ fading: { v: 2, budgetTokens: 20_000, masked: true },
fadingTiers: [
- { agentId: 'agent-123', v: 1, budgetTokens: 20_000, masked: true },
+ { agentId: 'agent-123', v: 2, budgetTokens: 20_000, masked: true },
{ agentId: 'agent-worker', v: 1, budgetTokens: 8_000, masked: false },
],
};
@@ -3571,10 +3571,9 @@ describe('AgentClient - startup telemetry', () => {
indexTokenCountMap: {},
initialSummary: { text: 'summary of earlier turns', tokenCount: 40 },
calibrationRatio: 1.25,
- fadingTier: { v: 1, budgetTokens: 20_000, masked: true },
+ fadingTier: { v: 2, budgetTokens: 20_000, masked: true },
fadingTiers: {
- 'agent-123': { v: 1, budgetTokens: 20_000, masked: true },
- 'agent-worker': { v: 1, budgetTokens: 8_000, masked: false },
+ 'agent-123': { v: 2, budgetTokens: 20_000, masked: true },
},
compactionSemanticIndex: evolvedCompactionSemanticIndexSnapshot.entries,
}),
diff --git a/package-lock.json b/package-lock.json
index 6e48c35dc2..36921d7d96 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -64,7 +64,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
- "@librechat/agents": "^3.9.3",
+ "@librechat/agents": "^3.9.6",
"@librechat/api": "*",
"@librechat/data-schemas": "*",
"@microsoft/microsoft-graph-client": "^3.0.7",
@@ -10622,9 +10622,9 @@
}
},
"node_modules/@librechat/agents": {
- "version": "3.9.3",
- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.9.3.tgz",
- "integrity": "sha512-KuR6/N8XVA4y7PeE/HE5695DtMtW5a9Fvnuffn85/vd4zt1u9lMTP+MQCbFfPA/91eUwJu/vb2YsFCm/7NC/uA==",
+ "version": "3.9.6",
+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.9.6.tgz",
+ "integrity": "sha512-sHKqt4f12+jfSybbi1hizvMm6gB/yYpwcS0+miad+ZZoBP3xNeuaOXIILW9TO9WwQYlVRbGImS6IF89qd8BSXw==",
"license": "MIT",
"dependencies": {
"@anthropic-ai/sdk": "^0.115.0",
@@ -42449,7 +42449,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
- "@librechat/agents": "^3.9.3",
+ "@librechat/agents": "^3.9.6",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.30.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/package.json b/packages/api/package.json
index f4cc6bfb28..7fc2ae30b7 100644
--- a/packages/api/package.json
+++ b/packages/api/package.json
@@ -120,7 +120,7 @@
"@azure/storage-blob": "^12.30.0",
"@google/genai": "^2.8.0",
"@keyv/redis": "5.1.6",
- "@librechat/agents": "^3.9.3",
+ "@librechat/agents": "^3.9.6",
"@librechat/data-schemas": "*",
"@modelcontextprotocol/sdk": "^1.30.0",
"@opentelemetry/api": "^1.9.0",
diff --git a/packages/api/src/agents/fading.spec.ts b/packages/api/src/agents/fading.spec.ts
index 37bb283411..1992e3a880 100644
--- a/packages/api/src/agents/fading.spec.ts
+++ b/packages/api/src/agents/fading.spec.ts
@@ -1,9 +1,16 @@
+import { AGENT_FADING_TIER_VERSION } from '@librechat/data-schemas';
import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
-import { createPruneMessages, resolveFadingCaps, seedFadingTier } from '@librechat/agents';
+import {
+ FADING_TIER_VERSION,
+ createPruneMessages,
+ resolveFadingCaps,
+ seedFadingTier,
+} from '@librechat/agents';
import type { IAgentFadingTier } from '@librechat/data-schemas';
import type { BaseMessage } from '@langchain/core/messages';
import {
isAgentFadingTier,
+ isCurrentAgentFadingTier,
resolvePersistableFadingTier,
resolvePersistableFadingTiers,
resolveRunContextMeta,
@@ -11,12 +18,19 @@ import {
} from './fading';
describe('isAgentFadingTier', () => {
+ it('matches the actual SDK tier version', () => {
+ expect(AGENT_FADING_TIER_VERSION).toBe(FADING_TIER_VERSION);
+ });
+
it('accepts a well-formed tier and rejects everything else', () => {
+ expect(isAgentFadingTier({ v: 2, budgetTokens: 20_000, masked: true })).toBe(true);
expect(isAgentFadingTier({ v: 1, budgetTokens: 20_000, masked: true })).toBe(true);
- expect(isAgentFadingTier({ v: 2, budgetTokens: 20_000, masked: true })).toBe(false);
- expect(isAgentFadingTier({ v: 1, budgetTokens: 0, masked: true })).toBe(false);
- expect(isAgentFadingTier({ v: 1, budgetTokens: 20_000, masked: 'yes' })).toBe(false);
- expect(isAgentFadingTier({ v: 1, budgetTokens: Number.NaN, masked: false })).toBe(false);
+ expect(isCurrentAgentFadingTier({ v: 2, budgetTokens: 20_000, masked: true })).toBe(true);
+ expect(isCurrentAgentFadingTier({ v: 1, budgetTokens: 20_000, masked: true })).toBe(false);
+ expect(isAgentFadingTier({ v: 3, budgetTokens: 20_000, masked: true })).toBe(false);
+ expect(isAgentFadingTier({ v: 2, budgetTokens: 0, masked: true })).toBe(false);
+ expect(isAgentFadingTier({ v: 2, budgetTokens: 20_000, masked: 'yes' })).toBe(false);
+ expect(isAgentFadingTier({ v: 2, budgetTokens: Number.NaN, masked: false })).toBe(false);
expect(isAgentFadingTier(null)).toBe(false);
expect(isAgentFadingTier(undefined)).toBe(false);
});
@@ -25,28 +39,33 @@ describe('isAgentFadingTier', () => {
describe('resolvePersistableFadingTier', () => {
it('strips a valid tier to its fields and drops invalid input', () => {
expect(
- resolvePersistableFadingTier({ v: 1, budgetTokens: 50_000, masked: true, extra: 1 }),
- ).toEqual({ v: 1, budgetTokens: 50_000, masked: true });
+ resolvePersistableFadingTier({ v: 2, budgetTokens: 50_000, masked: true, extra: 1 }),
+ ).toEqual({ v: 2, budgetTokens: 50_000, masked: true });
+ expect(resolvePersistableFadingTier({ v: 1, budgetTokens: 50_000, masked: true })).toEqual({
+ v: 1,
+ budgetTokens: 50_000,
+ masked: true,
+ });
expect(resolvePersistableFadingTier(undefined)).toBeUndefined();
- expect(resolvePersistableFadingTier({ v: 1, budgetTokens: -1, masked: true })).toBeUndefined();
+ expect(resolvePersistableFadingTier({ v: 2, budgetTokens: -1, masked: true })).toBeUndefined();
});
});
describe('resolvePersistableFadingTiers', () => {
it('keeps only valid tiers, stripped to the compact shape, from own keys', () => {
const snapshot = Object.fromEntries([
- ['agent-a', { v: 1, budgetTokens: 20_000, masked: true, latched: true }],
- ['agent-b', { v: 1, budgetTokens: 0, masked: false }],
- ['__proto__', { v: 1, budgetTokens: 10_000, masked: false, latched: true }],
+ ['agent-a', { v: 2, budgetTokens: 20_000, masked: true, latched: true }],
+ ['agent-b', { v: 2, budgetTokens: 0, masked: false }],
+ ['__proto__', { v: 2, budgetTokens: 10_000, masked: false, latched: true }],
]);
expect(resolvePersistableFadingTiers(snapshot)).toEqual([
- { agentId: 'agent-a', v: 1, budgetTokens: 20_000, masked: true },
- { agentId: '__proto__', v: 1, budgetTokens: 10_000, masked: false },
+ { agentId: 'agent-a', v: 2, budgetTokens: 20_000, masked: true },
+ { agentId: '__proto__', v: 2, budgetTokens: 10_000, masked: false },
]);
});
it('ignores inherited keys and yields nothing for an empty or invalid snapshot', () => {
- const inherited = Object.create({ ghost: { v: 1, budgetTokens: 20_000, masked: true } });
+ const inherited = Object.create({ ghost: { v: 2, budgetTokens: 20_000, masked: true } });
expect(resolvePersistableFadingTiers(inherited)).toBeUndefined();
expect(resolvePersistableFadingTiers({})).toBeUndefined();
expect(resolvePersistableFadingTiers(null)).toBeUndefined();
@@ -57,48 +76,57 @@ describe('resolvePersistableFadingTiers', () => {
describe('resolveRunFadingTiers', () => {
it('rebuilds a prototype-safe record from persisted entries', () => {
const tiers = resolveRunFadingTiers([
- { agentId: 'agent-a', v: 1, budgetTokens: 20_000, masked: true },
- { agentId: '__proto__', v: 1, budgetTokens: 10_000, masked: false },
+ { agentId: 'agent-a', v: 2, budgetTokens: 20_000, masked: true },
+ { agentId: '__proto__', v: 2, budgetTokens: 10_000, masked: false },
]);
expect(tiers).toBeDefined();
expect(Object.getPrototypeOf(tiers)).toBeNull();
expect(Object.keys(tiers ?? {})).toEqual(['agent-a', '__proto__']);
expect(Object.prototype.hasOwnProperty.call(tiers, '__proto__')).toBe(true);
- expect(tiers?.['agent-a']).toEqual({ v: 1, budgetTokens: 20_000, masked: true });
+ expect(tiers?.['agent-a']).toEqual({ v: 2, budgetTokens: 20_000, masked: true });
expect('budgetTokens' in {}).toBe(false);
});
it('rejects duplicate, malformed, or empty entry lists', () => {
expect(
resolveRunFadingTiers([
- { agentId: 'agent-a', v: 1, budgetTokens: 20_000, masked: true },
- { agentId: 'agent-a', v: 1, budgetTokens: 10_000, masked: true },
+ { agentId: 'agent-a', v: 2, budgetTokens: 20_000, masked: true },
+ { agentId: 'agent-a', v: 2, budgetTokens: 10_000, masked: true },
]),
).toBeUndefined();
expect(
- resolveRunFadingTiers([{ agentId: '', v: 1, budgetTokens: 1, masked: true }]),
+ resolveRunFadingTiers([{ agentId: '', v: 2, budgetTokens: 1, masked: true }]),
).toBeUndefined();
expect(resolveRunFadingTiers([])).toBeUndefined();
expect(resolveRunFadingTiers(undefined)).toBeUndefined();
});
+ it('keeps legacy entries readable but never seeds them into the v2 SDK', () => {
+ const legacy = { agentId: 'old-agent', v: 1, budgetTokens: 5_000, masked: true };
+ const current = { agentId: 'new-agent', v: 2, budgetTokens: 10_000, masked: false };
+ expect(resolveRunFadingTiers([legacy])).toBeUndefined();
+ const tiers = resolveRunFadingTiers([legacy, current]);
+ expect(Object.getPrototypeOf(tiers)).toBeNull();
+ expect(tiers).toEqual({ 'new-agent': { v: 2, budgetTokens: 10_000, masked: false } });
+ });
+
it('round-trips a run snapshot through the persisted entries unchanged', () => {
const snapshot = {
- 'agent-a': { v: 1 as const, budgetTokens: 20_000, masked: true, latched: true as const },
- 'agent-b': { v: 1 as const, budgetTokens: 5_000, masked: false, latched: true as const },
+ 'agent-a': { v: 2 as const, budgetTokens: 20_000, masked: true, latched: true as const },
+ 'agent-b': { v: 2 as const, budgetTokens: 5_000, masked: false, latched: true as const },
};
const entries = resolvePersistableFadingTiers(snapshot);
const restored = resolveRunFadingTiers(entries);
expect(restored).toEqual({
- 'agent-a': { v: 1, budgetTokens: 20_000, masked: true },
- 'agent-b': { v: 1, budgetTokens: 5_000, masked: false },
+ 'agent-a': { v: 2, budgetTokens: 20_000, masked: true },
+ 'agent-b': { v: 2, budgetTokens: 5_000, masked: false },
});
});
});
describe('resolveRunContextMeta', () => {
- const fading = { v: 1, budgetTokens: 20_000, masked: true };
+ const fading = { v: 2, budgetTokens: 20_000, masked: true };
const getEncoding = jest.fn(() => 'claude');
beforeEach(() => getEncoding.mockClear());
@@ -109,7 +137,7 @@ describe('resolveRunContextMeta', () => {
fadingTier: { ...fading, latched: true, messages: ['not persisted'] },
fadingTiers: {
'agent-a': { ...fading, latched: true, projection: { truncated: true } },
- 'agent-b': { v: 1, budgetTokens: 5_000, masked: false, latched: true },
+ 'agent-b': { v: 2, budgetTokens: 5_000, masked: false, latched: true },
},
getEncoding,
});
@@ -119,8 +147,8 @@ describe('resolveRunContextMeta', () => {
encoding: 'claude',
fading,
fadingTiers: [
- { agentId: 'agent-a', v: 1, budgetTokens: 20_000, masked: true },
- { agentId: 'agent-b', v: 1, budgetTokens: 5_000, masked: false },
+ { agentId: 'agent-a', v: 2, budgetTokens: 20_000, masked: true },
+ { agentId: 'agent-b', v: 2, budgetTokens: 5_000, masked: false },
],
});
expect(Object.keys(meta ?? {})).toEqual([
@@ -136,13 +164,13 @@ describe('resolveRunContextMeta', () => {
resolveRunContextMeta({
calibrationRatio: 1,
fadingTier: undefined,
- fadingTiers: { 'agent-b': { v: 1, budgetTokens: 5_000, masked: true } },
+ fadingTiers: { 'agent-b': { v: 2, budgetTokens: 5_000, masked: true } },
getEncoding,
}),
).toEqual({
calibrationRatio: 1,
encoding: 'claude',
- fadingTiers: [{ agentId: 'agent-b', v: 1, budgetTokens: 5_000, masked: true }],
+ fadingTiers: [{ agentId: 'agent-b', v: 2, budgetTokens: 5_000, masked: true }],
});
});
@@ -160,7 +188,7 @@ describe('resolveRunContextMeta', () => {
it('persists nothing, without resolving the encoding, when there is nothing to keep', () => {
expect(
- resolveRunContextMeta({ calibrationRatio: 0, fadingTier: { v: 1 }, getEncoding }),
+ resolveRunContextMeta({ calibrationRatio: 0, fadingTier: { v: 2 }, getEncoding }),
).toBeUndefined();
expect(getEncoding).not.toHaveBeenCalled();
});
@@ -211,12 +239,15 @@ describe('persisted tier round trip through the SDK pruner', () => {
summarizationEnabled: true,
calibrationRatio: overrides.calibrationRatio,
getInstructionTokens: () => overrides.instructionTokens,
- ...(overrides.fadingTier == null ? {} : { fadingTier: overrides.fadingTier }),
+ ...(isCurrentAgentFadingTier(overrides.fadingTier)
+ ? { fadingTier: overrides.fadingTier }
+ : {}),
})({ messages });
it("reproduces the first run's projection bytes when the next run is seeded from contextMeta", () => {
const turnOne = makeTurnOne();
const first = prune(turnOne, { calibrationRatio: 1, instructionTokens: 12_000 });
+ expect(first.fadingTier.v).toBe(2);
expect(first.fadingTier.budgetTokens).toBeLessThan(window);
const meta = resolveRunContextMeta({
@@ -225,7 +256,7 @@ describe('persisted tier round trip through the SDK pruner', () => {
getEncoding: () => 'claude',
});
expect(meta?.fading).toEqual({
- v: 1,
+ v: 2,
budgetTokens: first.fadingTier.budgetTokens,
masked: first.fadingTier.masked,
});
@@ -240,6 +271,13 @@ describe('persisted tier round trip through the SDK pruner', () => {
new HumanMessage('Say ok.'),
];
const firstBytes = serializeToolExchange(first.context);
+ const legacySeed = prune(makeTurnTwo(), {
+ calibrationRatio: 1,
+ instructionTokens: 9_000,
+ fadingTier: { v: 1, budgetTokens: first.fadingTier.budgetTokens, masked: true },
+ });
+ expect(legacySeed.fadingTier.v).toBe(2);
+ expect(legacySeed.fadingTier.budgetTokens).toBeGreaterThan(first.fadingTier.budgetTokens);
const drifted = { calibrationRatio: 1, instructionTokens: 9_000 };
const seeded = prune(makeTurnTwo(), { ...drifted, fadingTier: meta?.fading });
expect(serializeToolExchange(seeded.context.slice(0, turnOne.length))).toBe(firstBytes);
diff --git a/packages/api/src/agents/fading.ts b/packages/api/src/agents/fading.ts
index aa83607e4d..bbcb07612e 100644
--- a/packages/api/src/agents/fading.ts
+++ b/packages/api/src/agents/fading.ts
@@ -1,5 +1,6 @@
import {
isAgentFadingTier,
+ isCurrentAgentFadingTier,
isAgentFadingTierEntry,
isAgentFadingTierEntries,
AGENT_FADING_TIER_VERSION,
@@ -10,10 +11,13 @@ import type {
IAgentFadingTier,
} from '@librechat/data-schemas';
-export { isAgentFadingTier, isAgentFadingTierEntries };
+export { isAgentFadingTier, isCurrentAgentFadingTier, isAgentFadingTierEntries };
-/** Latched tiers keyed by agent ID, the shape `RunConfig.fadingTiers` takes. */
-export type RunFadingTiers = Record<string, IAgentFadingTier>;
+/** Latched current-version tiers keyed by agent ID for `RunConfig.fadingTiers`. */
+export type RunFadingTiers = Record<
+ string,
+ IAgentFadingTier & { v: typeof AGENT_FADING_TIER_VERSION }
+>;
/**
* Normalizes the tier a run exposes for persistence, or undefined when there
@@ -26,7 +30,7 @@ export function resolvePersistableFadingTier(tier: unknown): IAgentFadingTier |
if (!isAgentFadingTier(tier)) {
return undefined;
}
- return { v: AGENT_FADING_TIER_VERSION, budgetTokens: tier.budgetTokens, masked: tier.masked };
+ return { v: tier.v, budgetTokens: tier.budgetTokens, masked: tier.masked };
}
/**
@@ -49,19 +53,25 @@ export function resolvePersistableFadingTiers(tiers: unknown): IAgentFadingTierE
}
/**
- * Rebuilds `RunConfig.fadingTiers` from persisted entries on a null-prototype
- * record, so an agent ID such as `__proto__` stays an own key and can never
- * touch the prototype chain.
+ * Rebuilds `RunConfig.fadingTiers` from current-version entries on a null-prototype
+ * record. Legacy v1 tiers stay readable in storage but must be re-derived because
+ * the SDK changed the exchange-width calculation. An agent ID such as `__proto__`
+ * remains an own key and cannot touch the prototype chain.
*/
export function resolveRunFadingTiers(entries: unknown): RunFadingTiers | undefined {
if (!isAgentFadingTierEntries(entries) || entries.length === 0) {
return undefined;
}
const tiers: RunFadingTiers = Object.create(null);
+ let hasCurrentTier = false;
for (const { agentId, v, budgetTokens, masked } of entries) {
+ if (v !== AGENT_FADING_TIER_VERSION) {
+ continue;
+ }
tiers[agentId] = { v, budgetTokens, masked };
+ hasCurrentTier = true;
}
- return tiers;
+ return hasCurrentTier ? tiers : undefined;
}
export type RunContextMetaParams = {
diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts
index 8e010a21fb..44f98bc562 100644
--- a/packages/api/src/agents/run.ts
+++ b/packages/api/src/agents/run.ts
@@ -2179,10 +2179,10 @@ export async function createRun({
* Default agent's latched context-fading tier from the previous run's
* contextMeta. It seeds the pruner so the provider-only projection of
* historical tool results keeps the same bytes across runs; graph messages
- * stay canonical. Ships in `@librechat/agents` after 3.7.13; older SDK
- * versions ignore it.
+ * stay canonical. Legacy v1 tiers are not passed to the v2 SDK; it derives
+ * them afresh using the current-turn exchange width.
*/
- fadingTier?: IAgentFadingTier | null;
+ fadingTier?: (IAgentFadingTier & { v: 2 }) | null;
/**
* Latched tiers keyed by agent ID from the previous run's contextMeta, so
* every agent of a multi-agent run restores its own tier. Same SDK
diff --git a/packages/data-provider/src/schemas.spec.ts b/packages/data-provider/src/schemas.spec.ts
index fca60a549c..874f752220 100644
--- a/packages/data-provider/src/schemas.spec.ts
+++ b/packages/data-provider/src/schemas.spec.ts
@@ -683,6 +683,34 @@ describe('subagentThreadLineageSchema', () => {
});
});
+describe('tMessageSchema context fading', () => {
+ const message = {
+ messageId: 'message-1',
+ conversationId: 'conversation-1',
+ parentMessageId: null,
+ text: 'Assistant-role text',
+ isCreatedByUser: false,
+ };
+
+ it.each([1, 2])('round-trips stored version %i tiers', (v) => {
+ const fading = { v, budgetTokens: 10_000, masked: true };
+ const contextMeta = {
+ calibrationRatio: 1,
+ fading,
+ fadingTiers: [{ agentId: 'agent-a', ...fading }],
+ };
+ expect(tMessageSchema.parse({ ...message, contextMeta }).contextMeta).toEqual(contextMeta);
+ });
+
+ it('rejects unknown tier versions', () => {
+ const contextMeta = {
+ calibrationRatio: 1,
+ fading: { v: 3, budgetTokens: 10_000, masked: true },
+ };
+ expect(() => tMessageSchema.parse({ ...message, contextMeta })).toThrow();
+ });
+});
+
describe('tMessageSchema user-submitted provenance', () => {
const message = {
messageId: 'message-1',
diff --git a/packages/data-provider/src/schemas.ts b/packages/data-provider/src/schemas.ts
index a43dfab2b1..a2709edaed 100644
--- a/packages/data-provider/src/schemas.ts
+++ b/packages/data-provider/src/schemas.ts
@@ -877,7 +877,7 @@ export type TExample = z.infer<typeof tExampleSchema>;
/** Compact context-fading tier persisted beside a message's calibration ratio. */
const agentFadingTierSchema = z.object({
- v: z.literal(1),
+ v: z.union([z.literal(1), z.literal(2)]),
budgetTokens: z.number().positive(),
masked: z.boolean(),
});
diff --git a/packages/data-schemas/src/schema/fading.ts b/packages/data-schemas/src/schema/fading.ts
index 3b303cd2f0..72efa09791 100644
--- a/packages/data-schemas/src/schema/fading.ts
+++ b/packages/data-schemas/src/schema/fading.ts
@@ -6,7 +6,7 @@ interface AgentFadingContextDefinition {
/** Mongoose definition of one persisted context-fading tier (`IAgentFadingTier`). */
const agentFadingTierDefinition = {
- v: { type: Number, enum: [1], required: true },
+ v: { type: Number, enum: [1, 2], required: true },
budgetTokens: { type: Number, min: 1, required: true },
masked: { type: Boolean, required: true },
};
diff --git a/packages/data-schemas/src/types/convo.ts b/packages/data-schemas/src/types/convo.ts
index afb3889bbc..61cfc1bca8 100644
--- a/packages/data-schemas/src/types/convo.ts
+++ b/packages/data-schemas/src/types/convo.ts
@@ -67,7 +67,8 @@ export interface IAgentEventActorSummary {
* for prefix-based provider prompt caches. Graph messages stay canonical.
*/
export interface IAgentFadingTier {
- v: 1;
+ /** Version 1 is readable but must not seed a version 2 SDK run. */
+ v: 1 | 2;
/** Token budget the caps derive from; never grows within a conversation. */
budgetTokens: number;
/** Whether observation masking has activated. */
diff --git a/packages/data-schemas/src/utils/fading.spec.ts b/packages/data-schemas/src/utils/fading.spec.ts
index 7de1327f95..a5f73f7342 100644
--- a/packages/data-schemas/src/utils/fading.spec.ts
+++ b/packages/data-schemas/src/utils/fading.spec.ts
@@ -1,11 +1,19 @@
-import { isAgentFadingTier, isAgentFadingTierEntries, isAgentFadingTierEntry } from './fading';
+import {
+ isAgentFadingTier,
+ isCurrentAgentFadingTier,
+ isAgentFadingTierEntries,
+ isAgentFadingTierEntry,
+} from './fading';
-const tier = { v: 1, budgetTokens: 20_000, masked: true };
+const tier = { v: 2, budgetTokens: 20_000, masked: true };
describe('isAgentFadingTier', () => {
it('accepts the compact shape and rejects anything else', () => {
expect(isAgentFadingTier(tier)).toBe(true);
- expect(isAgentFadingTier({ ...tier, v: 2 })).toBe(false);
+ expect(isAgentFadingTier({ ...tier, v: 1 })).toBe(true);
+ expect(isCurrentAgentFadingTier(tier)).toBe(true);
+ expect(isCurrentAgentFadingTier({ ...tier, v: 1 })).toBe(false);
+ expect(isAgentFadingTier({ ...tier, v: 3 })).toBe(false);
expect(isAgentFadingTier({ ...tier, budgetTokens: 0 })).toBe(false);
expect(isAgentFadingTier({ ...tier, masked: 'yes' })).toBe(false);
expect(isAgentFadingTier(null)).toBe(false);
diff --git a/packages/data-schemas/src/utils/fading.ts b/packages/data-schemas/src/utils/fading.ts
index f7df158d25..55a8607434 100644
--- a/packages/data-schemas/src/utils/fading.ts
+++ b/packages/data-schemas/src/utils/fading.ts
@@ -1,7 +1,7 @@
import type { IAgentFadingTier, IAgentFadingTierEntry } from '~/types/convo';
-/** Version of the persisted context-fading tier shape; must match `@librechat/agents`. */
-export const AGENT_FADING_TIER_VERSION = 1;
+/** Current context-fading tier version; version 1 remains readable but is not seeded. */
+export const AGENT_FADING_TIER_VERSION = 2;
/** Whether a persisted value is a well-formed context-fading tier. */
export function isAgentFadingTier(value: unknown): value is IAgentFadingTier {
@@ -10,7 +10,7 @@ export function isAgentFadingTier(value: unknown): value is IAgentFadingTier {
}
const { v, budgetTokens, masked } = value as Partial<Record<keyof IAgentFadingTier, unknown>>;
return (
- v === AGENT_FADING_TIER_VERSION &&
+ (v === 1 || v === AGENT_FADING_TIER_VERSION) &&
typeof budgetTokens === 'number' &&
Number.isFinite(budgetTokens) &&
budgetTokens > 0 &&
@@ -18,6 +18,11 @@ export function isAgentFadingTier(value: unknown): value is IAgentFadingTier {
);
}
+/** Whether a tier can seed the current SDK instead of being re-derived from history. */
+export function isCurrentAgentFadingTier(value: unknown): value is IAgentFadingTier & { v: 2 } {
+ return isAgentFadingTier(value) && value.v === AGENT_FADING_TIER_VERSION;
+}
+
/**
* Whether a persisted value is a well-formed per-agent tier entry. Agent IDs
* are server-generated and unbounded (an ephemeral agent's ID encodes its