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: Fit MCP App Snapshots Within Message Documents (#16299)

lia-by-librechat[bot]55f318729668
diff --git a/api/models/index.js b/api/models/index.js
index 07504cf8b8..4ab4bfc6aa 100644
--- a/api/models/index.js
+++ b/api/models/index.js
@@ -1,13 +1,21 @@
const mongoose = require('mongoose');
const { createMethods } = require('@librechat/data-schemas');
-const { matchModelName, findMatchingPattern, isDeploymentSkillId } = require('@librechat/api');
+const {
+ matchModelName,
+ findMatchingPattern,
+ isDeploymentSkillId,
+ createMessageBudgetReader,
+} = require('@librechat/api');
const getLogStores = require('~/cache/getLogStores');
+const messageBudget = createMessageBudgetReader();
+
const methods = createMethods(mongoose, {
matchModelName,
findMatchingPattern,
isExternalSkillId: isDeploymentSkillId,
getCache: getLogStores,
+ getMCPAppMessageBudget: messageBudget.getBudget,
});
const seedDatabase = async () => {
@@ -19,5 +27,6 @@ const seedDatabase = async () => {
module.exports = {
...methods,
+ initializeMessageBudget: messageBudget.initialize,
seedDatabase,
};
diff --git a/api/models/index.spec.js b/api/models/index.spec.js
new file mode 100644
index 0000000000..a5bc4c9b41
--- /dev/null
+++ b/api/models/index.spec.js
@@ -0,0 +1,22 @@
+jest.mock('@librechat/data-schemas', () => ({ createMethods: jest.fn(() => ({})) }));
+jest.mock('@librechat/api', () => ({
+ matchModelName: jest.fn(),
+ findMatchingPattern: jest.fn(),
+ isDeploymentSkillId: jest.fn(),
+ createMessageBudgetReader: jest.fn(() => ({ getBudget: jest.fn(), initialize: jest.fn() })),
+}));
+jest.mock('~/cache/getLogStores', () => jest.fn());
+
+const { createMethods } = require('@librechat/data-schemas');
+const { createMessageBudgetReader } = require('@librechat/api');
+const { initializeMessageBudget } = require('./index');
+const reader = createMessageBudgetReader.mock.results[0].value;
+const { getMCPAppMessageBudget } = createMethods.mock.calls[0][1];
+
+describe('message App budget dependency wiring', () => {
+ it('passes the same reader to storage and initializer to the composition root', () => {
+ expect(getMCPAppMessageBudget).toBe(reader.getBudget);
+ expect(initializeMessageBudget).toBe(reader.initialize);
+ expect(reader.getBudget).not.toHaveBeenCalled();
+ });
+});
diff --git a/api/server/controllers/agents/__tests__/askUserQuestion.e2e.spec.js b/api/server/controllers/agents/__tests__/askUserQuestion.e2e.spec.js
index 3733188e89..f7117de240 100644
--- a/api/server/controllers/agents/__tests__/askUserQuestion.e2e.spec.js
+++ b/api/server/controllers/agents/__tests__/askUserQuestion.e2e.spec.js
@@ -34,6 +34,7 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
saveMessage: jest.fn(async (req, message) => message),
getConvo: jest.fn(async () => null),
getMessages: jest.fn(async () => []),
diff --git a/api/server/controllers/agents/__tests__/client.subagentUsage.spec.js b/api/server/controllers/agents/__tests__/client.subagentUsage.spec.js
index 21c15e809d..3fd3152fc9 100644
--- a/api/server/controllers/agents/__tests__/client.subagentUsage.spec.js
+++ b/api/server/controllers/agents/__tests__/client.subagentUsage.spec.js
@@ -2,6 +2,7 @@ const mockGetMultiplier = jest.fn(() => 1);
const mockGetCacheMultiplier = jest.fn(() => 1);
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
getMultiplier: (...args) => mockGetMultiplier(...args),
getCacheMultiplier: (...args) => mockGetCacheMultiplier(...args),
}));
diff --git a/api/server/controllers/agents/__tests__/client.transactions.spec.js b/api/server/controllers/agents/__tests__/client.transactions.spec.js
index 8f6e255ec2..4ad3d45172 100644
--- a/api/server/controllers/agents/__tests__/client.transactions.spec.js
+++ b/api/server/controllers/agents/__tests__/client.transactions.spec.js
@@ -1,6 +1,7 @@
const mockSpendTokens = jest.fn().mockResolvedValue(undefined);
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
spendTokens: mockSpendTokens,
}));
diff --git a/api/server/controllers/agents/__tests__/hitlCheckpoint.e2e.spec.js b/api/server/controllers/agents/__tests__/hitlCheckpoint.e2e.spec.js
index b0c9c6fc2a..365438dcab 100644
--- a/api/server/controllers/agents/__tests__/hitlCheckpoint.e2e.spec.js
+++ b/api/server/controllers/agents/__tests__/hitlCheckpoint.e2e.spec.js
@@ -32,6 +32,7 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
saveMessage: jest.fn(async (req, message) => message),
getConvo: jest.fn(async () => null),
getMessages: jest.fn(async () => []),
diff --git a/api/server/controllers/agents/recordCollectedUsage.spec.js b/api/server/controllers/agents/recordCollectedUsage.spec.js
index 6e00904107..4e86cef751 100644
--- a/api/server/controllers/agents/recordCollectedUsage.spec.js
+++ b/api/server/controllers/agents/recordCollectedUsage.spec.js
@@ -19,6 +19,7 @@ const mockRecordCollectedUsage = jest
.mockResolvedValue({ input_tokens: 100, output_tokens: 50 });
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
spendTokens: (...args) => mockSpendTokens(...args),
spendStructuredTokens: (...args) => mockSpendStructuredTokens(...args),
getMultiplier: mockGetMultiplier,
diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.js
index 71faa5dbdb..2e210520df 100644
--- a/api/server/routes/agents/__tests__/abort.spec.js
+++ b/api/server/routes/agents/__tests__/abort.spec.js
@@ -47,6 +47,7 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
saveMessage: (...args) => mockSaveMessage(...args),
saveConvo: (...args) => mockSaveConvo(...args),
}));
diff --git a/api/server/routes/agents/__tests__/streamTenant.spec.js b/api/server/routes/agents/__tests__/streamTenant.spec.js
index e23338c937..d3e3f28afe 100644
--- a/api/server/routes/agents/__tests__/streamTenant.spec.js
+++ b/api/server/routes/agents/__tests__/streamTenant.spec.js
@@ -37,6 +37,7 @@ jest.mock('@librechat/api', () => ({
}));
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
saveMessage: (...args) => mockSaveMessage(...args),
}));
diff --git a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js
index 8d21fb2e84..4b99cd28a8 100644
--- a/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js
+++ b/api/server/services/Config/__tests__/invalidateConfigCaches.spec.js
@@ -21,6 +21,7 @@ jest.mock('@librechat/data-schemas', () => {
});
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
getApplicableConfigs: jest.fn().mockResolvedValue([]),
getUserPrincipals: jest.fn().mockResolvedValue([]),
}));
@@ -45,7 +46,14 @@ jest.mock('@librechat/api', () => ({
// ── Tests ──────────────────────────────────────────────────────────────
-const { invalidateConfigCaches } = require('../app');
+const { getAppConfig, invalidateConfigCaches } = require('../app');
+const { initializeMessageBudget } = require('~/models');
+// Capture module-composition calls before clearMocks resets the spy history.
+const budgetInitializations = [...initializeMessageBudget.mock.calls];
+
+test('Config supplies its actual reader exactly once during composition', () => {
+ expect(budgetInitializations).toEqual([[getAppConfig]]);
+});
describe('invalidateConfigCaches', () => {
beforeEach(() => {
diff --git a/api/server/services/Config/app.js b/api/server/services/Config/app.js
index d67c0f0364..c078e480e1 100644
--- a/api/server/services/Config/app.js
+++ b/api/server/services/Config/app.js
@@ -68,6 +68,9 @@ const { getAppConfig, clearAppConfigCache, clearOverrideCache } = createAppConfi
},
});
+// Config owns the reader; models never import this module to obtain it.
+db.initializeMessageBudget(getAppConfig);
+
/**
* Invalidate all config-related caches after an admin config mutation.
* Clears the base config, per-principal override caches, tool caches,
diff --git a/api/server/services/Config/loadConfigModels.spec.js b/api/server/services/Config/loadConfigModels.spec.js
index 317ab080d3..d391fc85a7 100644
--- a/api/server/services/Config/loadConfigModels.spec.js
+++ b/api/server/services/Config/loadConfigModels.spec.js
@@ -13,6 +13,7 @@ jest.mock('@librechat/data-schemas', () => ({
}));
jest.mock('~/models', () => ({
getUserKeyValues: jest.fn(),
+ initializeMessageBudget: jest.fn(),
}));
const exampleConfig = {
diff --git a/api/server/utils/import/importBatchBuilder.spec.js b/api/server/utils/import/importBatchBuilder.spec.js
index f7a28f54d0..44ec73678a 100644
--- a/api/server/utils/import/importBatchBuilder.spec.js
+++ b/api/server/utils/import/importBatchBuilder.spec.js
@@ -27,6 +27,7 @@ const {
const { ImportBatchBuilder } = require('./importBatchBuilder');
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
bulkIncrementTagCounts: jest.fn(),
bulkSaveConvos: jest.fn(),
bulkSaveMessages: jest.fn(),
diff --git a/api/server/utils/import/importConversations.spec.js b/api/server/utils/import/importConversations.spec.js
index 711939a37d..71b3702344 100644
--- a/api/server/utils/import/importConversations.spec.js
+++ b/api/server/utils/import/importConversations.spec.js
@@ -7,6 +7,7 @@ const { getImporter } = require('./importers');
const importConversations = require('./importConversations');
jest.mock('~/models', () => ({
+ initializeMessageBudget: jest.fn(),
bulkIncrementTagCounts: jest.fn(),
bulkSaveConvos: jest.fn(),
bulkSaveMessages: jest.fn(),
diff --git a/config/__tests__/migrate-shared-link-permissions.spec.js b/config/__tests__/migrate-shared-link-permissions.spec.js
index 246d5e7e97..d9abe321f4 100644
--- a/config/__tests__/migrate-shared-link-permissions.spec.js
+++ b/config/__tests__/migrate-shared-link-permissions.spec.js
@@ -1,6 +1,7 @@
jest.mock('../connect', () => jest.fn().mockResolvedValue(true));
jest.mock('@librechat/api', () => ({
ensureRequiredCollectionsExist: jest.fn().mockResolvedValue(undefined),
+ createMessageBudgetReader: jest.fn(() => ({ initialize: jest.fn(), getBudget: jest.fn() })),
matchModelName: jest.fn(),
findMatchingPattern: jest.fn(),
}));
diff --git a/docs/mcp-apps.md b/docs/mcp-apps.md
index 2d0ff3995e..36c58894ed 100644
--- a/docs/mcp-apps.md
+++ b/docs/mcp-apps.md
@@ -52,6 +52,7 @@ mcpAppSandbox:
maxSourcesPerDirective: 64
maxSerializedLength: 8192
maxPersistedAppBytes: 2097152
+ maxPersistedMessageBytes: 8388608
maxAdmissionRequestsPerMinute: 480
```
@@ -60,9 +61,25 @@ user overrides cannot change them. Apply a limits change across the server and c
then reload open chat pages so host link decisions and newly served sandbox responses use the same
snapshot. Request query parameters contain only the normalized CSP declaration and cannot choose
their own limits. `maxPersistedAppBytes` defaults to 1 MiB and can be raised to at most 4 MiB. It
-bounds each complete App attachment added to a message, rather than the whole message document. An
-oversized full document falls back to a bound URI-only descriptor; if that descriptor is still too
-large, LibreChat omits the optional App artifact while preserving ordinary tool output.
+bounds each complete App attachment added to a message. `maxPersistedMessageBytes` is a separate,
+deployment-only aggregate target for App-bearing messages. It defaults to 12 MiB and accepts positive
+integers up to 12 MiB, leaving headroom below MongoDB's 16 MiB document ceiling. Roles, groups, users,
+and App requests cannot override it.
+
+All full saves, edits, records, imports, and background settlements check the actual candidate when
+it contains bound Apps, including stored fields omitted from the update. A small message-version
+fence makes competing writers retry from the row they actually read. Small text blocks and partial
+background outputs are not exempt. If the target is exceeded, the largest optional App documents
+become bound URI-only descriptors; if descriptors are too large, only optional Apps are omitted.
+Canonical output and unrelated attachments are never trimmed. Canonical-only data may exceed the
+App target, but must still fit the separate storage ceiling (16 MiB minus 16 KiB envelope reserve).
+Existing messages need no schema migration. As with other message upserts, the existing unique
+`(messageId, user, tenantId)` index must be present; the MongoDB regressions create that index too.
+
+Roll out this change to all message writers together before relying on the aggregate bound. An older
+replica does not participate in the version/admission contract and can still write an oversized
+snapshot; mixed-version writes are not protected by this change. Canary's normal authenticated
+same-version deployment remains the supported path.
`maxAdmissionRequestsPerMinute` defaults to 240 and is a shared per-user ceiling across every App
validation, resource, and tool-call route. LibreChat applies it before principal-scoped configuration
diff --git a/packages/api/src/app/service.spec.ts b/packages/api/src/app/service.spec.ts
index 6da766b76a..b8bb615d57 100644
--- a/packages/api/src/app/service.spec.ts
+++ b/packages/api/src/app/service.spec.ts
@@ -3,6 +3,7 @@ import { AppService, getTenantId, tenantStorage, SYSTEM_TENANT_ID } from '@libre
import type { AppConfig } from '@librechat/data-schemas';
import {
createAppConfigService,
+ createMessageBudgetReader,
_resetOverrideStrictCache,
getAppConfigOptionsFromUser,
} from './service';
@@ -1285,3 +1286,33 @@ describe('getAppConfigOptionsFromUser', () => {
});
});
});
+
+describe('message App budget reader composition', () => {
+ it('fails closed before the host supplies the base config reader', async () => {
+ const reader = createMessageBudgetReader();
+ await expect(reader.getBudget()).rejects.toThrow('not been initialized');
+ });
+
+ it('reads deployment-only values lazily and observes reconfiguration without caching', async () => {
+ const reader = createMessageBudgetReader();
+ const getConfig = jest
+ .fn()
+ .mockResolvedValue({ mcpAppSandbox: { maxPersistedMessageBytes: 2 * 1024 * 1024 } });
+ reader.initialize(getConfig);
+ expect(getConfig).not.toHaveBeenCalled();
+ expect(await reader.getBudget()).toBe(2 * 1024 * 1024);
+ expect(getConfig).toHaveBeenLastCalledWith({ baseOnly: true });
+ getConfig.mockResolvedValue({ mcpAppSandbox: { maxPersistedMessageBytes: 4 * 1024 * 1024 } });
+ expect(await reader.getBudget()).toBe(4 * 1024 * 1024);
+ getConfig.mockRejectedValue(new Error('configuration unavailable'));
+ await expect(reader.getBudget()).rejects.toThrow('configuration unavailable');
+ });
+
+ it('keeps independent hosts isolated and leaves an omitted limit to the storage default', async () => {
+ const a = createMessageBudgetReader();
+ const b = createMessageBudgetReader();
+ a.initialize(jest.fn().mockResolvedValue({}));
+ expect(await a.getBudget()).toBeUndefined();
+ await expect(b.getBudget()).rejects.toThrow('not been initialized');
+ });
+});
diff --git a/packages/api/src/app/service.ts b/packages/api/src/app/service.ts
index 069bc766b5..3f0e503963 100644
--- a/packages/api/src/app/service.ts
+++ b/packages/api/src/app/service.ts
@@ -285,6 +285,27 @@ function overrideCacheKey(
return `_OVERRIDE_:${tenant}:${principal}:tenant-v1:${scopeVersion}`;
}
+/**
+ * Per-host late binding for method adapters constructed before the config service. The service
+ * installs its reader during composition; no module-global registry or cached budget is involved.
+ */
+export function createMessageBudgetReader(): {
+ initialize: (reader: (options?: GetAppConfigOptions) => Promise<AppConfig>) => void;
+ getBudget: () => Promise<number | undefined>;
+} {
+ let readConfig: ((options?: GetAppConfigOptions) => Promise<AppConfig>) | undefined;
+ return {
+ initialize(reader) {
+ readConfig = reader;
+ },
+ async getBudget() {
+ if (!readConfig) throw new Error('Message App budget reader has not been initialized');
+ const config = await readConfig({ baseOnly: true });
+ return config.mcpAppSandbox?.maxPersistedMessageBytes;
+ },
+ };
+}
+
// ── Service factory ──────────────────────────────────────────────────
export function createAppConfigService(deps: AppConfigServiceDeps): {
diff --git a/packages/api/src/mcp/MCPManager.ts b/packages/api/src/mcp/MCPManager.ts
index a96710bf39..51e723ce02 100644
--- a/packages/api/src/mcp/MCPManager.ts
+++ b/packages/api/src/mcp/MCPManager.ts
@@ -2000,21 +2000,27 @@ Please follow these instructions when using tools from the respective MCP server
}
if (!resolvedAppResource) {
logger.warn(
- `[MCP][${serverName}][${toolName}] App resource "${resourceUri}" did not return usable App content; preserving tool result`,
+ `[MCP][${serverName}][${toolName}] App resource "${resourceUri}" did not return usable App content; retaining bound URI for a later read`,
);
- resourceMeta = undefined;
}
} catch (error) {
if (!options?.signal?.aborted) {
logger.warn(
- `[MCP][${serverName}][${toolName}] Could not resolve App resource "${resourceUri}"; preserving tool result`,
+ `[MCP][${serverName}][${toolName}] Could not resolve App resource "${resourceUri}"; retaining bound URI for a later read`,
error,
);
}
- resourceMeta = undefined;
+ if (options?.signal?.aborted) {
+ resourceMeta = undefined;
+ }
}
}
+ if (options?.signal?.aborted) {
+ resourceMeta = undefined;
+ resolvedAppResource = undefined;
+ }
+
const serverBinding =
resourceMeta && connection && checkedOutTarget && userId && this.appBindingCodec
? this.appBindingCodec.create(
diff --git a/packages/api/src/mcp/__tests__/MCPManager.test.ts b/packages/api/src/mcp/__tests__/MCPManager.test.ts
index 5ee264ceea..cf6e6beee2 100644
--- a/packages/api/src/mcp/__tests__/MCPManager.test.ts
+++ b/packages/api/src/mcp/__tests__/MCPManager.test.ts
@@ -1120,7 +1120,7 @@ describe('MCPManager', () => {
expect(app?.content).toBe(toolResult.content);
});
- it('keeps canonical tool output without an App artifact when document reading fails', async () => {
+ it('keeps canonical tool output and a bound retryable URI when document reading fails', async () => {
const request = jest.fn(async ({ method }: { method: string }) => {
if (method === 'tools/call') {
return toolResult;
@@ -1131,12 +1131,37 @@ describe('MCPManager', () => {
const [text, artifacts] = await callWith(connectionFor(request));
expect(text).toContain('ordinary output');
- expect(artifacts?.ui_resources).toBeUndefined();
+ expect(artifacts?.ui_resources?.data).toEqual([
+ expect.objectContaining({
+ uri: resourceUri,
+ mimeType: 'text/html;profile=mcp-app',
+ serverBinding: 'binding',
+ content: toolResult.content,
+ }),
+ ]);
+ expect(artifacts?.ui_resources?.data?.[0]).not.toHaveProperty('text');
expect(
request.mock.calls.filter(([request]) => request.method === 'tools/call'),
).toHaveLength(1);
});
+ it('retains the bound URI if the read returns no usable matching App document', async () => {
+ const request = jest.fn(async ({ method }: { method: string }) =>
+ method === 'tools/call'
+ ? toolResult
+ : { contents: [{ uri: resourceUri, mimeType: 'text/plain', text: 'not an app' }] },
+ );
+ const [text, artifacts] = await callWith(connectionFor(request));
+ expect(text).toContain('ordinary output');
+ expect(artifacts?.ui_resources?.data?.[0]).toMatchObject({
+ uri: resourceUri,
+ serverBinding: 'binding',
+ content: toolResult.content,
+ });
+ expect(artifacts?.ui_resources?.data?.[0]?.text).toBeUndefined();
+ expect(request.mock.calls.filter(([call]) => call.method === 'tools/call')).toHaveLength(1);
+ });
+
it('does not read or attach the App when Apps policy denies it', async () => {
const request = jest.fn().mockResolvedValue(toolResult);
const connection = connectionFor(request);
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 5825e23a78..e1be70b786 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -2012,6 +2012,7 @@ describe('MCP Apps configuration', () => {
expect(configSchema.parse({ version: '1.2.1' }).mcpAppSandbox).toEqual({
...DEFAULT_MCP_APP_CSP_LIMITS,
maxPersistedAppBytes: DEFAULT_MCP_APP_PERSISTED_BYTES,
+ maxPersistedMessageBytes: 12 * 1024 * 1024,
maxAdmissionRequestsPerMinute: DEFAULT_MCP_APP_ADMISSION_REQUESTS_PER_MINUTE,
});
expect(
@@ -2021,6 +2022,7 @@ describe('MCP Apps configuration', () => {
maxSourcesPerDirective: 64,
maxSerializedLength: 8192,
maxPersistedAppBytes: 2048,
+ maxPersistedMessageBytes: 1024 * 1024,
maxAdmissionRequestsPerMinute: 480,
url: 'https://mcp-sandbox.example.com/api/mcp/sandbox',
},
@@ -2029,6 +2031,7 @@ describe('MCP Apps configuration', () => {
maxSourcesPerDirective: 64,
maxSerializedLength: 8192,
maxPersistedAppBytes: 2048,
+ maxPersistedMessageBytes: 1024 * 1024,
maxAdmissionRequestsPerMinute: 480,
url: 'https://mcp-sandbox.example.com/api/mcp/sandbox',
});
@@ -2038,6 +2041,9 @@ describe('MCP Apps configuration', () => {
{ maxSerializedLength: -1 },
{ maxSerializedLength: 1.5 },
{ maxSerializedLength: Number.MAX_SAFE_INTEGER + 1 },
+ { maxPersistedMessageBytes: 0 },
+ { maxPersistedMessageBytes: 1.5 },
+ { maxPersistedMessageBytes: 12 * 1024 * 1024 + 1 },
{ maxPersistedAppBytes: 0 },
{ maxPersistedAppBytes: 1.5 },
{ maxPersistedAppBytes: MAX_MCP_APP_PERSISTED_BYTES + 1 },
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 8f1216d905..604000d949 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -2636,6 +2636,9 @@ export type TMCPAppsPolicy = {
sandboxUrl?: string;
};
+/** Aggregate App-bearing message target; cannot exceed the safe storage ceiling. */
+export const DEFAULT_MCP_APP_MESSAGE_BYTES: number = 12 * 1024 * 1024;
+export const MAX_MCP_APP_MESSAGE_BYTES: number = 12 * 1024 * 1024;
export const DEFAULT_MCP_APP_PERSISTED_BYTES = 1024 * 1024;
export const MAX_MCP_APP_PERSISTED_BYTES = 4 * 1024 * 1024;
export const DEFAULT_MCP_APP_ADMISSION_REQUESTS_PER_MINUTE = 240;
@@ -3329,6 +3332,12 @@ export const configSchema = z.object({
.positive()
.max(MAX_MCP_APP_PERSISTED_BYTES)
.default(DEFAULT_MCP_APP_PERSISTED_BYTES),
+ maxPersistedMessageBytes: z
+ .number()
+ .int()
+ .positive()
+ .max(MAX_MCP_APP_MESSAGE_BYTES)
+ .default(DEFAULT_MCP_APP_MESSAGE_BYTES),
maxAdmissionRequestsPerMinute: z
.number()
.int()
diff --git a/packages/data-schemas/src/app/resolution.spec.ts b/packages/data-schemas/src/app/resolution.spec.ts
index a41ff0718a..00d040548f 100644
--- a/packages/data-schemas/src/app/resolution.spec.ts
+++ b/packages/data-schemas/src/app/resolution.spec.ts
@@ -82,6 +82,7 @@ describe('mergeConfigOverrides', () => {
maxSourcesPerDirective: 64,
maxSerializedLength: 8192,
maxAdmissionRequestsPerMinute: 480,
+ maxPersistedMessageBytes: 123456,
},
} as unknown as AppConfig;
const configs = [
@@ -92,6 +93,7 @@ describe('mergeConfigOverrides', () => {
maxSourcesPerDirective: 128,
maxSerializedLength: 16384,
maxAdmissionRequestsPerMinute: 960,
+ maxPersistedMessageBytes: 200000,
},
},
10,
diff --git a/packages/data-schemas/src/methods/appSnapshots.ts b/packages/data-schemas/src/methods/appSnapshots.ts
new file mode 100644
index 0000000000..20f3fbc0c5
--- /dev/null
+++ b/packages/data-schemas/src/methods/appSnapshots.ts
@@ -0,0 +1,118 @@
+import mongoose from 'mongoose';
+import {
+ Tools,
+ isMcpAppMimeType,
+ DEFAULT_MCP_APP_MESSAGE_BYTES,
+ MAX_MCP_APP_MESSAGE_BYTES,
+} from 'librechat-data-provider';
+
+/** Leave 4 MiB for timestamps, metadata, later receipts and other non-App message fields. */
+export const MAX_MCP_APP_MESSAGE_BSON_BYTES: number = DEFAULT_MCP_APP_MESSAGE_BYTES;
+/** Separate canonical-only ceiling; an App target must not reject otherwise persistable text. */
+const CANONICAL_MESSAGE_BSON_BYTES = 16 * 1024 * 1024 - 16 * 1024;
+
+type Resource = Record<string, unknown>;
+type Attachment = Record<string, unknown>;
+
+function isBoundAppResource(value: unknown): value is Resource {
+ if (value == null || typeof value !== 'object' || Array.isArray(value)) return false;
+ const resource = value as Resource;
+ return (
+ typeof resource.uri === 'string' &&
+ typeof resource.serverBinding === 'string' &&
+ typeof resource.mimeType === 'string' &&
+ isMcpAppMimeType(resource.mimeType)
+ );
+}
+
+function appResources(attachment: unknown): unknown[] | undefined {
+ if (attachment == null || typeof attachment !== 'object' || Array.isArray(attachment)) return;
+ const value = attachment as Attachment;
+ return value.type === Tools.ui_resources && Array.isArray(value[Tools.ui_resources])
+ ? value[Tools.ui_resources]
+ : undefined;
+}
+
+export function hasBoundAppSnapshots(attachments: unknown): boolean {
+ return (
+ Array.isArray(attachments) &&
+ attachments.some((attachment) => appResources(attachment)?.some(isBoundAppResource))
+ );
+}
+
+/** Preserve result, arguments, URI, identity and binding; remove only the optional View document. */
+function uriOnly(resource: Resource): Resource {
+ const descriptor = { ...resource };
+ delete descriptor.text;
+ delete descriptor.blob;
+ delete descriptor.csp;
+ delete descriptor.permissions;
+ delete descriptor._meta;
+ return descriptor;
+}
+
+/**
+ * Called only for messages containing a bound App. The caller supplies BSON size of the ENTIRE
+ * candidate document, not just its attachments. Work on copies, so a later full-row save with the
+ * original in-memory attachments cannot sneak an oversized document back into storage.
+ *
+ * Estimates are used only to pick the largest documents to drop first. The final BSON calculation
+ * is exact; if the candidate still exceeds the budget we omit all optional Apps or fail explicitly
+ * when the canonical message / non-App attachments alone are too large.
+ */
+export function fitBoundAppSnapshots(
+ attachments: unknown[],
+ bsonSize: (attachments: unknown[]) => number,
+ maxBytes: number = MAX_MCP_APP_MESSAGE_BSON_BYTES,
+): unknown[] {
+ if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_MCP_APP_MESSAGE_BYTES) {
+ throw new Error('Invalid deployment MCP App message budget');
+ }
+ const size = bsonSize(attachments);
+ if (size <= maxBytes) return attachments;
+
+ const result: unknown[] = attachments.slice();
+ const changes: Array<{ attachment: number; resource: number; saving: number }> = [];
+ for (let i = 0; i < attachments.length; i++) {
+ const resources = appResources(attachments[i]);
+ if (!resources) continue;
+ for (let j = 0; j < resources.length; j++) {
+ const resource = resources[j];
+ if (!isBoundAppResource(resource)) continue;
+ const descriptor = uriOnly(resource);
+ const saving =
+ mongoose.mongo.BSON.calculateObjectSize({ resource }) -
+ mongoose.mongo.BSON.calculateObjectSize({ resource: descriptor });
+ changes.push({ attachment: i, resource: j, saving });
+ }
+ }
+ changes.sort((a, b) => b.saving - a.saving);
+
+ let remaining = size;
+ for (const { attachment, resource, saving } of changes) {
+ if (remaining <= maxBytes) break;
+ if (saving <= 0) continue;
+ const original = result[attachment] as Attachment;
+ const resources = appResources(original);
+ if (!resources) continue;
+ const next = resources.slice();
+ next[resource] = uriOnly(next[resource] as Resource);
+ result[attachment] = { ...original, [Tools.ui_resources]: next };
+ remaining -= saving;
+ }
+ if (bsonSize(result) <= maxBytes) return result;
+
+ // The descriptor can itself contain a large tool result or args. Remove only bound Apps;
+ // ordinary/legacy resources and unrelated attachments are never sacrificed.
+ for (let i = 0; i < result.length; i++) {
+ const original = result[i] as Attachment;
+ const resources = appResources(original);
+ if (!resources?.some(isBoundAppResource)) continue;
+ const keep = resources.filter((value) => !isBoundAppResource(value));
+ result[i] = keep.length ? { ...original, [Tools.ui_resources]: keep } : null;
+ }
+ const withoutApps = result.filter((attachment) => attachment != null);
+ if (bsonSize(withoutApps) <= CANONICAL_MESSAGE_BSON_BYTES) return withoutApps;
+
+ throw new Error('Message exceeds the BSON budget without optional MCP App snapshots');
+}
diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.ts
index a8f1abcf1d..0a8238951a 100644
--- a/packages/data-schemas/src/methods/index.ts
+++ b/packages/data-schemas/src/methods/index.ts
@@ -287,6 +287,8 @@ export interface CreateMethodsDeps {
removeAllPermissions?: (params: { resourceType: string; resourceId: unknown }) => Promise<void>;
/** Returns a cache store for the given key. From getLogStores. */
getCache?: RoleDeps['getCache'];
+ /** Resolves only the base deployment's aggregate MCP App persistence limit. */
+ getMCPAppMessageBudget?: () => Promise<number | undefined>;
/** Recognizes agent skill IDs supplied by an external, non-database registry. */
isExternalSkillId?: AgentDeps['isExternalSkillId'];
}
@@ -319,7 +321,9 @@ export function createMethods(
createStructuredTransaction: transactionMethods.createStructuredTransaction,
});
- const messageMethods = createMessageMethods(mongoose);
+ const messageMethods = createMessageMethods(mongoose, {
+ getMCPAppMessageBudget: deps.getMCPAppMessageBudget,
+ });
const agentQueuedTurnMethods = createAgentQueuedTurnMethods(mongoose);
const agentTriggerDeliveryMethods = createAgentTriggerDeliveryMethods(mongoose, {
diff --git a/packages/data-schemas/src/methods/message.spec.ts b/packages/data-schemas/src/methods/message.spec.ts
index 85353eb6e3..73a0269589 100644
--- a/packages/data-schemas/src/methods/message.spec.ts
+++ b/packages/data-schemas/src/methods/message.spec.ts
@@ -1,7 +1,13 @@
import mongoose from 'mongoose';
import { v4 as uuidv4 } from 'uuid';
import { MongoMemoryServer } from 'mongodb-memory-server';
-import { backgroundResultMetadata, Constants, RetentionMode } from 'librechat-data-provider';
+import {
+ backgroundResultMetadata,
+ Constants,
+ RetentionMode,
+ Tools,
+ MCP_APP_MIME_TYPE,
+} from 'librechat-data-provider';
import type { AppConfig, IMessage } from '..';
import {
createMessageMethods,
@@ -11,6 +17,7 @@ import {
SUBAGENT_TRANSCRIPT_SOURCE_BYTE_LIMIT,
} from './message';
import { tenantStorage, runAsSystem } from '~/config/tenantContext';
+import { MAX_MCP_APP_MESSAGE_BSON_BYTES } from './appSnapshots';
import { createModels } from '../models';
import logger from '~/config/winston';
@@ -100,6 +107,7 @@ beforeAll(async () => {
releaseBackgroundToolResultClaims = methods.releaseBackgroundToolResultClaims;
await mongoose.connect(mongoUri);
+ await Message.createIndexes();
});
afterAll(async () => {
@@ -108,6 +116,12 @@ afterAll(async () => {
});
describe('Message Operations', () => {
+ it('constructs message methods before the host registers models', () => {
+ const unregistered = new mongoose.Mongoose();
+ expect(unregistered.models.Message).toBeUndefined();
+ expect(() => createMessageMethods(unregistered as unknown as typeof mongoose)).not.toThrow();
+ });
+
let mockCtx: {
userId: string;
isTemporary?: boolean;
@@ -143,7 +157,433 @@ describe('Message Operations', () => {
};
});
+ const appAttachment = (i: number, bytes: number, toolCallId = 'call_bg') => ({
+ type: Tools.ui_resources,
+ file_id: `app-${i}`,
+ toolCallId,
+ [Tools.ui_resources]: [
+ {
+ uri: `ui://app/${i}`,
+ mimeType: MCP_APP_MIME_TYPE,
+ serverName: 'server',
+ serverBinding: 'authenticated-binding',
+ resourceId: `resource-${i}`,
+ toolName: 'show_app',
+ content: [{ type: 'text', text: 'canonical' }],
+ text: 'x'.repeat(bytes),
+ },
+ ],
+ });
+
+ describe('App admission across writers', () => {
+ it('rebudgets aggregate sub-megabyte blocks on content-only saves', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ attachments: Array.from({ length: 11 }, (_, i) =>
+ appAttachment(i, 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ const content = Array.from({ length: 10 }, () => ({
+ type: 'text',
+ text: 'x'.repeat(700_000),
+ }));
+ await saveMessage(mockCtx, { ...mockMessageData, content, attachments: undefined });
+ const row = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(row?.content).toEqual(content);
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ }, 60000);
+
+ it('rebudgets every sub-megabyte settle without a new attachment', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content: Array.from({ length: 8 }, (_, i) => ({
+ type: 'tool_call',
+ tool_call: { id: `call-${i}`, output: 'pending' },
+ })),
+ attachments: Array.from({ length: 11 }, (_, i) =>
+ appAttachment(i, 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ for (let i = 0; i < 8; i++) {
+ expect(
+ (
+ await updateToolCallResult({
+ userId: 'user123',
+ messageId: 'msg123',
+ conversationId: mockMessageData.conversationId as string,
+ toolCallId: `call-${i}`,
+ output: 'x'.repeat(900_000),
+ })
+ ).matched,
+ ).toBe(true);
+ const row = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(row?.attachments).toHaveLength(11);
+ }
+ }, 60000);
+
+ it('never propagates caller tenantId through a budget callback or provenance save', async () => {
+ await tenantStorage.run({ tenantId: 'real-tenant' }, async () => {
+ const result = await saveMessage(mockCtx, {
+ ...mockMessageData,
+ tenantId: 'evil-tenant',
+ userSubmittedPaths: ['/text'],
+ attachments: [appAttachment(0, 4096)] as unknown as IMessage['attachments'],
+ });
+ expect(result?.tenantId).toBe('real-tenant');
+ });
+ const row = await runAsSystem(() => Message.findOne({ messageId: 'msg123' }).lean());
+ expect(row?.tenantId).toBe('real-tenant');
+ expect(row?.attachments).toHaveLength(1);
+ });
+
+ it('preserves omitted attachments from the retried row, not a stale preliminary read', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content: [{ type: 'tool_call', tool_call: { id: 'call_bg', output: 'pending' } }],
+ attachments: [appAttachment(0, 4096)] as unknown as IMessage['attachments'],
+ });
+ const original = Message.findOneAndUpdate.bind(Message);
+ let inject = true;
+ const spy = jest.spyOn(Message, 'findOneAndUpdate').mockImplementation((...args) => {
+ const query = original(...args);
+ const execute = query.exec.bind(query);
+ query.exec = async () => {
+ if (inject && (args[0] as Record<string, unknown>)?.__v != null) {
+ inject = false;
+ await updateToolCallResult({
+ userId: 'user123',
+ messageId: 'msg123',
+ conversationId: mockMessageData.conversationId as string,
+ toolCallId: 'call_bg',
+ attachments: [appAttachment(1, 4096)],
+ });
+ }
+ return execute();
+ };
+ return query;
+ });
+ try {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ text: 'x'.repeat(1024 * 1024 + 1),
+ attachments: undefined,
+ });
+ } finally {
+ spy.mockRestore();
+ }
+ const row = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(inject).toBe(false);
+ expect(row?.attachments?.map((x) => (x as { file_id: string }).file_id).sort()).toEqual([
+ 'app-0',
+ 'app-1',
+ ]);
+ });
+
+ it('treats undefined private fields as omissions exactly as MongoDB does', async () => {
+ await saveMessage(mockCtx, mockMessageData);
+ const subagentTranscript = {
+ taskId: 'private',
+ mode: 'append',
+ messagesJson: 'p'.repeat(5 * 1024 * 1024),
+ };
+ await Message.updateOne({ messageId: 'msg123' }, { $set: { subagentTranscript } });
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ subagentTranscript: undefined,
+ attachments: Array.from({ length: 9 }, (_, i) =>
+ appAttachment(i, 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ const row = await Message.findOne({ messageId: 'msg123' })
+ .select('+subagentTranscript')
+ .lean();
+ expect(row?.subagentTranscript).toEqual(subagentTranscript);
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ }, 60000);
+
+ it.each([
+ ['part agent wins', 'mine', 'other', true],
+ ['different part agent wins', 'other', 'mine', false],
+ ['nested agent fallback', undefined, 'other', false],
+ ['legacy wildcard', undefined, undefined, true],
+ ])('sizes only parts actually updated: %s', async (_name, partAgent, callAgent, matches) => {
+ const content = [
+ { type: 'tool_call', agentId: 'mine', tool_call: { id: 'call_bg', output: 'pending' } },
+ {
+ type: 'tool_call',
+ ...(partAgent != null && { agentId: partAgent }),
+ tool_call: { id: 'call_bg', agentId: callAgent, output: 'p'.repeat(850_000) },
+ },
+ ];
+ let configReads = 0;
+ const methods = createMessageMethods(mongoose, {
+ getMCPAppMessageBudget: async () => {
+ configReads++;
+ return 1024 * 1024;
+ },
+ });
+ await methods.saveMessage(mockCtx, {
+ ...mockMessageData,
+ content,
+ attachments: [appAttachment(0, 150_000)] as unknown as IMessage['attachments'],
+ });
+ const result = await methods.updateToolCallResult({
+ userId: 'user123',
+ messageId: 'msg123',
+ conversationId: mockMessageData.conversationId as string,
+ toolCallId: 'call_bg',
+ agentId: 'mine',
+ output: 'x'.repeat(300_000),
+ });
+ expect(result.matched).toBe(true);
+ const row = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(row?.content?.[1]).toMatchObject({
+ tool_call: { output: matches ? 'x'.repeat(300_000) : 'p'.repeat(850_000) },
+ });
+ const ui = (row?.attachments?.[0] as { ui_resources: Array<{ text?: string }> } | undefined)
+ ?.ui_resources;
+ if (matches) expect(ui?.[0].text).toBeDefined();
+ else expect(ui).toBeUndefined(); // Canonical-only may exceed the App target, never the storage ceiling.
+ expect(configReads).toBeGreaterThan(0);
+ });
+
+ it.each(['record', 'edit', 'bulk', 'text'] as const)(
+ 'applies the same configurable limit through the %s writer',
+ async (writer) => {
+ const methods = createMessageMethods(mongoose, {
+ getMCPAppMessageBudget: async () => 150_000,
+ });
+ const base = {
+ ...mockMessageData,
+ attachments: [appAttachment(0, 100_000)] as unknown as IMessage['attachments'],
+ };
+ await methods.saveMessage(mockCtx, base);
+ const text = 'result'.repeat(15_000);
+ if (writer === 'record')
+ await methods.recordMessage({
+ conversationId: mockMessageData.conversationId,
+ user: 'user123',
+ messageId: 'msg123',
+ text,
+ });
+ if (writer === 'edit')
+ await methods.updateMessage('user123', { messageId: 'msg123', text });
+ if (writer === 'bulk')
+ await methods.bulkSaveMessages([{ ...mockMessageData, user: 'user123', text }]);
+ if (writer === 'text')
+ await methods.updateMessageText('user123', { messageId: 'msg123', text });
+ const row = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(row?.text).toBe(text);
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(150_000);
+ expect(
+ (row?.attachments?.[0] as { ui_resources: Array<{ text?: string }> }).ui_resources[0]
+ .text,
+ ).toBeUndefined();
+ },
+ );
+
+ it('preserves bulk import counts and timestamps across ordinary and App-bearing rows', async () => {
+ const methods = createMessageMethods(mongoose, {
+ getMCPAppMessageBudget: async () => 80_000,
+ });
+ const createdAt = new Date('2020-01-01T00:00:00Z');
+ const messages = [
+ { ...mockMessageData, messageId: 'normal', createdAt },
+ {
+ ...mockMessageData,
+ messageId: 'app',
+ createdAt,
+ attachments: [appAttachment(0, 100_000)] as unknown as IMessage['attachments'],
+ },
+ ];
+ const created = await methods.bulkSaveMessages(messages, true);
+ expect(created).toMatchObject({ upsertedCount: 2, modifiedCount: 0 });
+ const modified = await methods.bulkSaveMessages(messages, true);
+ expect(modified).toMatchObject({ upsertedCount: 0, modifiedCount: 2, matchedCount: 2 });
+ const row = await Message.findOne({ messageId: 'app' }).lean();
+ expect(row?.createdAt).toEqual(createdAt);
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(80_000);
+ });
+
+ it('keeps newer-producer fields in the whole BSON estimate without dropping them', async () => {
+ await saveMessage(mockCtx, mockMessageData);
+ await Message.collection.updateOne(
+ { messageId: 'msg123' },
+ { $set: { futurePayload: 'x'.repeat(5 * 1024 * 1024) } },
+ );
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ attachments: Array.from({ length: 9 }, (_, i) =>
+ appAttachment(i, 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ const row = await Message.collection.findOne({ messageId: 'msg123' });
+ expect(row?.futurePayload.length).toBe(5 * 1024 * 1024);
+ expect(mongoose.mongo.BSON.calculateObjectSize(row!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ }, 60000);
+
+ it('does not resolve App configuration or read a full row on ordinary saves', async () => {
+ const getMCPAppMessageBudget = jest.fn();
+ const methods = createMessageMethods(mongoose, { getMCPAppMessageBudget });
+ const read = jest.spyOn(Message, 'findOne');
+ try {
+ await methods.saveMessage(mockCtx, mockMessageData);
+ await methods.saveMessage(mockCtx, { ...mockMessageData, text: 'updated' });
+ expect(read).not.toHaveBeenCalled();
+ expect(getMCPAppMessageBudget).not.toHaveBeenCalled();
+ } finally {
+ read.mockRestore();
+ }
+ });
+ });
+
describe('saveMessage', () => {
+ it('bounds aggregate App BSON without changing canonical output, even on a later full save', async () => {
+ const content = [{ type: 'text', text: 'canonical message' }];
+ const attachments = Array.from({ length: 17 }, (_, i) =>
+ appAttachment(i, 1024 * 1024 - 2048),
+ );
+ for (let attempt = 0; attempt < 2; attempt++) {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content,
+ attachments: attachments as unknown as IMessage['attachments'],
+ });
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ const apps =
+ stored?.attachments?.flatMap(
+ (attachment) =>
+ (
+ attachment as {
+ [Tools.ui_resources]: Array<{ text?: string; serverBinding?: string }>;
+ }
+ )[Tools.ui_resources],
+ ) ?? [];
+ expect(apps).toHaveLength(17);
+ expect(apps.some((app) => app.text === undefined)).toBe(true);
+ expect(apps.every((app) => app.serverBinding === 'authenticated-binding')).toBe(true);
+ expect(stored?.content).toEqual(content);
+ }
+ }, 60000);
+
+ it('re-budgets retained Apps when a later save omits attachments and grows canonical text', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ attachments: Array.from({ length: 3 }, (_, i) =>
+ appAttachment(i, 3 * 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ const text = 'model answer '.repeat(420_000);
+ await saveMessage(mockCtx, { ...mockMessageData, text, attachments: undefined });
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(stored?.text).toBe(text);
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(stored?.attachments).toHaveLength(3);
+ expect(
+ stored?.attachments?.some((attachment) =>
+ (attachment as { [Tools.ui_resources]: Array<{ text?: string }> })[
+ Tools.ui_resources
+ ].some((resource) => resource.text === undefined),
+ ),
+ ).toBe(true);
+ }, 60000);
+
+ it('omits only oversized bound Apps, never legacy UI or canonical message text', async () => {
+ const original = appAttachment(1, 4 * 1024 * 1024);
+ const legacy = { uri: 'ui://legacy', mimeType: 'text/html', text: '<p>legacy</p>' };
+ const canonical = 'ordinary output '.repeat(420_000);
+ const attachment = {
+ ...original,
+ [Tools.ui_resources]: [
+ { ...original[Tools.ui_resources][0], content: [{ type: 'text', text: canonical }] },
+ legacy,
+ ],
+ };
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ text: canonical,
+ attachments: [
+ attachment,
+ { file_id: 'ordinary-file' },
+ ] as unknown as IMessage['attachments'],
+ });
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(stored?.text).toBe(canonical);
+ expect(stored?.attachments).toEqual([
+ expect.objectContaining({ [Tools.ui_resources]: [legacy] }),
+ { file_id: 'ordinary-file' },
+ ]);
+ }, 60000);
+
+ it('accounts for server-private message fields that the chat projection omits', async () => {
+ await saveMessage(mockCtx, mockMessageData);
+ await Message.updateOne(
+ { messageId: 'msg123' },
+ {
+ $set: {
+ subagentTranscript: {
+ taskId: 'private-task',
+ mode: 'append',
+ messagesJson: 'p'.repeat(4 * 1024 * 1024),
+ },
+ },
+ },
+ );
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ attachments: Array.from({ length: 9 }, (_, i) =>
+ appAttachment(i, 1024 * 1024 - 2048),
+ ) as unknown as IMessage['attachments'],
+ });
+ const stored = await Message.findOne({ messageId: 'msg123' })
+ .select('+subagentTranscript')
+ .lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ const apps =
+ stored?.attachments?.flatMap(
+ (item) =>
+ (item as { [Tools.ui_resources]: Array<{ text?: string }> })[Tools.ui_resources],
+ ) ?? [];
+ expect(apps).toHaveLength(9);
+ expect(apps.some((item) => item.text === undefined)).toBe(true);
+ }, 60000);
+
+ it('applies the same App budget when merging user-submitted provenance', async () => {
+ const attachments = Array.from({ length: 17 }, (_, i) =>
+ appAttachment(i, 1024 * 1024 - 2048),
+ );
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content: [{ type: 'steer', text: 'user-authored' }],
+ attachments: attachments as unknown as IMessage['attachments'],
+ });
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(stored?.content?.[0]).toMatchObject({ type: 'steer', text: 'user-authored' });
+ expect(stored?.userSubmittedPaths).toContain('/content/0');
+ }, 60000);
+
it('should save a message for an authenticated user', async () => {
const result = await saveMessage(mockCtx, mockMessageData);
@@ -821,6 +1261,67 @@ describe('Message Operations', () => {
});
describe('updateToolCallResult', () => {
+ it('preserves a large canonical background result by downgrading existing App HTML', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content: [
+ { type: 'tool_call', tool_call: { id: 'call_bg', name: 'show_app', output: 'pending' } },
+ ],
+ attachments: Array.from({ length: 3 }, (_, i) =>
+ appAttachment(i, 3 * 1024 * 1024),
+ ) as unknown as IMessage['attachments'],
+ });
+ const largeOutput = 'result '.repeat(700_000);
+ const patched = await updateToolCallResult({
+ userId: 'user123',
+ messageId: 'msg123',
+ conversationId: mockMessageData.conversationId as string,
+ toolCallId: 'call_bg',
+ output: largeOutput,
+ });
+ expect(patched.matched).toBe(true);
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(stored?.content?.[0]).toMatchObject({ tool_call: { output: largeOutput } });
+ expect(
+ stored?.attachments?.some((attachment) =>
+ (attachment as { [Tools.ui_resources]: Array<{ text?: string }> })[
+ Tools.ui_resources
+ ].some((resource) => resource.text === undefined),
+ ),
+ ).toBe(true);
+ }, 60000);
+
+ it('serializes concurrent App attachment settlements under the shared BSON budget', async () => {
+ await saveMessage(mockCtx, {
+ ...mockMessageData,
+ content: [
+ { type: 'tool_call', tool_call: { id: 'call_bg', name: 'show_app', output: 'pending' } },
+ ],
+ });
+ const patch = (i: number) =>
+ updateToolCallResult({
+ userId: 'user123',
+ messageId: 'msg123',
+ conversationId: mockMessageData.conversationId as string,
+ toolCallId: 'call_bg',
+ output: 'canonical result',
+ attachments: [appAttachment(i, 3 * 1024 * 1024)],
+ });
+ const settled = await Promise.all(Array.from({ length: 5 }, (_, i) => patch(i)));
+ expect(settled.every((item) => item.matched)).toBe(true);
+ const stored = await Message.findOne({ messageId: 'msg123' }).lean();
+ expect(mongoose.mongo.BSON.calculateObjectSize(stored!)).toBeLessThanOrEqual(
+ MAX_MCP_APP_MESSAGE_BSON_BYTES,
+ );
+ expect(stored?.attachments).toHaveLength(5);
+ expect(stored?.content?.[0]).toMatchObject({ tool_call: { output: 'canonical result' } });
+ await patch(0);
+ expect((await Message.findOne({ messageId: 'msg123' }).lean())?.attachments).toHaveLength(5);
+ }, 60000);
+
const toolCallContent = () => [
{ type: 'text', text: 'intro' },
{
diff --git a/packages/data-schemas/src/methods/message.ts b/packages/data-schemas/src/methods/message.ts
index 1799b90e57..3c0688a929 100644
--- a/packages/data-schemas/src/methods/message.ts
+++ b/packages/data-schemas/src/methods/message.ts
@@ -10,6 +10,7 @@ import type { SchemaWithMeiliMethods } from '~/models/plugins/mongoMeili';
import type { AppConfig, IConversation, IMessage } from '~/types';
import { createChatExpirationDate, createTempChatExpirationDate } from '~/utils/tempChatRetention';
import { activeExpirationFilter, createFallbackRetentionDate } from '~/utils/retention';
+import { fitBoundAppSnapshots, hasBoundAppSnapshots } from './appSnapshots';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import logger from '~/config/winston';
@@ -269,6 +270,18 @@ function getSteerUserSubmittedPaths(content: unknown): string[] {
return paths;
}
+/** Mongoose omits undefined $set values. Strip identity/version inputs before any sizing callback. */
+function sanitizeMessageUpdate(update: Record<string, unknown>): Record<string, unknown> {
+ return Object.fromEntries(
+ Object.entries(update).filter(
+ ([key, value]) => value !== undefined && !['_id', 'tenantId', '__v'].includes(key),
+ ),
+ );
+}
+
+/** Conservatively admit any server-bound resource to the slow path, including legacy MIME forms. */
+const NO_BOUND_APPS = { 'attachments.ui_resources.serverBinding': { $exists: false } };
+
/**
* A terminal save that must drop a stored `contextMeta` unsets it in the same
* update that persists the response, so no failure between two writes can
@@ -282,15 +295,9 @@ function buildMessageSaveUpdate(
retentionOnInsert?: { expiredAt: Date; isTemporary: false };
},
): UpdateQuery<IMessage> {
- if (
- !options.stampModelOutputOnInsert &&
- !options.unsetContextMeta &&
- options.retentionOnInsert == null
- ) {
- return update;
- }
return {
$set: update,
+ $inc: { __v: 1 },
...((options.stampModelOutputOnInsert || options.retentionOnInsert != null) && {
$setOnInsert: {
...(options.stampModelOutputOnInsert && { isUserSubmitted: false }),
@@ -312,11 +319,16 @@ async function findOneAndMergeMessageProvenance(
stampModelOutputOnInsert?: boolean;
unsetContextMeta?: boolean;
retentionOnInsert?: { expiredAt: Date; isTemporary: false };
+ prepareAppUpdate?: (
+ current: Record<string, unknown> | null,
+ update: Record<string, unknown>,
+ ) => Promise<Record<string, unknown>>;
+ timestamps?: boolean;
+ privateMessagePaths?: string;
+ onWrite?: (inserted: boolean, id: unknown) => void;
},
) {
- const safeUpdate = { ...update };
- delete safeUpdate._id;
- delete safeUpdate.tenantId;
+ const safeUpdate = sanitizeMessageUpdate(update);
const preservesStoredIsUserSubmitted = !Object.prototype.hasOwnProperty.call(
safeUpdate,
'isUserSubmitted',
@@ -325,13 +337,25 @@ async function findOneAndMergeMessageProvenance(
/** A small optimistic loop keeps the merge atomic while using only classic update operators. */
for (let attempt = 0; attempt < MAX_PROVENANCE_CAS_ATTEMPTS; attempt += 1) {
const current = await Message.findOne(identity)
- .select({
- isUserSubmitted: 1,
- userSubmittedPaths: 1,
- userSubmittedMessageFieldPaths: 1,
- _id: 0,
- })
- .lean<MessageProvenance | null>();
+ .select(
+ options.prepareAppUpdate
+ ? (options.privateMessagePaths ?? '')
+ : {
+ isUserSubmitted: 1,
+ userSubmittedPaths: 1,
+ userSubmittedMessageFieldPaths: 1,
+ _id: 0,
+ },
+ )
+ .lean<
+ | (MessageProvenance & {
+ _id?: Types.ObjectId;
+ attachments?: unknown[];
+ content?: unknown[];
+ __v?: number;
+ })
+ | null
+ >();
if (current == null && !options.upsert) {
return null;
}
@@ -347,20 +371,32 @@ async function findOneAndMergeMessageProvenance(
const filter = {
...identity,
...(current == null ? getMissingProvenanceFilter() : getProvenanceSnapshotFilter(current)),
+ ...(options.prepareAppUpdate &&
+ (current != null
+ ? {
+ _id: current._id,
+ __v: current.__v ?? null,
+ }
+ : { _id: new Message.base.Types.ObjectId() })),
};
+ const admittedUpdate = options.prepareAppUpdate
+ ? await options.prepareAppUpdate(current, { ...safeUpdate, ...provenance })
+ : { ...safeUpdate, ...provenance };
try {
const message = await Message.findOneAndUpdate(
filter,
{
- $set: { ...safeUpdate, ...provenance },
+ $set: admittedUpdate,
+ $inc: { __v: 1 },
...(current == null &&
options.retentionOnInsert != null && { $setOnInsert: options.retentionOnInsert }),
...(options.unsetContextMeta && { $unset: { contextMeta: 1 } }),
},
- { upsert: options.upsert && current == null, new: true },
+ { upsert: options.upsert && current == null, new: true, timestamps: options.timestamps },
);
if (message != null) {
+ options.onWrite?.(current == null, message._id);
return message;
}
} catch (err) {
@@ -860,49 +896,118 @@ function agentOwnershipFilter(prefix: string, agentId: string): Record<string, u
};
}
-type UpdateToolCallResultInput = {
- userId: string;
- messageId: string;
- conversationId: string;
- toolCallId: string;
- stepId?: string;
- /** Scopes the part match when provider tool-call ids repeat across
- * agents in one response message (e.g. `call_0` per response); a part
- * without agent identity matches any caller (single-agent runs). */
- agentId?: string;
- output?: string;
- attachments?: unknown[];
- /**
- * Stamps `backgrounded: true` onto the patched tool call. Replacing the
- * dispatch-handle output with the settled task's stdout destroys the only
- * signal renderers had that this call ran detached (the handle JSON and
- * the live status-marker attachment are both transient), so the patch
- * that erases it must persist a durable one alongside.
- */
- markBackgrounded?: boolean;
- backgroundTask?: {
- taskId: string;
- toolName: string;
- status: 'completed' | 'error';
- cancelled?: true;
- settledAt: Date;
- completionWakeup?: true;
- completionReceipt?: true;
- resultClaim?: {
- kind: 'manual' | 'wakeup';
- claimId: string;
- claimedAt: Date;
- generationId?: string;
- };
- };
-};
+export interface MessageDependencies {
+ /** Read from deployment config, never from a message/request or a principal override. */
+ getMCPAppMessageBudget?: () => Promise<number | undefined>;
+}
-type SteplessToolCallFallback = {
- content: NonNullable<IMessage['content']>;
- hasResultClaim: boolean;
-};
+export function createMessageMethods(
+ mongoose: typeof import('mongoose'),
+ deps: MessageDependencies = {},
+): MessageMethods {
+ /** The API constructs method adapters before it necessarily registers every model. */
+ function privateMessagePaths(): string {
+ const Message = mongoose.models.Message as Model<IMessage>;
+ return Object.entries(Message.schema.paths)
+ .filter(([, path]) => path.options.select === false)
+ .map(([name]) => `+${name}`)
+ .join(' ');
+ }
+
+ async function prepareAppUpdate(
+ update: Record<string, unknown>,
+ current: Record<string, unknown> | null,
+ unsetContextMeta = false,
+ retentionOnInsert?: { expiredAt: Date; isTemporary: false },
+ ): Promise<Record<string, unknown>> {
+ const Message = mongoose.models.Message as Model<IMessage>;
+ const safeUpdate = sanitizeMessageUpdate(update);
+ // Omission retains the attachments of THIS fenced row; null/[] explicitly clears them.
+ const attachments = Object.prototype.hasOwnProperty.call(safeUpdate, 'attachments')
+ ? safeUpdate.attachments
+ : current?.attachments;
+ if (!hasBoundAppSnapshots(attachments)) return safeUpdate;
+ const maxBytes = await deps.getMCPAppMessageBudget?.();
+ const admitted = fitBoundAppSnapshots(
+ attachments as unknown[],
+ (candidateAttachments) => {
+ const fields = {
+ ...current,
+ ...(current == null ? retentionOnInsert : {}),
+ ...safeUpdate,
+ attachments: candidateAttachments,
+ ...(unsetContextMeta ? { contextMeta: undefined } : {}),
+ createdAt: current?.createdAt ?? safeUpdate.createdAt ?? new Date(),
+ updatedAt: new Date(),
+ __v: (Number(current?.__v) || 0) + 1,
+ };
+ const next = new Message(fields).toObject({ depopulate: true, minimize: false });
+ // Keep unknown fields already stored by a newer producer, even if this schema drops them.
+ const candidate = { ...current, ...next };
+ if (unsetContextMeta) delete candidate.contextMeta;
+ return mongoose.mongo.BSON.calculateObjectSize(candidate);
+ },
+ maxBytes,
+ );
+ if (admitted !== attachments) {
+ logger.warn('[saveMessage] Optional MCP App documents exceeded the message BSON budget');
+ }
+ return admitted === attachments ? safeUpdate : { ...safeUpdate, attachments: admitted };
+ }
+
+ /** One admission owner for save, edit, record and import. No size heuristics or stale closures. */
+ async function writeMessage(
+ identity: FilterQuery<IMessage>,
+ input: Record<string, unknown>,
+ options: {
+ upsert: boolean;
+ stampModelOutputOnInsert?: boolean;
+ unsetContextMeta?: boolean;
+ retentionOnInsert?: { expiredAt: Date; isTemporary: false };
+ timestamps?: boolean;
+ onWrite?: (inserted: boolean, id: unknown) => void;
+ },
+ ): Promise<IMessage | null> {
+ const Message = mongoose.models.Message as Model<IMessage>;
+ const update = sanitizeMessageUpdate(input);
+ const paths = normalizeUserSubmittedPaths(update.userSubmittedPaths);
+ const fields = normalizeUserSubmittedMessageFieldPaths(update.userSubmittedMessageFieldPaths);
+ delete update.userSubmittedPaths;
+ delete update.userSubmittedMessageFieldPaths;
+ if (!hasBoundAppSnapshots(update.attachments) && paths.length === 0 && fields.length === 0) {
+ try {
+ // Preserve the single-write common path. If an App row is excluded, its existing
+ // unique (messageId, user, tenantId) index rejects the upsert; budget that row below.
+ const fast = await Message.findOneAndUpdate(
+ { ...identity, ...NO_BOUND_APPS },
+ buildMessageSaveUpdate(update, {
+ stampModelOutputOnInsert: options.stampModelOutputOnInsert ?? false,
+ unsetContextMeta: options.unsetContextMeta ?? false,
+ retentionOnInsert: options.retentionOnInsert,
+ }),
+ {
+ upsert: options.upsert,
+ new: true,
+ timestamps: options.timestamps,
+ includeResultMetadata: true,
+ },
+ );
+ if (fast.value) {
+ options.onWrite?.(fast.lastErrorObject?.updatedExisting === false, fast.value._id);
+ return fast.value;
+ }
+ } catch (error) {
+ if (!isDuplicateKeyError(error)) throw error;
+ }
+ }
+ return findOneAndMergeMessageProvenance(Message, identity, update, paths, fields, {
+ ...options,
+ privateMessagePaths: privateMessagePaths(),
+ prepareAppUpdate: (current, sanitized) =>
+ prepareAppUpdate(sanitized, current, options.unsetContextMeta, options.retentionOnInsert),
+ });
+ }
-export function createMessageMethods(mongoose: typeof import('mongoose')): MessageMethods {
/**
* Saves a message in the database.
*/
@@ -1021,28 +1126,14 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
);
delete update.userSubmittedPaths;
delete update.userSubmittedMessageFieldPaths;
+ delete update.__v;
const stampModelOutputOnInsert =
params.isCreatedByUser === false && params.isUserSubmitted === undefined;
- const hasProvenance =
- userSubmittedPaths.length > 0 || userSubmittedMessageFieldPaths.length > 0;
- const message = hasProvenance
- ? await findOneAndMergeMessageProvenance(
- Message,
- { messageId: params.messageId, user: userId },
- update,
- userSubmittedPaths,
- userSubmittedMessageFieldPaths,
- { upsert: true, stampModelOutputOnInsert, unsetContextMeta, retentionOnInsert },
- )
- : await Message.findOneAndUpdate(
- { messageId: params.messageId, user: userId },
- buildMessageSaveUpdate(update, {
- stampModelOutputOnInsert,
- unsetContextMeta,
- retentionOnInsert,
- }),
- { upsert: true, new: true },
- );
+ const message = await writeMessage(
+ { messageId: params.messageId, user: userId },
+ { ...update, userSubmittedPaths, userSubmittedMessageFieldPaths },
+ { upsert: true, stampModelOutputOnInsert, unsetContextMeta, retentionOnInsert },
+ );
if (message == null) {
return message;
@@ -1126,7 +1217,7 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
try {
const Message = mongoose.models.Message as Model<IMessage>;
const bulkOps = messages.map((message) => {
- const normalizedMessage = { ...message };
+ const normalizedMessage = sanitizeMessageUpdate(message);
const provenance = capNormalizedProvenance(
normalizeUserSubmittedPaths(message.userSubmittedPaths),
normalizeUserSubmittedMessageFieldPaths(message.userSubmittedMessageFieldPaths),
@@ -1147,15 +1238,96 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
}
return {
updateOne: {
- filter: { messageId: message.messageId },
- update: normalizedMessage,
+ filter: {
+ messageId: message.messageId,
+ ...(message.user != null ? { user: message.user } : {}),
+ },
+ update: { $set: normalizedMessage, $inc: { __v: 1 } },
timestamps: !overrideTimestamp,
upsert: true,
},
};
});
- const result = await tenantSafeBulkWrite(Message, bulkOps);
- return result;
+ // Keep no-App imports batched. The atomic predicate makes a race with App attachment
+ // creation collide on the unique key, at which point only that row uses guarded admission.
+ const guarded: typeof bulkOps = [];
+ const ordinary = bulkOps.filter((op) => {
+ if (hasBoundAppSnapshots(op.updateOne.update.$set.attachments)) {
+ guarded.push(op);
+ return false;
+ }
+ return true;
+ });
+ let result:
+ | {
+ matchedCount: number;
+ modifiedCount: number;
+ upsertedCount: number;
+ upsertedIds: Record<number, unknown>;
+ }
+ | undefined;
+ const repaired = {
+ matchedCount: 0,
+ modifiedCount: 0,
+ upsertedCount: 0,
+ upsertedIds: {} as Record<number, unknown>,
+ };
+ if (ordinary.length) {
+ try {
+ result = await tenantSafeBulkWrite(
+ Message,
+ ordinary.map((op) => ({
+ updateOne: {
+ ...op.updateOne,
+ filter: { ...op.updateOne.filter, ...NO_BOUND_APPS },
+ },
+ })),
+ { ordered: false },
+ );
+ } catch (error) {
+ const failure = error as {
+ writeErrors?: Array<{ code: number; index: number }>;
+ result?: typeof result;
+ };
+ if (
+ !failure.writeErrors?.length ||
+ failure.writeErrors.some((item) => item.code !== 11000)
+ )
+ throw error;
+ result = failure.result;
+ for (const { index } of failure.writeErrors) guarded.push(ordinary[index]);
+ }
+ }
+ // Ordinary imports stay batched; exceptional App rows are admitted one at a time.
+ for (const op of guarded) {
+ await writeMessage(op.updateOne.filter, op.updateOne.update.$set, {
+ upsert: true,
+ timestamps: !overrideTimestamp,
+ onWrite: (inserted, id) => {
+ if (inserted) {
+ repaired.upsertedCount++;
+ repaired.upsertedIds[bulkOps.indexOf(op)] = id;
+ } else {
+ repaired.matchedCount++;
+ repaired.modifiedCount++;
+ }
+ },
+ });
+ }
+ if (!guarded.length) return result;
+ const upsertedIds: Record<number, unknown> = { ...repaired.upsertedIds };
+ for (const [index, id] of Object.entries(result?.upsertedIds ?? {})) {
+ upsertedIds[bulkOps.indexOf(ordinary[Number(index)])] = id;
+ }
+ return {
+ insertedCount: 0,
+ deletedCount: 0,
+ insertedIds: {},
+ upsertedIds,
+ matchedCount: (result?.matchedCount ?? 0) + repaired.matchedCount,
+ modifiedCount: (result?.modifiedCount ?? 0) + repaired.modifiedCount,
+ upsertedCount: (result?.upsertedCount ?? 0) + repaired.upsertedCount,
+ };
} catch (err) {
logger.error('Error saving messages in bulk:', err);
throw err;
@@ -1181,7 +1353,6 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
[key: string]: unknown;
}) {
try {
- const Message = mongoose.models.Message as Model<IMessage>;
const provenance = capNormalizedProvenance(
normalizeUserSubmittedPaths(rest.userSubmittedPaths),
normalizeUserSubmittedMessageFieldPaths(rest.userSubmittedMessageFieldPaths),
@@ -1206,16 +1377,10 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
}),
...(provenance.promoteWholeMessage && { isUserSubmitted: true }),
};
- const update =
- rest.isCreatedByUser === false &&
- rest.isUserSubmitted === undefined &&
- !provenance.promoteWholeMessage
- ? { $set: message, $setOnInsert: { isUserSubmitted: false } }
- : message;
-
- return await Message.findOneAndUpdate({ user, messageId }, update, {
+ return await writeMessage({ user, messageId }, message, {
upsert: true,
- new: true,
+ stampModelOutputOnInsert:
+ rest.isCreatedByUser === false && rest.isUserSubmitted === undefined,
});
} catch (err) {
logger.error('Error recording message:', err);
@@ -1231,8 +1396,7 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
{ messageId, text }: { messageId: string; text: string },
) {
try {
- const Message = mongoose.models.Message as Model<IMessage>;
- await Message.updateOne({ messageId, user: userId }, { text });
+ await writeMessage({ messageId, user: userId }, { text }, { upsert: false });
} catch (err) {
logger.error('Error updating message text:', err);
throw err;
@@ -1400,7 +1564,8 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
}
}
}
- const mergingAttachments = attachments !== undefined && attachments.length > 0;
+ const incomingAttachments = attachments ?? [];
+ const mergingAttachments = incomingAttachments.length > 0;
if (Object.keys(partPatch).length === 0 && !mergingAttachments) {
return { matched: false, unfinished: false };
}
@@ -1415,7 +1580,8 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
: {}),
};
const settleUpdate = {
- ...(Object.keys(settlePatch).length > 0 ? { $set: settlePatch } : {}),
+ $inc: { __v: 1 },
+ ...(Object.keys(partPatch).length > 0 ? { $set: partPatch } : {}),
...(disarmWakeup
? { $unset: { 'content.$[part].tool_call.backgroundTask.completionWakeup': 1 } }
: {}),
@@ -1454,12 +1620,13 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
);
}
if (!mergingAttachments) {
- const result = await Message.findOneAndUpdate(
- messageFilter,
+ const fast = await Message.findOneAndUpdate(
+ { ...messageFilter, ...NO_BOUND_APPS },
settleUpdate,
settleOptions,
).lean<{ unfinished?: boolean } | null>();
- return { matched: result != null, unfinished: result?.unfinished === true };
+ if (fast) return { matched: true, unfinished: fast.unfinished === true };
+ // Either absent, or a bound-App row needs an exact candidate even for tiny results.
}
/** Dedupe key mirrors the resume merge: `file_id ?? filepath`, so
* download-fallback attachments (no `file_id`, only a filepath) stay
@@ -1471,7 +1638,7 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
* agent's attachment under the same id/key must survive (missing agent
* identity = legacy wildcard). */
const attachmentKeys = new Set(
- attachments
+ incomingAttachments
.map((attachment) => {
const { file_id, filepath } = attachment as { file_id?: unknown; filepath?: unknown };
return typeof file_id === 'string' ? file_id : filepath;
@@ -1496,33 +1663,110 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
if (stepId != null && entryStep !== null && entryStep !== stepId) return false;
return true;
};
- /** The old pipeline replaced-and-appended `attachments` in one atomic
- * write; classic `$pull` and `$push` conflict on one field and splitting
- * them opens a window where a crash strips attachments and concurrent
- * re-applications duplicate them. Instead: read the array, merge it here
- * with the exact semantics the old `$filter`/`$concatArrays` had, and
- * write everything back in ONE update fenced on the array being unchanged
- * — the same guarded full-array compare-and-swap this file already uses
- * for `subagentTask.controlReceipts`. A lost fence means a concurrent
- * writer advanced the array; re-reading converges to exactly one copy. */
+ /** Classic `$pull` and `$push` conflict on the same field. Keep merge and
+ * part patch in one update; ordinary attachments retain the preexisting
+ * array compare-and-swap. For bound Apps, a large array in BOTH the filter
+ * and update exceeds MongoDB's 16 MiB command limit even when the resulting
+ * document fits. Use the small `__v` fence instead: every save with
+ * attachments and every background settle increments it. A lost fence is
+ * re-read and re-budgeted before retrying the combined write. */
+ const incomingApp = hasBoundAppSnapshots(incomingAttachments);
for (let attempt = 0; attempt < ATTACHMENT_MERGE_CAS_ATTEMPTS; attempt += 1) {
const row = await Message.findOne(messageFilter)
- .select({ _id: 1, attachments: 1 })
- .lean<{ _id: Types.ObjectId; attachments?: unknown[] } | null>();
+ .select(incomingApp ? privateMessagePaths() : { _id: 1, attachments: 1, __v: 1 })
+ .lean<
+ | (Record<string, unknown> & {
+ _id: Types.ObjectId;
+ attachments?: unknown[];
+ __v?: number;
+ })
+ | null
+ >();
if (row == null) {
return { matched: false, unfinished: false };
}
- const prior = Array.isArray(row.attachments) ? row.attachments : [];
- const merged = [...prior.filter((entry) => !replacesEntry(entry)), ...attachments];
+ const hasApps = incomingApp || hasBoundAppSnapshots(row.attachments);
+ /** Avoid materializing the whole message for ordinary file attachments. */
+ const current =
+ hasApps && !incomingApp
+ ? await Message.findOne({
+ ...messageFilter,
+ _id: row._id,
+ __v: row.__v ?? null,
+ })
+ .select(privateMessagePaths())
+ .lean<
+ | (Record<string, unknown> & { _id: Types.ObjectId; attachments?: unknown[] })
+ | null
+ >()
+ : row;
+ if (current == null) continue;
+ const prior = Array.isArray(current.attachments) ? current.attachments : [];
+ const merged = [...prior.filter((entry) => !replacesEntry(entry)), ...incomingAttachments];
+ let admitted = merged;
+ if (hasApps) {
+ const content = Array.isArray(current.content) ? current.content : [];
+ const nextContent = content.map((entry) => {
+ if (entry == null || typeof entry !== 'object') return entry;
+ const part = entry as {
+ type?: unknown;
+ agentId?: unknown;
+ tool_call?: {
+ id?: unknown;
+ stepId?: unknown;
+ agentId?: unknown;
+ backgroundTask?: Record<string, unknown>;
+ };
+ };
+ // Exactly the agentOwnershipFilter precedence: part agent, then call agent, then wildcard.
+ const owner = part.agentId ?? part.tool_call?.agentId;
+ if (
+ part.type !== 'tool_call' ||
+ part.tool_call?.id !== toolCallId ||
+ (stepId != null && part.tool_call.stepId !== stepId) ||
+ (agentId != null && owner != null && owner !== agentId)
+ )
+ return entry;
+ const task = { ...part.tool_call.backgroundTask };
+ if (backgroundTask) {
+ Object.assign(task, {
+ version: 1,
+ taskId: backgroundTask.taskId,
+ toolName: backgroundTask.toolName,
+ status: backgroundTask.status,
+ cancelled: backgroundTask.cancelled === true,
+ settledAt: backgroundTask.settledAt,
+ });
+ if (backgroundTask.completionReceipt) task.completionReceipt = true;
+ if (backgroundTask.completionWakeup) task.completionWakeup = true;
+ else delete task.completionWakeup;
+ }
+ return {
+ ...part,
+ tool_call: {
+ ...part.tool_call,
+ ...(output !== undefined && { output }),
+ ...((output !== undefined || backgroundTask != null) &&
+ markBackgrounded && { backgrounded: true }),
+ ...(backgroundTask && { backgroundTask: task }),
+ },
+ };
+ });
+ admitted = (
+ await prepareAppUpdate({ attachments: merged, content: nextContent }, current)
+ ).attachments as unknown[];
+ }
const result = await Message.findOneAndUpdate(
{
...messageFilter,
- _id: row._id,
- attachments: row.attachments == null ? null : row.attachments,
+ _id: current._id,
+ ...(hasApps
+ ? { __v: current.__v ?? null }
+ : { attachments: current.attachments == null ? null : current.attachments }),
},
{
...settleUpdate,
- $set: { ...settlePatch, attachments: merged },
+ $set: { ...partPatch, attachments: admitted },
},
settleOptions,
).lean<{ unfinished?: boolean } | null>();
@@ -2063,25 +2307,10 @@ export function createMessageMethods(mongoose: typeof import('mongoose')): Messa
metadata?: { context?: string },
) {
try {
- const Message = mongoose.models.Message as Model<IMessage>;
const { messageId, ...update } = message;
- const submittedPaths = normalizeUserSubmittedPaths(update.userSubmittedPaths);
- const submittedMessageFields = normalizeUserSubmittedMessageFieldPaths(
- update.userSubmittedMessageFieldPaths,
- );
- delete update.userSubmittedPaths;
- delete update.userSubmittedMessageFieldPaths;
- const updatedMessage =
- submittedPaths.length > 0 || submittedMessageFields.length > 0
- ? await findOneAndMergeMessageProvenance(
- Message,
- { messageId, user: userId },
- update,
- submittedPaths,
- submittedMessageFields,
- { upsert: false },
- )
- : await Message.findOneAndUpdate({ messageId, user: userId }, update, { new: true });
+ const updatedMessage = await writeMessage({ messageId, user: userId }, update, {
+ upsert: false,
+ });
if (!updatedMessage) {
throw new Error('Message not found or user not authorized.');