📎 feat: Resolve Channel Attachments and Usage Summaries (#17608)

* 📎 feat: Resolve Channel Attachments and Usage Summaries

* fix: Bound Response Artifact Catalogs and Reauthorize Trace Disclosure

* fix: unify channel artifact budgets and generated provenance
This commit is contained in:
Dustin Healy 2026-11-10 21:04:02 -08:00 • committed by GitHub
parent 7593a5c14a
commit aae13f6817
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
29 changed files with 2554 additions and 26 deletions

View file

@ -44,6 +44,7 @@ const png = Buffer.from(
describe('assistant avatar multipart authorization', () => {
let mongo;
let directory;
let unlink;
let Assistant;
let app;
let providers;
@ -57,6 +58,7 @@ describe('assistant avatar multipart authorization', () => {
const openai = { beta: { assistants: { retrieve, update } } };
beforeAll(async () => {
unlink = jest.spyOn(fs, 'unlink');
directory = await fs.mkdtemp(`${os.tmpdir()}/assistant-avatar-`);
mongo = await MongoMemoryServer.create({ instance: { args: ['--nounixsocket'] } });
await mongoose.connect(mongo.getUri());
@ -111,6 +113,7 @@ describe('assistant avatar multipart authorization', () => {
await mongoose.disconnect();
await mongo?.stop();
await fs.rm(directory, { recursive: true, force: true });
unlink.mockRestore();
});
beforeEach(async () => {
@ -164,6 +167,12 @@ describe('assistant avatar multipart authorization', () => {
getStrategyFunctions.mockReturnValue({ deleteFile: deleteStoredFile });
});
async function expectTemporaryFilesRemoved() {
// The HTTP response precedes the controller's asynchronous finally cleanup.
await Promise.all(unlink.mock.results.map(({ value }) => value));
expect(await fs.readdir(directory)).toEqual([]);
}
async function upload(id, fields = {}, query = '', checkTemporaryFiles = true) {
let req = request(app)
.post(`/api/files/images/assistants/${id}/avatar${query}`)
@ -176,7 +185,7 @@ describe('assistant avatar multipart authorization', () => {
contentType: 'image/png',
});
if (checkTemporaryFiles) {
expect(await fs.readdir(directory)).toEqual([]);
await expectTemporaryFilesRemoved();
}
return response;
}
@ -567,7 +576,7 @@ describe('assistant avatar multipart authorization', () => {
const second = upload('asst-attacker', {}, '', false);
setTimeout(finishFirst, 5);
const responses = await Promise.all([first, second]);
expect(await fs.readdir(directory)).toEqual([]);
await expectTemporaryFilesRemoved();
expect(responses.map((response) => response.status)).toEqual([201, 201]);
expect(providerAvatar).toBe(secondPath);
const reference = await Assistant.findOne({ assistant_id: 'asst-attacker' }).lean();

View file

@ -1,4 +1,5 @@
const { Readable } = require('stream');
const { createHash } = require('node:crypto');
// Configurable file size limit for tests - use a getter so it can be changed per test
const fileSizeLimitConfig = { value: 20 * 1024 * 1024 }; // Default 20MB
@ -647,6 +648,24 @@ describe('Code Process', () => {
});
describe('snapshot reservation', () => {
it('binds immutable snapshot bytes to the generating message', async () => {
const bytes = Buffer.from('new content');
mockAxios.mockResolvedValue({ data: bytes });
const { file } = await processCodeOutput({ ...baseParams, messageId: 'current-message' });
const codeOutput = {
messageId: 'current-message',
sha256: createHash('sha256').update(bytes).digest('hex'),
};
expect(mockCommitCodeFile).toHaveBeenCalledWith(
expect.objectContaining({
messageId: 'current-message',
metadata: expect.objectContaining({ codeOutput }),
}),
undefined,
);
expect(file.messageId).toBe('current-message');
expect(file.metadata.codeOutput).toEqual(codeOutput);
});
it('reserves a fresh capture rather than claiming the mutable filename slot', async () => {
mockAxios.mockResolvedValue({ data: Buffer.alloc(100) });
const { file } = await processCodeOutput(baseParams);
@ -708,6 +727,7 @@ describe('Code Process', () => {
const convertedFile = {
filepath: '/uploads/converted-image.webp',
bytes: 400,
sha256: createHash('sha256').update('converted image bytes').digest('hex'),
};
convertImage.mockResolvedValue(convertedFile);
@ -722,6 +742,10 @@ describe('Code Process', () => {
expect(result.type).toBe('image/webp');
expect(result.context).toBe(FileContext.execute_code_snapshot);
expect(result.filename).toBe('chart.png');
expect(result.metadata.codeOutput).toEqual({
messageId: baseParams.messageId,
sha256: convertedFile.sha256,
});
});
it('persists tenantId on image code output records when present', async () => {
@ -1200,6 +1224,10 @@ describe('Code Process', () => {
const { file: result } = await processCodeOutput(baseParams);
expect(result.metadata).toEqual({
codeOutput: {
messageId: baseParams.messageId,
sha256: createHash('sha256').update(smallBuffer).digest('hex'),
},
codeEnvSource: {
kind: 'user',
id: 'user-123',

View file

@ -12,7 +12,7 @@ const { resizeImageBuffer } = require('./resize');
* @param {Buffer | Express.Multer.File} file - The file object, containing either a path or a buffer.
* @param {'low' | 'high'} [resolution='high'] - The desired resolution for the output image.
* @param {string} [basename=''] - The basename of the input file, if it is a buffer.
* @returns {Promise<{filepath: string, bytes: number, width: number, height: number, storageKey?: string, storageRegion?: string}>} An object containing the path, size, dimensions, and optional storage metadata of the converted image.
* @returns {Promise<{filepath: string, bytes: number, width: number, height: number, sha256: string, storageKey?: string, storageRegion?: string}>} Metadata and digest of the stored converted image.
* @throws Throws an error if there is an issue during the conversion process.
*/
async function convertImage(req, file, resolution = 'high', basename = '') {
@ -38,7 +38,11 @@ async function convertImage(req, file, resolution = 'high', basename = '') {
type,
} = await resizeImageBuffer(inputBuffer, resolution);
const { buffer: outputBuffer, fileName: newFileName } = await convertImageBuffer({
const {
buffer: outputBuffer,
fileName: newFileName,
sha256,
} = await convertImageBuffer({
buffer: resizedBuffer,
type,
fileName: path.basename(file.path ?? basename),
@ -59,7 +63,7 @@ async function convertImage(req, file, resolution = 'high', basename = '') {
});
const bytes = Buffer.byteLength(outputBuffer);
return { filepath: savedFilePath, ...storageMetadata, bytes, width, height };
return { filepath: savedFilePath, ...storageMetadata, bytes, width, height, sha256 };
} catch (err) {
logger.error(err);
throw err;

View file

@ -885,6 +885,8 @@ test.describe('quote references on touch devices', () => {
}) => {
test.setTimeout(120000);
await seedParagraphReply(page);
await expect(page.getByRole('button', { name: 'Stop generating' })).toBeHidden();
await waitForReplyToSettle(page, CLOSING_PARAGRAPH);
// A mouse-less selection is only published once it has been quiet for the
// settle interval, and nothing is tracked until then — so a scroll inside

View file

@ -460,6 +460,8 @@ describe('createAdminLangfuseHandlers', () => {
{
user: 'u1',
conversationId: 'conversation-1',
isCreatedByUser: false,
isUserSubmitted: { $ne: true },
langfuseSampled: true,
langfuseDestinationIds: getLangfuseDestinationId(
'https://cloud.langfuse.com',

View file

@ -0,0 +1,214 @@
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { Readable } from 'node:stream';
import { createReadStream } from 'node:fs';
import { FileSources } from 'librechat-data-provider';
import { mkdtemp, writeFile, rm } from 'node:fs/promises';
import type { AppConfig, ChannelRunRecord, RunArtifactFile } from '@librechat/data-schemas';
import type { ChannelArtifactStorageRequest } from './artifactStorage';
import { createChannelArtifactReader } from './artifactStorage';
const run: ChannelRunRecord = {
tenantId: 'tenant-a',
channelId: 'channel-a',
agentId: 'agent-a',
runId: 'run-a',
laneId: 'lane-a',
state: 'delivered',
sequence: 1,
payloadHash: 'hash',
receivedAt: 1,
leaseEpoch: 1,
leaseExpiresAt: 0,
cancellationRequested: false,
receipts: [],
principal: {
userId: 'user-a',
channelRevision: 'channel-rev',
linkId: 'link-a',
linkRevision: 'link-rev',
},
admission: {
eventId: 'Ev1',
externalChannelId: 'C1',
externalThreadKey: 'C1:1',
externalMessageKey: 'C1:1',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
input: 'hello',
},
execution: {
requestId: 'request-a',
conversationId: 'conversation-a',
parentMessageId: 'parent-a',
},
};
const file: RunArtifactFile = {
file_id: 'file-a',
user: 'user-a',
tenantId: 'tenant-a',
conversationId: 'conversation-a',
filename: 'result.txt',
filepath: '/uploads/result.txt?cache=1',
bytes: 6,
type: 'text/plain',
source: FileSources.local,
embedded: false,
object: 'file',
usage: 0,
metadata: {
runFile: {
runId: 'response-a',
executionId: 'execution-a',
agentId: 'agent-a',
sourceFileId: 'source-a',
publishedAt: '2026-10-20T00:00:00.000Z',
inputFileIds: [],
},
},
};
const config = { paths: { uploads: '/configured/uploads' } } as AppConfig;
it('reads a real local file through the configured storage stream with the exact run principal', async () => {
const directory = await mkdtemp(join(tmpdir(), 'channel-artifact-reader-'));
const path = join(directory, 'result.txt');
try {
await writeFile(path, 'result');
const signal = new AbortController().signal;
const getConfig = jest.fn(async () => config);
const getDownloadStream = jest.fn(
async (request: ChannelArtifactStorageRequest, storedPath: string) => {
expect(request).toEqual({ config, user: { id: 'user-a' }, tenantId: 'tenant-a' });
expect(storedPath).toBe(path);
return createReadStream(storedPath);
},
);
const getStrategyFunctions = jest.fn(() => ({ getDownloadStream }));
const reader = createChannelArtifactReader({ getConfig, getStrategyFunctions });
const stream = await reader.readFile({ ...file, storageKey: path }, run, signal);
expect(stream).not.toBeNull();
const chunks: Buffer[] = [];
for await (const chunk of stream!) chunks.push(Buffer.from(chunk));
expect(Buffer.concat(chunks).toString()).toBe('result');
expect(getConfig).toHaveBeenCalledWith(run);
expect(getStrategyFunctions).toHaveBeenCalledWith(FileSources.local);
expect(getDownloadStream).toHaveBeenCalledWith(expect.anything(), path, { signal });
} finally {
await rm(directory, { recursive: true, force: true });
}
});
it.each([
FileSources.local,
FileSources.s3,
FileSources.cloudfront,
FileSources.azure_blob,
FileSources.firebase,
])('uses the persisted download reference and forwards cancellation for %s', async (source) => {
const signal = new AbortController().signal;
const getDownloadStream = jest.fn(async () => Readable.from(['result']));
const reader = createChannelArtifactReader({
getConfig: async () => config,
getStrategyFunctions: () => ({ getDownloadStream }),
});
const stream = await reader.readFile({ ...file, source }, run, signal);
expect(getDownloadStream).toHaveBeenCalledWith(
{ config, user: { id: 'user-a' }, tenantId: 'tenant-a' },
file.filepath,
{ signal },
);
stream?.destroy();
});
it('rejects another owner, tenant, conversation, or missing execution before any storage/config I/O', async () => {
const getConfig = jest.fn(async () => config);
const getStrategyFunctions = jest.fn();
const reader = createChannelArtifactReader({ getConfig, getStrategyFunctions });
const signal = new AbortController().signal;
for (const other of [
{ ...file, user: 'user-b' },
{ ...file, tenantId: 'tenant-b' },
{ ...file, tenantId: undefined },
{ ...file, conversationId: 'conversation-b' },
{ ...file, expiredAt: new Date(0) },
{ ...file, expiredAt: new Date(Number.NaN) },
]) {
expect(await reader.readFile(other, run, signal)).toBeNull();
}
expect(await reader.readFile(file, { ...run, execution: undefined }, signal)).toBeNull();
expect(getConfig).not.toHaveBeenCalled();
expect(getStrategyFunctions).not.toHaveBeenCalled();
});
it('does not route unsupported provider/code sources to storage or expose credentials', async () => {
const getConfig = jest.fn(async () => config);
const getStrategyFunctions = jest.fn();
const reader = createChannelArtifactReader({ getConfig, getStrategyFunctions });
for (const source of Object.values(FileSources).filter(
(source) =>
![
FileSources.local,
FileSources.s3,
FileSources.cloudfront,
FileSources.azure_blob,
FileSources.firebase,
].includes(source),
)) {
expect(
await reader.readFile({ ...file, source }, run, new AbortController().signal),
).toBeNull();
}
expect(getConfig).not.toHaveBeenCalled();
expect(getStrategyFunctions).not.toHaveBeenCalled();
});
it('normalizes only the default tenant sentinel without admitting a named tenant', async () => {
const getDownloadStream = jest.fn(async () => Readable.from(['result']));
const reader = createChannelArtifactReader({
getConfig: async () => config,
getStrategyFunctions: () => ({ getDownloadStream }),
});
const defaultRun = { ...run, tenantId: '_' };
const signal = new AbortController().signal;
const stream = await reader.readFile({ ...file, tenantId: undefined }, defaultRun, signal);
expect(stream).not.toBeNull();
stream?.destroy();
expect(getDownloadStream).toHaveBeenCalledWith(
{ config, user: { id: 'user-a' }, tenantId: undefined },
file.filepath,
{ signal },
);
expect(await reader.readFile(file, defaultRun, signal)).toBeNull();
expect(getDownloadStream).toHaveBeenCalledTimes(1);
});
it('returns null for missing config/strategy/path and never starts an already aborted read', async () => {
const getDownloadStream = jest.fn(async () => Readable.from(['result']));
const deps = {
getConfig: async () => config,
getStrategyFunctions: () => ({ getDownloadStream }),
};
const signal = new AbortController().signal;
expect(
await createChannelArtifactReader({ ...deps, getConfig: async () => undefined }).readFile(
file,
run,
signal,
),
).toBeNull();
expect(
await createChannelArtifactReader({ ...deps, getStrategyFunctions: () => undefined }).readFile(
file,
run,
signal,
),
).toBeNull();
expect(
await createChannelArtifactReader(deps).readFile({ ...file, filepath: '' }, run, signal),
).toBeNull();
const controller = new AbortController();
controller.abort();
await expect(
createChannelArtifactReader(deps).readFile(file, run, controller.signal),
).rejects.toThrow();
expect(getDownloadStream).not.toHaveBeenCalled();
});

View file

@ -0,0 +1,80 @@
import { FileSources } from 'librechat-data-provider';
import type { AppConfig, ChannelRunRecord, ResponseArtifactFile } from '@librechat/data-schemas';
import type { Readable } from 'node:stream';
import { isChannelArtifactExpired } from './artifacts';
import { resolveDownloadPath } from '~/storage/path';
/** Only the request fields used by supported storage readers, never an authenticated HTTP request. */
export interface ChannelArtifactStorageRequest {
config: AppConfig;
user: { id: string };
tenantId?: string;
}
export interface ChannelArtifactStorageDependencies {
getConfig: (run: ChannelRunRecord) => Promise<AppConfig | undefined>;
getStrategyFunctions: (source: FileSources) =>
| {
getDownloadStream?: (
request: ChannelArtifactStorageRequest,
path: string,
options: { signal: AbortSignal },
) => Promise<Readable>;
}
| undefined;
}
export interface ChannelArtifactReader {
readFile: (
file: ResponseArtifactFile,
run: ChannelRunRecord,
signal: AbortSignal,
) => Promise<Readable | null>;
}
const supportedSources = new Set<string>([
FileSources.local,
FileSources.s3,
FileSources.cloudfront,
FileSources.azure_blob,
FileSources.firebase,
]);
/** Input files must already be authorized by readResponseArtifacts for the exact saved response. */
export function createChannelArtifactReader(
deps: ChannelArtifactStorageDependencies,
): ChannelArtifactReader {
return {
async readFile(file, run, signal) {
const expired = isChannelArtifactExpired(file);
if (
!run.execution ||
file.user !== run.principal.userId ||
(file.tenantId || '_') !== (run.tenantId || '_') ||
file.conversationId !== run.execution.conversationId ||
expired ||
!file.source ||
!supportedSources.has(file.source)
) {
return null;
}
signal.throwIfAborted();
const path = resolveDownloadPath(file);
if (!path) return null;
const config = await deps.getConfig(run);
signal.throwIfAborted();
if (!config || isChannelArtifactExpired(file)) return null;
const strategy = deps.getStrategyFunctions(file.source);
if (!strategy?.getDownloadStream) return null;
return strategy.getDownloadStream(
{
config,
user: { id: run.principal.userId },
tenantId: run.tenantId === '_' ? undefined : run.tenantId || undefined,
},
path,
{ signal },
);
},
};
}

View file

@ -0,0 +1,809 @@
import mongoose from 'mongoose';
import { Readable } from 'node:stream';
import { createHash } from 'node:crypto';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { FileSources, FileContext } from 'librechat-data-provider';
import { createModels, createMethods, tenantStorage, runAsSystem } from '@librechat/data-schemas';
import type {
ChannelRunRecord,
RunArtifactScope,
RunArtifactContent,
ResponseArtifactFile,
} from '@librechat/data-schemas';
import type { ChannelArtifactDependencies } from './artifacts';
import { createChannelArtifactService } from './artifacts';
let mongo: MongoMemoryServer;
let db: ReturnType<typeof createMethods>;
let run: ChannelRunRecord;
let deps: ChannelArtifactDependencies;
let service: ReturnType<typeof createChannelArtifactService>;
const userId = new mongoose.Types.ObjectId().toString();
const scope: RunArtifactScope = {
userId,
tenantId: 'tenant-a',
conversationId: 'conversation-a',
runId: 'response-a',
executionId: 'execution-a',
agentId: 'agent-a',
sourceFileId: 'source-a',
};
const contentByFile = new Map<string, Buffer>();
const digest = (bytes: Buffer | string) => createHash('sha256').update(bytes).digest('hex');
const generatedMetadata = (messageId = scope.runId, bytes: Buffer | string = 'result') => ({
codeOutput: { messageId, sha256: digest(bytes) },
});
let limits = {
artifactMaxBytes: 10000,
artifactMaxFiles: 3,
artifactReadTimeoutMs: 1000,
artifactAnswerFileThresholdBytes: 6000,
};
async function publish(
bytes = 'result',
identity: RunArtifactScope = scope,
overrides: Partial<RunArtifactContent> = {},
) {
const file = await tenantStorage.run({ tenantId: identity.tenantId ?? undefined }, () =>
db.publishRunArtifactFile({
scope: identity,
provenance: {
runId: identity.runId,
executionId: identity.executionId,
agentId: identity.agentId,
sourceFileId: identity.sourceFileId,
publishedAt: '2026-10-20T00:00:00.000Z',
inputFileIds: [],
},
file: {
filename: 'result.txt',
filepath: '/uploads/result.txt',
bytes: Buffer.byteLength(bytes),
type: 'text/plain',
source: FileSources.local,
...overrides,
},
}),
);
contentByFile.set(file.file_id, Buffer.from(bytes));
return file;
}
async function generate(bytes = 'before') {
const file_id = 'reused-code-output';
const metadata = generatedMetadata(scope.runId, bytes);
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, async () => {
await mongoose.models.File.create({
file_id,
user: userId,
tenantId: scope.tenantId,
conversationId: scope.conversationId,
messageId: scope.runId,
filename: 'result.txt',
filepath: '/uploads/result.txt',
bytes: Buffer.byteLength(bytes),
type: 'text/plain',
source: FileSources.local,
context: FileContext.execute_code,
metadata,
});
await mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{ $set: { attachments: [{ file_id, metadata }] } },
);
});
contentByFile.set(file_id, Buffer.from(bytes));
return file_id;
}
beforeAll(async () => {
mongo = await MongoMemoryServer.create({ instance: { args: ['--nounixsocket'] } });
await mongoose.connect(mongo.getUri());
createModels(mongoose);
db = createMethods(mongoose);
await mongoose.models.File.init();
}, 60000);
afterAll(async () => {
await mongoose.disconnect();
await mongo?.stop();
});
beforeEach(async () => {
await runAsSystem(() =>
Promise.all([mongoose.models.File.deleteMany({}), mongoose.models.Message.deleteMany({})]),
);
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, () =>
mongoose.models.Message.create({
user: userId,
tenantId: scope.tenantId,
conversationId: scope.conversationId,
messageId: scope.runId,
isCreatedByUser: false,
sender: 'Agent',
endpoint: 'agents',
model: 'agent-a',
text: 'Owned response',
attachments: [],
}),
);
contentByFile.clear();
limits = {
artifactMaxBytes: 10000,
artifactMaxFiles: 3,
artifactReadTimeoutMs: 1000,
artifactAnswerFileThresholdBytes: 6000,
};
run = {
tenantId: 'tenant-a',
channelId: 'channel-a',
agentId: 'agent-a',
runId: 'run-a',
laneId: 'lane-a',
state: 'delivered',
sequence: 1,
payloadHash: 'hash',
receivedAt: 1,
leaseEpoch: 1,
leaseExpiresAt: 0,
cancellationRequested: false,
receipts: [],
principal: {
userId,
channelRevision: 'channel-rev',
linkId: 'link-a',
linkRevision: 'link-rev',
},
admission: {
eventId: 'Ev1',
externalChannelId: 'C1',
externalThreadKey: 'C1:1',
externalMessageKey: 'C1:1',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
input: 'hello',
},
execution: {
requestId: 'request-a',
responseId: scope.runId,
protocol: 'responses',
conversationId: 'conversation-a',
parentMessageId: 'parent-a',
},
snapshot: { responseId: 'response-a', status: 'completed', text: 'answer', elapsedMs: 1 },
};
deps = {
readArtifacts: (identity, query) =>
tenantStorage.run({ tenantId: identity.tenantId ?? undefined }, () =>
db.readResponseArtifacts(identity, query),
),
readFile: jest.fn(async (file) => Readable.from([contentByFile.get(file.file_id)!])),
limits: async () => limits,
};
service = createChannelArtifactService(deps);
});
it('hashes exact saved response bytes and reauthorizes the immutable file at download', async () => {
const file = await publish('snowman ☃', scope, {
filename: '../nested\\report\n.csv',
type: 'text/plain; bad',
});
const listed = await service.list(run, run.snapshot!);
expect(listed).toEqual({
unavailable: false,
artifacts: [
{
artifactId: `${file.file_id}:${digest('snowman ☃')}`,
filename: 'report.csv',
mediaType: 'application/octet-stream',
bytes: Buffer.byteLength('snowman ☃'),
sha256: digest('snowman ☃'),
},
],
});
run.snapshot!.artifacts = listed.artifacts;
const downloaded = await service.content(run, listed.artifacts[0].artifactId);
expect(downloaded.bytes).toEqual(Buffer.from('snowman ☃'));
expect(downloaded.descriptor).toEqual(listed.artifacts[0]);
});
it('real Mongo scope excludes other users, tenants, conversations, responses and expired artifacts', async () => {
const allowed = await publish();
await publish('other owner', { ...scope, userId: new mongoose.Types.ObjectId().toString() });
await publish('other tenant', { ...scope, tenantId: 'tenant-b' });
await publish('other conversation', { ...scope, conversationId: 'conversation-b' });
await publish('other response', { ...scope, runId: 'response-b' });
await publish('expired', { ...scope, sourceFileId: 'expired' }, { expiredAt: new Date(0) });
const listed = await service.list(run, run.snapshot!);
expect(listed.artifacts).toHaveLength(1);
expect(listed.artifacts[0].artifactId).toBe(`${allowed.file_id}:${digest('result')}`);
expect(deps.readFile).toHaveBeenCalledTimes(1);
run.snapshot!.artifacts = listed.artifacts;
await expect(
service.content(
{ ...run, principal: { ...run.principal, userId: new mongoose.Types.ObjectId().toString() } },
listed.artifacts[0].artifactId,
),
).rejects.toMatchObject({ code: 'artifact_unavailable' });
await expect(
service.content({ ...run, tenantId: 'tenant-b' }, listed.artifacts[0].artifactId),
).rejects.toMatchObject({ code: 'artifact_unavailable' });
});
it('rejects unknown identifiers before storage and rejects changed bytes even at the same length', async () => {
const file = await publish('before');
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
jest.mocked(deps.readFile).mockClear();
for (const id of [
'https://untrusted.invalid/file',
'/etc/passwd',
file.file_id,
`${file.file_id}:${digest('other')}`,
]) {
await expect(service.content(run, id)).rejects.toMatchObject({ code: 'artifact_unavailable' });
}
expect(deps.readFile).not.toHaveBeenCalled();
contentByFile.set(file.file_id, Buffer.from('after!'));
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_changed',
});
contentByFile.set(file.file_id, Buffer.from('longer bytes'));
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_changed',
});
});
it('resolves default tenant artifacts without matching files in a named tenant', async () => {
const file = await publish('default tenant', { ...scope, tenantId: undefined });
await publish('named tenant');
await runAsSystem(() =>
mongoose.models.Message.collection.insertOne({
user: userId,
conversationId: scope.conversationId,
messageId: scope.runId,
isCreatedByUser: false,
attachments: [],
}),
);
const defaultRun = { ...run, tenantId: '_' };
const listed = await service.list(defaultRun, defaultRun.snapshot!);
expect(listed.artifacts).toHaveLength(1);
expect(listed.artifacts[0].artifactId).toBe(`${file.file_id}:${digest('default tenant')}`);
});
it('rechecks expiry at download even when the snapshot still advertises the file', async () => {
const file = await publish();
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
await tenantStorage.run({ tenantId: 'tenant-a' }, () =>
mongoose.models.File.updateOne({ file_id: file.file_id }, { $set: { expiredAt: new Date(0) } }),
);
jest.mocked(deps.readFile).mockClear();
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_unavailable',
});
expect(deps.readFile).not.toHaveBeenCalled();
});
it('bounds declared size, actual streamed bytes and number of files without erasing answer text', async () => {
limits.artifactMaxBytes = 8;
await publish('too many bytes', scope);
await publish('lying stream exceeds limit', { ...scope, sourceFileId: 'lying' }, { bytes: 1 });
await publish('valid', { ...scope, sourceFileId: 'valid' });
const listed = await service.list(run, run.snapshot!);
expect(listed.unavailable).toBe(true);
expect(listed.artifacts).toHaveLength(1);
expect(listed.artifacts[0].bytes).toBe(5);
expect(deps.readFile).toHaveBeenCalledTimes(2);
expect(run.snapshot!.text).toBe('answer');
limits.artifactMaxFiles = 1;
jest.mocked(deps.readFile).mockClear();
expect((await service.list(run, run.snapshot!)).unavailable).toBe(true);
expect(jest.mocked(deps.readFile).mock.calls.length).toBeLessThanOrEqual(1);
});
it('preserves safe source fallback when optional storage is unsupported or unavailable', async () => {
await publish();
run.snapshot!.text = '```sql\nSELECT 1\n```';
jest.mocked(deps.readFile).mockResolvedValueOnce(null);
const unsupported = await service.list(run, run.snapshot!);
expect(unsupported.unavailable).toBe(true);
expect(unsupported.artifacts).toEqual([
{
artifactId: `answer:${digest(run.snapshot!.text)}`,
filename: 'agent-response.md',
mediaType: 'text/markdown',
bytes: Buffer.byteLength(run.snapshot!.text),
sha256: digest(run.snapshot!.text),
},
]);
jest.mocked(deps.readFile).mockRejectedValueOnce(new Error('storage unavailable'));
expect(await service.list(run, run.snapshot!)).toEqual(unsupported);
run.snapshot!.artifacts = unsupported.artifacts;
expect((await service.content(run, unsupported.artifacts[0].artifactId)).bytes.toString()).toBe(
run.snapshot!.text,
);
run.snapshot!.text = 'changed source';
await expect(service.content(run, unsupported.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_changed',
});
});
it('bounds source fallback at listing and honors a reduced byte limit at download', async () => {
run.snapshot!.text = 'a'.repeat(6001);
const listed = await service.list(run, run.snapshot!);
expect(listed.artifacts).toHaveLength(1);
run.snapshot!.artifacts = listed.artifacts;
limits.artifactMaxBytes = 100;
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_too_large',
});
expect((await service.list(run, run.snapshot!)).artifacts).toEqual([]);
});
it('destroys timed out or invalid streams without losing retained response text', async () => {
await publish();
limits.artifactReadTimeoutMs = 15;
run.snapshot!.text = '```text\nanswer\n```';
const hanging = new Readable({ read() {} });
jest.mocked(deps.readFile).mockResolvedValueOnce(hanging);
const listed = await service.list(run, run.snapshot!);
expect(hanging.destroyed).toBe(true);
expect(listed.unavailable).toBe(true);
expect(listed.artifacts).toEqual([]);
expect(run.snapshot!.text).toBe('```text\nanswer\n```');
const invalid = Readable.from([{ unexpected: 'object' }]);
jest.mocked(deps.readFile).mockResolvedValueOnce(invalid);
expect((await service.list(run, run.snapshot!)).unavailable).toBe(true);
expect(invalid.destroyed).toBe(true);
});
it('does not resolve files for incomplete or missing responses, but propagates database failures', async () => {
const readArtifacts = jest.spyOn(deps, 'readArtifacts');
expect(await service.list(run, { ...run.snapshot!, status: 'running' })).toEqual({
artifacts: [],
unavailable: false,
});
expect(await service.list(run, { ...run.snapshot!, responseId: undefined })).toEqual({
artifacts: [],
unavailable: false,
});
expect(readArtifacts).not.toHaveBeenCalled();
readArtifacts.mockRejectedValueOnce(new Error('database unavailable'));
await expect(service.list(run, run.snapshot!)).rejects.toThrow('database unavailable');
});
it('binds both catalog and stored content to the exact execution response', async () => {
await publish();
await expect(
service.list(run, { ...run.snapshot!, responseId: 'previous-response' }),
).rejects.toMatchObject({ code: 'artifact_changed' });
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
run.execution!.responseId = 'another-response';
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_changed',
});
});
it.each([FileContext.execute_code, FileContext.execute_code_snapshot])(
'includes only owned generated attachments and bounds reader metadata for %s',
async (context) => {
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, async () => {
for (let index = 0; index < 8; index++) {
const id = `ordinary-${index}`;
await mongoose.models.File.create({
file_id: id,
user: userId,
tenantId: scope.tenantId,
conversationId: scope.conversationId,
filename: `${id}.txt`,
filepath: `/uploads/${id}`,
type: 'text/plain',
source: FileSources.local,
bytes: 6,
context,
metadata: generatedMetadata(),
text: 'private extracted text',
});
contentByFile.set(id, Buffer.from('result'));
}
await mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{
$set: {
attachments: Array.from({ length: 7 }, (_, index) => ({
file_id: `ordinary-${index}`,
metadata: generatedMetadata(),
})),
},
},
);
const catalog = await db.readResponseArtifacts(scope, { kind: 'list', limit: 3 });
expect(catalog).toHaveLength(3);
for (const file of catalog!) {
expect(file).not.toHaveProperty('text');
expect(file).not.toHaveProperty('metadata');
expect(file).not.toHaveProperty('_id');
}
});
limits.artifactMaxFiles = 2;
const listed = await service.list(run, run.snapshot!);
expect(listed.unavailable).toBe(true);
expect(listed.artifacts).toHaveLength(2);
expect(listed.artifacts.every((file) => !file.artifactId.startsWith('ordinary-7:'))).toBe(true);
run.snapshot!.artifacts = listed.artifacts;
limits.artifactMaxFiles = 1;
expect((await service.content(run, listed.artifacts[1].artifactId)).bytes.toString()).toBe(
'result',
);
},
);
it('refuses expired response retention for generated files and answer fallbacks', async () => {
await publish();
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, () =>
mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{ $set: { expiredAt: new Date(Date.now() - 1) } },
),
);
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_unavailable',
});
run.snapshot!.text = '```text\nanswer\n```';
expect(await service.list(run, run.snapshot!)).toEqual({ artifacts: [], unavailable: true });
});
it('never discovers a later turn through a reused generated-file ID, including an in-flight overwrite', () =>
tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, async () => {
const file_id = await generate();
const original = await service.list(run, run.snapshot!);
expect(original.artifacts[0].sha256).toBe(digest('before'));
run.snapshot!.artifacts = original.artifacts;
// The object write can finish while the row still describes the previous bytes.
contentByFile.set(file_id, Buffer.from('after!'));
expect(await service.list(run, run.snapshot!)).toEqual({ artifacts: [], unavailable: true });
await expect(service.content(run, original.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_unavailable',
});
const messageId = 'response-later';
const metadata = generatedMetadata(messageId, 'after!');
await mongoose.models.File.updateOne({ file_id }, { $set: { metadata } });
expect(
(await mongoose.models.File.findOne({ file_id }).lean<{ messageId: string }>())?.messageId,
).toBe(scope.runId);
expect(await deps.readArtifacts(scope, { kind: 'list', limit: 21 })).toEqual([]);
expect(await deps.readArtifacts(scope, { kind: 'file', fileId: file_id })).toEqual([]);
await mongoose.models.Message.create({
user: userId,
tenantId: scope.tenantId,
conversationId: scope.conversationId,
messageId,
isCreatedByUser: false,
sender: 'Agent',
endpoint: 'agents',
model: 'agent-a',
text: 'Later response',
attachments: [{ file_id, metadata }],
});
const later = {
...run,
execution: { ...run.execution!, responseId: messageId },
snapshot: { ...run.snapshot!, responseId: messageId },
};
const current = await service.list(later, later.snapshot);
expect(current.artifacts[0].sha256).toBe(digest('after!'));
later.snapshot.artifacts = current.artifacts;
expect((await service.content(later, current.artifacts[0].artifactId)).bytes.toString()).toBe(
'after!',
);
}));
it('requires the attachment content witness even when a new write reuses the same message ID', () =>
tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, async () => {
const file_id = await generate();
const original = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = original.artifacts;
const metadata = generatedMetadata(scope.runId, 'after!');
contentByFile.set(file_id, Buffer.from('after!'));
await mongoose.models.File.updateOne({ file_id }, { $set: { metadata } });
expect(await deps.readArtifacts(scope, { kind: 'list', limit: 21 })).toEqual([]);
await mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{ $set: { attachments: [{ file_id, metadata }] } },
);
expect((await service.list(run, run.snapshot!)).artifacts[0].sha256).toBe(digest('after!'));
await expect(service.content(run, original.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_changed',
});
}));
it('bounds stream acquisition even when its reader ignores cancellation and destroys late streams', async () => {
await publish();
limits.artifactReadTimeoutMs = 15;
run.snapshot!.text = '```text\nanswer\n```';
let deliver!: (stream: Readable) => void;
const stalled = new Promise<Readable>((resolve) => {
deliver = resolve;
});
jest.mocked(deps.readFile).mockReturnValueOnce(stalled);
const listed = await service.list(run, run.snapshot!);
expect(listed.unavailable).toBe(true);
expect(listed.artifacts).toEqual([]);
const late = new Readable({
read() {},
destroy(_error, callback) {
callback(new Error('late cleanup failure'));
},
});
deliver(late);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(late.destroyed).toBe(true);
});
it('rejects invalid catalog bounds and cross-tenant contexts rather than hiding query failures', async () => {
for (const limit of [0, 22, 1.5, Number.MAX_SAFE_INTEGER]) {
await expect(deps.readArtifacts(scope, { kind: 'list', limit })).rejects.toThrow('page size');
}
await expect(
tenantStorage.run({ tenantId: 'tenant-b' }, () =>
db.readResponseArtifacts(scope, { kind: 'authorize' }),
),
).rejects.toThrow('authenticated scope');
await expect(
deps.readArtifacts({ ...scope, tenantId: '_' }, { kind: 'authorize' }),
).rejects.toThrow('Reserved tenant identifier');
});
it('requires the actual response attachment and rejects expired, foreign-owner and foreign-conversation generated files', async () => {
const attachmentIds: string[] = [];
await runAsSystem(async () => {
for (const [id, extra] of [
['allowed-generated', {}],
['unreferenced-generated', {}],
['expired-generated', { expiresAt: new Date(0) }],
['foreign-owner', { user: new mongoose.Types.ObjectId() }],
['foreign-conversation', { conversationId: 'other' }],
['foreign-tenant', { tenantId: 'tenant-b' }],
['unversioned', { metadata: {} }],
['wrong-message', { metadata: generatedMetadata('another-response') }],
['wrong-digest', { metadata: generatedMetadata(scope.runId, 'changed') }],
] as const) {
await mongoose.models.File.collection.insertOne({
file_id: id,
user: new mongoose.Types.ObjectId(userId),
tenantId: scope.tenantId,
conversationId: scope.conversationId,
filename: id,
filepath: '/uploads/result',
bytes: 6,
type: 'text/plain',
source: FileSources.local,
context: FileContext.execute_code,
metadata: generatedMetadata(),
...extra,
});
if (id !== 'unreferenced-generated') attachmentIds.push(id);
}
});
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, () =>
mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{
$set: {
attachments: attachmentIds.map((file_id) => ({ file_id, metadata: generatedMetadata() })),
},
},
),
);
expect(
(await deps.readArtifacts(scope, { kind: 'list', limit: 21 }))?.map((file) => file.file_id),
).toEqual(['allowed-generated']);
expect(
await deps.readArtifacts(scope, { kind: 'file', fileId: 'unreferenced-generated' }),
).toEqual([]);
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, () =>
mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{ $set: { isCreatedByUser: true } },
),
);
expect(await deps.readArtifacts(scope, { kind: 'authorize' })).toBeNull();
});
it.each([0, 1])(
'bounds all files and policy resolution after %i successful reads by one deadline',
async (successful) => {
const files: ResponseArtifactFile[] = [];
for (let index = 0; index < 3; index++)
files.push(await publish('result', { ...scope, sourceFileId: `source-${index}` }));
deps.readArtifacts = jest.fn(async (_scope, query) => (query.kind === 'list' ? files : []));
limits.artifactReadTimeoutMs = 50;
const late: Array<(stream: Readable) => void> = [];
let reads = 0;
jest
.mocked(deps.readFile)
.mockImplementation(() =>
reads++ < successful
? Promise.resolve(Readable.from(['result']))
: new Promise<Readable>((resolve) => late.push(resolve)),
);
jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
try {
deps.limits = () => new Promise((resolve) => setTimeout(() => resolve(limits), 20));
let settled = false;
const listing = service.list(run, run.snapshot!).then((result) => {
settled = true;
return result;
});
await jest.advanceTimersByTimeAsync(50);
const settledAtBudget = settled;
await jest.advanceTimersByTimeAsync(200);
const result = await listing;
expect(settledAtBudget).toBe(true);
expect(deps.readFile).toHaveBeenCalledTimes(successful + 1);
expect(result).toEqual({ artifacts: [], unavailable: true });
} finally {
jest.useRealTimers();
for (const resolve of late) resolve(Readable.from(['late']));
await new Promise<void>((resolve) => setImmediate(resolve));
}
},
);
it.each(['list', 'authorize'] as const)(
'bounds a stalled %s query without exposing an unverified answer file',
async (stalledKind) => {
limits.artifactReadTimeoutMs = 50;
run.snapshot!.text = '```text\nanswer\n```';
let release!: () => void;
const stalled = new Promise<[]>((resolve) => {
release = () => resolve([]);
});
deps.readArtifacts = jest.fn(async (_scope, query) =>
query.kind === stalledKind ? stalled : [],
);
jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
try {
let settled = false;
const listing = service.list(run, run.snapshot!).then((result) => {
settled = true;
return result;
});
await jest.advanceTimersByTimeAsync(50);
const settledAtBudget = settled;
release();
const result = await listing;
expect(settledAtBudget).toBe(true);
expect(result).toEqual({ artifacts: [], unavailable: true });
expect(deps.readFile).not.toHaveBeenCalled();
} finally {
release();
jest.useRealTimers();
}
},
);
it('rejects user-submitted assistant-shaped rows for all catalog reads and saved descriptors', async () => {
const file = await publish();
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
await tenantStorage.run({ tenantId: scope.tenantId ?? undefined }, () =>
mongoose.models.Message.updateOne(
{ messageId: scope.runId, user: userId },
{ $set: { isUserSubmitted: true } },
),
);
for (const query of [
{ kind: 'list', limit: 4 },
{ kind: 'file', fileId: file.file_id },
{ kind: 'authorize' },
] as const)
expect(await deps.readArtifacts(scope, query)).toBeNull();
await expect(service.content(run, listed.artifacts[0].artifactId)).rejects.toMatchObject({
code: 'artifact_unavailable',
});
run.snapshot!.text = '```text\nanswer\n```';
expect(await service.list(run, run.snapshot!)).toEqual({ artifacts: [], unavailable: true });
});
it('uses the configured byte threshold for new answer files and preserves authorized saved identities', async () => {
run.snapshot!.text = 'ééé';
limits.artifactAnswerFileThresholdBytes = 5;
const listed = await service.list(run, run.snapshot!);
expect(listed.artifacts).toHaveLength(1);
expect(listed.artifacts[0].bytes).toBe(6);
run.snapshot!.artifacts = listed.artifacts;
limits.artifactAnswerFileThresholdBytes = 6;
expect((await service.list(run, run.snapshot!)).artifacts).toEqual([]);
expect((await service.content(run, listed.artifacts[0].artifactId)).bytes.toString()).toBe('ééé');
run.snapshot!.text = '```text\nshort\n```';
expect((await service.list(run, run.snapshot!)).artifacts).toHaveLength(1);
});
it('bounds a stalled policy lookup by the schema hard maximum and never starts late catalog work', async () => {
let release!: () => void;
deps.limits = () =>
new Promise((resolve) => {
release = () => resolve(limits);
});
deps.readArtifacts = jest.fn(async () => []);
jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
try {
const listing = service.list(run, run.snapshot!);
await jest.advanceTimersByTimeAsync(60_000);
expect(await listing).toEqual({ artifacts: [], unavailable: true });
release();
await Promise.resolve();
expect(deps.readArtifacts).not.toHaveBeenCalled();
} finally {
release();
jest.useRealTimers();
}
});
it('keeps downloads inside the same budget through final reauthorization', async () => {
const file = await publish();
const listed = await service.list(run, run.snapshot!);
run.snapshot!.artifacts = listed.artifacts;
limits.artifactReadTimeoutMs = 50;
let release!: () => void;
const authorization = new Promise<[]>((resolve) => {
release = () => resolve([]);
});
deps.readArtifacts = jest.fn(async (_scope, query) =>
query.kind === 'file' ? [file] : authorization,
);
jest.useFakeTimers({ doNotFake: ['nextTick', 'setImmediate'] });
try {
let settled = false;
const download = service.content(run, listed.artifacts[0].artifactId).then(
() => {
settled = true;
return undefined;
},
(error: Error) => {
settled = true;
return error;
},
);
await jest.advanceTimersByTimeAsync(50);
const settledAtBudget = settled;
release();
expect(await download).toMatchObject({ code: 'artifact_unavailable' });
expect(settledAtBudget).toBe(true);
} finally {
release();
jest.useRealTimers();
}
});
it('uses at most one storage stream while listing the maximum number of artifacts', async () => {
limits.artifactMaxFiles = 20;
for (let index = 0; index < 20; index++)
await publish('result', { ...scope, sourceFileId: `bounded-${index}` });
let active = 0;
let maximumActive = 0;
jest.mocked(deps.readFile).mockImplementation(async () => {
active++;
maximumActive = Math.max(maximumActive, active);
return new Readable({
read() {
this.push('result');
this.push(null);
},
destroy(_error, callback) {
active--;
callback(null);
},
});
});
const listed = await service.list(run, run.snapshot!);
expect(listed.artifacts).toHaveLength(20);
expect(maximumActive).toBe(1);
expect(active).toBe(0);
});

View file

@ -0,0 +1,311 @@
import { basename } from 'node:path';
import { createHash } from 'node:crypto';
import { CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS } from 'librechat-data-provider';
import type {
ChannelRunRecord,
RunArtifactRunScope,
ResponseArtifactFile,
ResponseArtifactQuery,
} from '@librechat/data-schemas';
import type { ChannelArtifact, ChannelRunSnapshot } from 'librechat-data-provider';
import type { ChannelConfig } from 'librechat-data-provider';
import type { Readable } from 'node:stream';
type ArtifactLimits = Pick<
ChannelConfig,
| 'artifactMaxBytes'
| 'artifactMaxFiles'
| 'artifactReadTimeoutMs'
| 'artifactAnswerFileThresholdBytes'
>;
type ArtifactContent = { bytes: Buffer; sha256: string };
export interface ChannelArtifactDependencies {
/** Null means the owned assistant response is absent or expired; failures propagate. */
readArtifacts: (
scope: RunArtifactRunScope,
query: ResponseArtifactQuery,
) => Promise<ResponseArtifactFile[] | null>;
readFile: (
file: ResponseArtifactFile,
run: ChannelRunRecord,
signal: AbortSignal,
) => Promise<Readable | null>;
limits: () => Promise<ArtifactLimits>;
}
export class ChannelArtifactError extends Error {
constructor(readonly code: 'artifact_unavailable' | 'artifact_changed' | 'artifact_too_large') {
super(code);
this.name = 'ChannelArtifactError';
}
}
const hash = (buffer: Buffer) => createHash('sha256').update(buffer).digest('hex');
const filename = (value: string) =>
basename(value.replace(/\\/g, '/'))
.replace(/\p{Cc}/gu, '')
.slice(0, 180) || 'artifact.bin';
const mediaType = (value: string) =>
/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/i.test(value) ? value : 'application/octet-stream';
export interface ChannelArtifactService {
list(
run: ChannelRunRecord,
snapshot: ChannelRunSnapshot,
): Promise<{ artifacts: ChannelArtifact[]; unavailable: boolean }>;
content(
run: ChannelRunRecord,
artifactId: string,
): Promise<{ descriptor: ChannelArtifact; bytes: Buffer }>;
}
function artifactScope(run: ChannelRunRecord, responseId: string): RunArtifactRunScope {
if (!run.execution || run.execution.responseId !== responseId)
throw new ChannelArtifactError('artifact_changed');
return {
userId: run.principal.userId,
tenantId: run.tenantId === '_' ? undefined : run.tenantId || undefined,
conversationId: run.execution.conversationId,
runId: responseId,
};
}
export function isChannelArtifactExpired(file: ResponseArtifactFile): boolean {
return [file.expiredAt, file.expiresAt].some(
(value) =>
value != null &&
(!Number.isFinite(new Date(value).getTime()) || new Date(value).getTime() <= Date.now()),
);
}
/** Policy lookup is capped by the schema maximum; the selected budget tightens from invocation. */
class ArtifactBudget {
private readonly controller = new AbortController();
readonly signal = this.controller.signal;
private readonly startedAt = performance.now();
private expiresAt = this.startedAt + CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS;
private timer: ReturnType<typeof setTimeout>;
constructor() {
this.timer = setTimeout(
() => this.controller.abort(),
CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS,
);
}
tighten(timeoutMs: number): void {
if (
!Number.isSafeInteger(timeoutMs) ||
timeoutMs < 1 ||
timeoutMs > CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS
)
throw new TypeError('Invalid artifact operation timeout');
this.expiresAt = Math.min(this.expiresAt, this.startedAt + timeoutMs);
clearTimeout(this.timer);
this.assertActive();
this.timer = setTimeout(
() => this.controller.abort(),
Math.ceil(this.expiresAt - performance.now()),
);
}
assertActive(): void {
if (this.signal.aborted || performance.now() >= this.expiresAt) {
this.controller.abort();
throw new ChannelArtifactError('artifact_unavailable');
}
}
async run<T>(work: () => Promise<T>): Promise<T> {
this.assertActive();
let rejectAbort!: (error: ChannelArtifactError) => void;
const expired = new Promise<never>((_resolve, reject) => {
rejectAbort = reject;
});
const aborted = () => rejectAbort(new ChannelArtifactError('artifact_unavailable'));
this.signal.addEventListener('abort', aborted, { once: true });
try {
const result = await Promise.race([
Promise.resolve().then(() => {
this.assertActive();
return work();
}),
expired,
]);
this.assertActive();
return result;
} finally {
// A shared pending race promise would retain every completed file buffer until operation end.
this.signal.removeEventListener('abort', aborted);
}
}
dispose(): void {
clearTimeout(this.timer);
this.controller.abort();
}
}
function destroyStream(stream: Readable | null): void {
if (!stream) return;
stream.once('error', () => {});
stream.destroy();
}
/** One deadline and one bounded stream at a time cover policy, catalog and current authorization. */
export function createChannelArtifactService(
deps: ChannelArtifactDependencies,
): ChannelArtifactService {
async function read(
run: ChannelRunRecord,
file: ResponseArtifactFile,
limits: ArtifactLimits,
budget: ArtifactBudget,
): Promise<ArtifactContent | null> {
if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || file.bytes > limits.artifactMaxBytes)
return null;
let stream: Readable | null = null;
const abort = () => destroyStream(stream);
budget.signal.addEventListener('abort', abort, { once: true });
const acquisition = Promise.resolve().then(() => {
budget.assertActive();
return deps.readFile(file, run, budget.signal);
});
void acquisition.then(
(late) => {
if (budget.signal.aborted) destroyStream(late);
},
() => {},
);
try {
stream = await budget.run(() => acquisition);
if (!stream) return null;
const acquired = stream;
return await budget.run(async () => {
let length = 0;
const chunks: Buffer[] = [];
for await (const chunk of acquired) {
budget.assertActive();
if (!Buffer.isBuffer(chunk) && typeof chunk !== 'string')
throw new ChannelArtifactError('artifact_unavailable');
length += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
if (length > limits.artifactMaxBytes)
throw new ChannelArtifactError('artifact_too_large');
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
}
if (isChannelArtifactExpired(file)) return null;
const content = Buffer.concat(chunks, length);
const sha256 = hash(content);
// A reused file's bytes can change before its metadata write commits.
if (file.sha256 != null && sha256 !== file.sha256) return null;
return { bytes: content, sha256 };
});
} finally {
budget.signal.removeEventListener('abort', abort);
destroyStream(stream);
}
}
return {
async list(run, snapshot) {
if (snapshot.status !== 'completed' || !snapshot.responseId)
return { artifacts: [], unavailable: false };
const scope = artifactScope(run, snapshot.responseId);
const budget = new ArtifactBudget();
try {
const limits = await budget.run(() => deps.limits());
budget.tighten(limits.artifactReadTimeoutMs);
const candidates = await budget.run(() =>
deps.readArtifacts(scope, { kind: 'list', limit: limits.artifactMaxFiles + 1 }),
);
if (!candidates) return { artifacts: [], unavailable: true };
const descriptors: ChannelArtifact[] = [];
let unavailable = candidates.length > limits.artifactMaxFiles;
for (const file of candidates.slice(0, limits.artifactMaxFiles)) {
budget.assertActive();
let content: ArtifactContent | null;
try {
content = await read(run, file, limits, budget);
} catch {
budget.assertActive();
unavailable = true;
continue;
}
if (!content) {
unavailable = true;
continue;
}
const { sha256 } = content;
descriptors.push({
artifactId: `${file.file_id}:${sha256}`,
filename: filename(file.filename),
mediaType: mediaType(file.type),
bytes: content.bytes.length,
sha256,
});
}
const answerLength = Buffer.byteLength(snapshot.text);
if (
!descriptors.length &&
(snapshot.text.includes('```') ||
answerLength > limits.artifactAnswerFileThresholdBytes) &&
answerLength <= limits.artifactMaxBytes
) {
const answer = Buffer.from(snapshot.text);
const sha256 = hash(answer);
descriptors.push({
artifactId: `answer:${sha256}`,
filename: 'agent-response.md',
mediaType: 'text/markdown',
bytes: answer.length,
sha256,
});
}
if (!(await budget.run(() => deps.readArtifacts(scope, { kind: 'authorize' }))))
return { artifacts: [], unavailable: true };
return { artifacts: descriptors, unavailable };
} catch (error) {
if (budget.signal.aborted) return { artifacts: [], unavailable: true };
throw error;
} finally {
budget.dispose();
}
},
async content(run, artifactId) {
const descriptor = run.snapshot?.artifacts?.find((item) => item.artifactId === artifactId);
if (!descriptor || run.snapshot?.status !== 'completed' || !run.snapshot.responseId)
throw new ChannelArtifactError('artifact_unavailable');
const scope = artifactScope(run, run.snapshot.responseId);
const budget = new ArtifactBudget();
try {
const limits = await budget.run(() => deps.limits());
budget.tighten(limits.artifactReadTimeoutMs);
if (descriptor.bytes > limits.artifactMaxBytes)
throw new ChannelArtifactError('artifact_too_large');
let content: ArtifactContent | null;
if (artifactId === `answer:${descriptor.sha256}`) {
if (!(await budget.run(() => deps.readArtifacts(scope, { kind: 'authorize' }))))
throw new ChannelArtifactError('artifact_unavailable');
if (Buffer.byteLength(run.snapshot.text) > limits.artifactMaxBytes)
throw new ChannelArtifactError('artifact_too_large');
const bytes = Buffer.from(run.snapshot.text);
content = { bytes, sha256: hash(bytes) };
} else {
const suffix = `:${descriptor.sha256}`;
if (!artifactId.endsWith(suffix)) throw new ChannelArtifactError('artifact_changed');
const files = await budget.run(() =>
deps.readArtifacts(scope, {
kind: 'file',
fileId: artifactId.slice(0, -suffix.length),
}),
);
content = files?.[0] ? await read(run, files[0], limits, budget) : null;
}
if (!content || !(await budget.run(() => deps.readArtifacts(scope, { kind: 'authorize' }))))
throw new ChannelArtifactError('artifact_unavailable');
if (content.bytes.length !== descriptor.bytes || content.sha256 !== descriptor.sha256)
throw new ChannelArtifactError('artifact_changed');
budget.assertActive();
return { descriptor, bytes: content.bytes };
} finally {
budget.dispose();
}
},
};
}

View file

@ -0,0 +1,479 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { configCapability, SystemCapabilities } from '@librechat/data-schemas';
import type {
ChannelRunRecord,
ChannelSummaryRow,
IMessage,
SystemCapability,
} from '@librechat/data-schemas';
import type { ChannelRunSnapshot, ResponseAccounting } from 'librechat-data-provider';
import type { ChannelSummaryTraceDependencies } from './summary';
import type { CapabilityUser } from '~/middleware/capabilities';
import type { ChannelMessage } from './types';
import { createChannelSummaryService, createChannelSummaryTraceResolver } from './summary';
import { getLangfuseDestinationId } from '~/langfuse/destinations';
function priced(amount = '0.1'): ResponseAccounting {
return {
status: 'available',
currency: 'USD',
amount,
basis: 'application_billing',
coverage: 'complete',
reason: 'priced',
calls: [
{
modelSource: 'configured',
usageType: 'message',
inputTokens: 2,
outputTokens: 3,
cacheReadTokens: 0,
cacheWriteTokens: 0,
amount,
basis: 'application_billing',
reason: 'priced',
},
],
};
}
function snapshot(overrides: Partial<ChannelRunSnapshot> = {}): ChannelRunSnapshot {
return {
status: 'completed',
text: 'Private answer must not appear in summary',
elapsedMs: 10,
responseId: 'response',
usage: { inputTokens: 2, outputTokens: 3, totalTokens: 5 },
accounting: priced(),
...overrides,
};
}
function run(sequence = 1): ChannelRunRecord {
return {
tenantId: 'tenant',
channelId: 'channel',
agentId: 'agent',
laneId: 'actor-lane',
runId: 'run',
sequence,
state: 'executing',
receivedAt: 1,
payloadHash: 'hash',
leaseEpoch: 1,
leaseExpiresAt: 100,
receipts: [],
cancellationRequested: false,
principal: { userId: 'user', channelRevision: 'revision', linkId: 'link', linkRevision: 'r1' },
admission: {
eventId: 'event',
externalChannelId: 'C1',
externalThreadKey: 'C1:123',
externalMessageKey: 'C1:124',
input: 'Private input must not appear in summary',
actor: { teamId: 'T1', appId: 'A1', externalUserId: 'U1' },
},
execution: {
requestId: 'request',
responseId: 'response',
protocol: 'responses',
conversationId: 'conversation',
parentMessageId: 'parent',
},
};
}
function service(rows: ChannelSummaryRow[] = [], trace?: ChannelSummaryTraceDependencies) {
return createChannelSummaryService({
storage: {
async *priorMetrics() {
yield* rows;
},
},
trace,
});
}
describe('actor-lane summary', () => {
it('adds current exactly once to prior attempts with exact decimal arithmetic', async () => {
const result = await service([
{ sequence: 2, snapshot: snapshot({ status: 'cancelled', accounting: priced('0.2') }) },
{ sequence: 1, snapshot: snapshot({ status: 'failed', accounting: priced('0.3') }) },
]).summarize(run(3), snapshot());
expect(result).toEqual({
version: 1,
scope: 'actor_lane',
throughSequence: 3,
includesCurrent: true,
priorRuns: 2,
expectedRuns: 3,
observedRuns: 3,
costUSD: { coverage: 'complete', coveredRuns: 3, value: '0.6', basis: 'application_billing' },
elapsedMs: { coverage: 'complete', coveredRuns: 3, value: 30 },
tokens: {
coverage: 'complete',
coveredRuns: 3,
value: { inputTokens: 6, outputTokens: 9, totalTokens: 15 },
},
});
expect(JSON.stringify(result)).not.toContain('Private');
});
it('retains all 18 fraction digits and amounts beyond Decimal128 precision', async () => {
const result = await service([
{
sequence: 1,
snapshot: snapshot({
accounting: priced('10000000000000000000000000000000000.000000000000000001'),
}),
},
]).summarize(run(2), snapshot({ accounting: priced('0.000000000000000002') }));
expect(result.costUSD.value).toBe('10000000000000000000000000000000000.000000000000000003');
});
it('marks truncated or missing prior sequence coverage partial without claiming a total', async () => {
const result = await service([{ sequence: 999, snapshot: snapshot() }]).summarize(
run(1001),
snapshot(),
);
expect(result).toMatchObject({ expectedRuns: 1001, observedRuns: 2, priorRuns: 1 });
expect(result.costUSD).toEqual({
coverage: 'partial',
coveredRuns: 2,
knownValue: '0.2',
basis: 'application_billing',
});
expect(result.elapsedMs).toEqual({ coverage: 'partial', coveredRuns: 2, knownValue: 20 });
expect(result.tokens.value).toBeUndefined();
});
it('keeps unavailable or running/legacy snapshots as coverage gaps, never invented zeros', async () => {
const result = await service([
{ sequence: 1 },
{ sequence: 2, snapshot: snapshot({ status: 'running' }) },
]).summarize(run(3), snapshot({ usage: undefined, accounting: undefined }));
expect(result.costUSD).toEqual({ coverage: 'unavailable', coveredRuns: 0 });
expect(result.tokens).toEqual({ coverage: 'unavailable', coveredRuns: 0 });
expect(result.elapsedMs).toEqual({ coverage: 'partial', coveredRuns: 1, knownValue: 10 });
});
it('does not mix provider-invoice and application-billing costs', async () => {
const result = await service([
{
sequence: 1,
snapshot: snapshot({ accounting: { ...priced(), basis: 'provider_reported' } }),
},
]).summarize(run(2), snapshot());
expect(result.costUSD).toEqual({ coverage: 'unavailable', coveredRuns: 0 });
expect(result.tokens.coverage).toBe('complete');
});
it.each(['-1', 'NaN', '1e3', '0.1234567890123456789', ''])(
'rejects malformed amount %s',
async (amount) => {
const result = await service().summarize(run(), snapshot({ accounting: priced(amount) }));
expect(result.costUSD).toEqual({ coverage: 'unavailable', coveredRuns: 0 });
},
);
it('accepts actual priced zero but does not convert missing usage to a zero token total', async () => {
const result = await service().summarize(
run(),
snapshot({ accounting: priced('0'), usage: undefined }),
);
expect(result.costUSD.value).toBe('0');
expect(result.tokens.coverage).toBe('unavailable');
});
it('suppresses partial cost amounts and invalid numeric totals independently', async () => {
const result = await service([
{ sequence: 1, snapshot: snapshot({ elapsedMs: Number.MAX_SAFE_INTEGER }) },
]).summarize(
run(2),
snapshot({
accounting: { ...priced('900'), status: 'unavailable', coverage: 'partial' },
usage: { inputTokens: -1, outputTokens: 3, totalTokens: 2 },
}),
);
expect(result.costUSD).toEqual({
coverage: 'partial',
coveredRuns: 1,
knownValue: '0.1',
basis: 'application_billing',
});
expect(result.elapsedMs.coverage).toBe('unavailable');
expect(result.tokens).toMatchObject({ coverage: 'partial', coveredRuns: 1 });
});
it('reuses frozen summary without new reads on retry', async () => {
const frozen = await service().summarize(run(), snapshot());
const priorMetrics = jest.fn(async function* () {
yield* [];
throw new Error('must not read');
});
const result = await createChannelSummaryService({ storage: { priorMetrics } }).summarize(
{ ...run(), snapshot: { ...snapshot(), summary: frozen } },
snapshot({ accounting: priced('999') }),
);
expect(result).toEqual(frozen);
expect(priorMetrics).not.toHaveBeenCalled();
});
it('propagates storage outages instead of returning complete empty history', async () => {
const storage = {
async *priorMetrics(): AsyncIterable<ChannelSummaryRow> {
yield* [];
throw new Error('database unavailable');
},
};
await expect(
createChannelSummaryService({ storage }).summarize(run(), snapshot()),
).rejects.toThrow('database unavailable');
});
});
it('normalizes an actual Mongo lean ObjectId without assuming an id virtual', async () => {
const mongo = await MongoMemoryServer.create({ instance: { args: ['--nounixsocket'] } });
const connection = await mongoose.createConnection(mongo.getUri()).asPromise();
try {
const User = connection.model(
'SummaryUser',
new mongoose.Schema({ tenantId: String, role: String }),
);
const saved = await User.create({ tenantId: 'tenant', role: 'ADMIN' });
const lean = await User.findById(saved._id).lean();
expect(lean).not.toHaveProperty('id');
const getHeldCapabilities = jest.fn(
async (_user: CapabilityUser) =>
new Set([SystemCapabilities.ACCESS_ADMIN, SystemCapabilities.MANAGE_CONFIGS]),
);
const resolver = createChannelSummaryTraceResolver({
findUser: async () => lean,
getHeldCapabilities,
getConfig: async () => undefined,
getMessages: async () => [],
getMessage: async () => null,
});
const owned = run();
owned.principal.userId = saved._id.toString();
expect(await resolver.canViewSession(owned)).toBe(true);
expect(getHeldCapabilities.mock.calls[0]?.[0]).toMatchObject({
id: saved._id.toString(),
tenantId: 'tenant',
});
expect(await resolver.canViewSession(run())).toBe(false);
} finally {
await connection.close();
await mongo.stop();
}
}, 60000);
describe('authorized saved session provenance', () => {
const url = 'https://cloud.langfuse.com/project/project/sessions/conversation';
let message: ChannelMessage;
let trace: ChannelSummaryTraceDependencies;
beforeEach(() => {
message = {
user: 'user',
tenantId: 'tenant',
messageId: 'response',
conversationId: 'conversation',
isCreatedByUser: false,
langfuseSampled: true,
langfuseDestinationIds: ['destination'],
};
trace = {
canViewSession: jest.fn(async () => true),
getMessage: jest.fn(async () => message),
resolveSession: jest.fn(async () => ({ url, destinationId: 'destination' })),
};
});
it('includes only a saved current assistant response in the authorized configured destination', async () => {
expect((await service([], trace).summarize(run(), snapshot())).session).toEqual({ url });
expect(trace.getMessage).toHaveBeenCalledWith({
tenantId: 'tenant',
user: 'user',
conversationId: 'conversation',
messageId: 'response',
});
});
it.each([
{ user: 'other' },
{ tenantId: 'other' },
{ messageId: 'previous-response' },
{ conversationId: 'other' },
{ isCreatedByUser: true },
{ isUserSubmitted: true },
{ langfuseSampled: false },
{ langfuseDestinationIds: [] },
{ langfuseDestinationIds: ['new-destination'] },
])('omits mismatched provenance %j', async (override) => {
Object.assign(message, override);
expect((await service([], trace).summarize(run(), snapshot())).session).toBeUndefined();
});
it('removes a frozen session link when the saved row becomes user-submitted while preserving metrics', async () => {
const frozen = await service([], trace).summarize(run(), snapshot());
const saved = run();
saved.snapshot = { ...snapshot(), summary: frozen };
message.isUserSubmitted = true;
const current = await service([], trace).summarize(saved, saved.snapshot);
expect(current.session).toBeUndefined();
expect(current.costUSD).toEqual(frozen.costUSD);
expect(current.tokens).toEqual(frozen.tokens);
});
it('fails closed on current authorization denial/outage without discarding metrics', async () => {
for (const canViewSession of [
async () => false,
async () => {
throw new Error('sensitive diagnostic');
},
]) {
const result = await service([], { ...trace, canViewSession }).summarize(run(), snapshot());
expect(result.session).toBeUndefined();
expect(result.costUSD.value).toBe('0.1');
}
expect(trace.getMessage).not.toHaveBeenCalled();
});
it.each([
'http://127.0.0.1:8788',
'https://127.0.0.1',
'https://[::1]',
'https://10.0.0.1',
'https://trace.internal',
'https://localhost',
'https://trace.local',
'https://trace.test',
'https://user:secret@cloud.langfuse.com',
'https://cloud.langfuse.com?token=secret',
'https://cloud.langfuse.com#secret',
'javascript:secret',
'not a URL',
])('never emits nonpublic or credential-bearing UI URL %s', async (unsafe) => {
trace.resolveSession = async () => ({ url: unsafe, destinationId: 'destination' });
expect((await service([], trace).summarize(run(), snapshot())).session).toBeUndefined();
});
it('uses the real configured session resolver and current capabilities without external HTTP', async () => {
const savedEnv = { ...process.env };
try {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://127.0.0.1:8788';
process.env.LANGFUSE_TRACING_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = 'false';
process.env.LANGFUSE_FANOUT_TENANT_DESTINATIONS = 'test=https://cloud.langfuse.com';
process.env.LANGFUSE_SAMPLE_RATE = '1';
message.langfuseDestinationIds = [
getLangfuseDestinationId('https://cloud.langfuse.com', 'project'),
];
const Message = mongoose.model<IMessage>(
'SummaryMessage',
new mongoose.Schema<IMessage>({ messageId: String }),
);
const getMessages = jest.fn(async () => [new Message({ messageId: 'response' })]);
const deps = {
findUser: async () => ({ id: 'user', tenantId: 'tenant', role: 'ADMIN' }),
getHeldCapabilities: async () =>
new Set([SystemCapabilities.ACCESS_ADMIN, configCapability('langfuse')]),
getConfig: async () => ({ enabled: true, destination: 'test', projectId: 'project' }),
getMessage: async () => message,
getMessages,
};
const typed = createChannelSummaryTraceResolver(deps);
expect((await service([], typed).summarize(run(), snapshot())).session).toEqual({ url });
expect(getMessages).toHaveBeenCalledWith(
{
user: 'user',
conversationId: 'conversation',
isCreatedByUser: false,
isUserSubmitted: { $ne: true },
langfuseSampled: true,
langfuseDestinationIds: message.langfuseDestinationIds[0],
},
'_id',
{ sort: false, limit: 1 },
);
for (const held of [
new Set([SystemCapabilities.ACCESS_ADMIN]),
new Set([configCapability('langfuse')]),
new Set<SystemCapability>(),
]) {
expect(
await createChannelSummaryTraceResolver({
...deps,
getHeldCapabilities: async () => held,
}).canViewSession(run()),
).toBe(false);
}
expect(
await createChannelSummaryTraceResolver({
...deps,
findUser: async () => ({ id: 'user', tenantId: 'other', role: 'ADMIN' }),
}).canViewSession(run()),
).toBe(false);
expect(
(
await service(
[],
createChannelSummaryTraceResolver({ ...deps, getConfig: async () => undefined }),
).summarize(run(), snapshot())
).session,
).toBeUndefined();
} finally {
process.env = savedEnv;
}
});
});
describe('fresh disclosure of frozen metrics', () => {
it('does not count absent or empty accounting as recorded token usage, including legacy zeros', async () => {
for (const accounting of [undefined, { ...priced(), calls: [] }]) {
expect(
(
await service().summarize(
run(),
snapshot({ usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 }, accounting }),
)
).tokens.coverage,
).toBe('unavailable');
}
const knownZero = priced();
knownZero.calls[0].inputTokens = 0;
knownZero.calls[0].outputTokens = 0;
expect(
(
await service().summarize(
run(),
snapshot({
usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
accounting: knownZero,
}),
)
).tokens,
).toMatchObject({ coverage: 'complete', value: { totalTokens: 0 } });
});
it('preserves immutable metrics while suppressing a previously authorized URL after policy changes', async () => {
const destinationId = 'destination';
const link = {
url: 'https://cloud.langfuse.com/project/project/sessions/conversation',
destinationId,
};
let allowed = true;
let destination = link;
const trace: ChannelSummaryTraceDependencies = {
canViewSession: async () => allowed,
getMessage: async () => ({
user: 'user',
tenantId: 'tenant',
conversationId: 'conversation',
messageId: 'response',
isCreatedByUser: false,
langfuseSampled: true,
langfuseDestinationIds: [destinationId],
}),
resolveSession: async () => destination,
};
const summaryService = service([], trace);
const frozen = await summaryService.summarize(run(), snapshot());
expect(frozen.session).toEqual({ url: link.url });
const retained = { ...run(), snapshot: { ...snapshot(), summary: frozen } };
allowed = false;
const denied = await summaryService.summarize(
retained,
snapshot({ accounting: priced('999') }),
);
expect(denied.session).toBeUndefined();
expect(denied.costUSD).toEqual(frozen.costUSD);
expect(frozen.session).toEqual({ url: link.url });
allowed = true;
destination = { ...link, destinationId: 'changed' };
expect((await summaryService.summarize(retained, snapshot())).session).toBeUndefined();
});
});

View file

@ -0,0 +1,271 @@
import { isIP } from 'node:net';
import {
configCapability,
SystemCapabilities,
isServerAuthoredMessage,
} from '@librechat/data-schemas';
import type {
ChannelRunSummary,
ChannelRunSnapshot,
ChannelSummaryMetric,
AccountingBasis,
TCustomConfig,
} from 'librechat-data-provider';
import type {
ChannelRunRecord,
ChannelSummaryRow,
ChannelSummaryStorage,
} from '@librechat/data-schemas';
import type { CapabilityUser, GetHeldCapabilitiesFn } from '~/middleware/capabilities';
import type { LangfuseSessionLinkParams } from '~/langfuse/session';
import type { LangfuseSession } from '~/langfuse/session';
import type { ChannelMessage } from './types';
import { resolveLangfuseSession } from '~/langfuse/session';
export interface ChannelSummaryTraceDependencies {
/** Current principal/tenant capabilities, using the existing trace UI authorization policy. */
canViewSession: (run: ChannelRunRecord) => Promise<boolean>;
getMessage: (scope: {
tenantId: string;
user: string;
conversationId: string;
messageId: string;
}) => Promise<ChannelMessage | null>;
/** Existing configured/trusted UI destination resolver. Never infer a UI from an export endpoint. */
resolveSession: (run: ChannelRunRecord) => Promise<LangfuseSession | null>;
}
export interface ChannelSummaryDependencies {
storage: ChannelSummaryStorage;
trace?: ChannelSummaryTraceDependencies;
}
export interface ChannelSummaryTraceResolverDependencies {
findUser: (userId: string) => Promise<{
id?: string;
_id?: { toString(): string };
role?: string | null;
tenantId?: string | null;
idOnTheSource?: string | null;
} | null>;
getHeldCapabilities: GetHeldCapabilitiesFn;
getConfig: (run: ChannelRunRecord) => Promise<TCustomConfig['langfuse']>;
getMessage: ChannelSummaryTraceDependencies['getMessage'];
getMessages: LangfuseSessionLinkParams['getMessages'];
}
/** Same current-tenant capability policy as shared-link trace UI, with the configured session resolver. */
export function createChannelSummaryTraceResolver(
deps: ChannelSummaryTraceResolverDependencies,
): ChannelSummaryTraceDependencies {
return {
async canViewSession(run) {
const source = await deps.findUser(run.principal.userId);
const id = source?.id ?? source?._id?.toString();
if (!source || id !== run.principal.userId || (source.tenantId || '_') !== run.tenantId)
return false;
const user: CapabilityUser = {
id,
role: source.role ?? '',
tenantId: source.tenantId || undefined,
idOnTheSource: source.idOnTheSource ?? null,
};
const langfuse = configCapability('langfuse');
const held = await deps.getHeldCapabilities(user, [
SystemCapabilities.ACCESS_ADMIN,
SystemCapabilities.MANAGE_CONFIGS,
langfuse,
]);
return (
held.has(SystemCapabilities.ACCESS_ADMIN) &&
(held.has(SystemCapabilities.MANAGE_CONFIGS) || held.has(langfuse))
);
},
getMessage: deps.getMessage,
async resolveSession(run) {
if (!run.execution?.conversationId) return null;
return resolveLangfuseSession({
config: await deps.getConfig(run),
conversationId: run.execution.conversationId,
userId: run.principal.userId,
getMessages: deps.getMessages,
});
},
};
}
function safeCount(value: number | undefined): value is number {
return value != null && Number.isSafeInteger(value) && value >= 0;
}
function metric<T>(coveredRuns: number, expectedRuns: number, value: T): ChannelSummaryMetric<T> {
if (!coveredRuns) return { coverage: 'unavailable', coveredRuns };
if (coveredRuns === expectedRuns) return { coverage: 'complete', coveredRuns, value };
return { coverage: 'partial', coveredRuns, knownValue: value };
}
function amountUnits(amount: string | undefined): bigint | null {
if (!amount || amount.length > 64 || !/^(?:0|[1-9]\d*)(?:\.\d{1,18})?$/.test(amount)) return null;
const [whole, fraction = ''] = amount.split('.');
return BigInt(whole + fraction.padEnd(18, '0'));
}
function amountString(units: bigint): string {
const digits = units.toString().padStart(19, '0');
const fraction = digits.slice(-18).replace(/0+$/, '');
return digits.slice(0, -18) + (fraction ? `.${fraction}` : '');
}
async function session(
deps: ChannelSummaryTraceDependencies | undefined,
run: ChannelRunRecord,
snapshot: ChannelRunSnapshot,
): Promise<ChannelRunSummary['session']> {
if (
!deps ||
!snapshot.responseId ||
!run.execution?.conversationId ||
run.execution.responseId !== snapshot.responseId
)
return undefined;
if (!(await deps.canViewSession(run))) return undefined;
const message = await deps.getMessage({
tenantId: run.tenantId,
user: run.principal.userId,
conversationId: run.execution.conversationId,
messageId: snapshot.responseId,
});
if (
!message ||
message.user !== run.principal.userId ||
(message.tenantId || '_') !== run.tenantId ||
message.conversationId !== run.execution.conversationId ||
message.messageId !== snapshot.responseId ||
!isServerAuthoredMessage(message) ||
(message.expiredAt != null &&
(!Number.isFinite(new Date(message.expiredAt).getTime()) ||
new Date(message.expiredAt).getTime() <= Date.now())) ||
message.langfuseSampled !== true ||
!message.langfuseDestinationIds?.length
)
return undefined;
const resolved = await deps.resolveSession(run);
if (!resolved || !message.langfuseDestinationIds.includes(resolved.destinationId))
return undefined;
const url = new URL(resolved.url);
const hostname = url.hostname
.replace(/^\[|\]$/g, '')
.replace(/\.$/, '')
.toLowerCase();
if (
url.protocol !== 'https:' ||
isIP(hostname) !== 0 ||
!hostname.includes('.') ||
/\.(?:localhost|local|localdomain|internal|lan|home|test|invalid|example)$/.test(hostname) ||
url.username ||
url.password ||
url.search ||
url.hash
)
return undefined;
return { url: url.toString() };
}
/** Footer metadata only. The caller checks live authority before and after, then freezes the snapshot. */
export function createChannelSummaryService(deps: ChannelSummaryDependencies): {
summarize(run: ChannelRunRecord, snapshot: ChannelRunSnapshot): Promise<ChannelRunSummary>;
} {
return {
async summarize(run, snapshot) {
const present = async (metrics: ChannelRunSummary): Promise<ChannelRunSummary> => {
const { session: _previous, ...current } = metrics;
try {
const link = await session(deps.trace, run, snapshot);
return link ? { ...current, session: link } : current;
} catch {
return current;
}
};
if (run.snapshot?.summary) return present(run.snapshot.summary);
if (!Number.isSafeInteger(run.sequence) || run.sequence < 1)
throw new Error('Invalid channel summary sequence');
let observedRuns = 0;
let elapsedRuns = 0;
let elapsedMs = 0;
let tokenRuns = 0;
const tokens = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
let costRuns = 0;
let costUnits = BigInt(0);
let basis: AccountingBasis | undefined;
let mixedBases = false;
const consume = (row: ChannelSummaryRow): void => {
observedRuns++;
const value = row.snapshot;
if (!value || !['completed', 'failed', 'cancelled'].includes(value.status)) return;
if (safeCount(value.elapsedMs)) {
elapsedMs += value.elapsedMs;
elapsedRuns++;
}
const usage = value.usage;
const accounting = value.accounting;
if (
usage &&
accounting &&
Array.isArray(accounting.calls) &&
accounting.calls.length > 0 &&
accounting.calls.every(
(call) => call.reason === 'priced' || call.reason === 'pricing_unavailable',
) &&
safeCount(usage.inputTokens) &&
safeCount(usage.outputTokens) &&
safeCount(usage.totalTokens) &&
usage.totalTokens === usage.inputTokens + usage.outputTokens &&
accounting?.reason !== 'usage_unavailable' &&
accounting?.reason !== 'conflicting_usage' &&
!accounting?.calls?.some(
(call) => call.reason === 'invalid_usage' || call.reason === 'usage_unavailable',
)
) {
tokens.inputTokens += usage.inputTokens;
tokens.outputTokens += usage.outputTokens;
tokens.totalTokens += usage.totalTokens;
tokenRuns++;
}
const units = amountUnits(accounting?.amount);
if (
accounting?.status === 'available' &&
accounting.coverage === 'complete' &&
accounting.reason === 'priced' &&
accounting.currency === 'USD' &&
units != null &&
(accounting.basis === 'provider_reported' || accounting.basis === 'application_billing')
) {
mixedBases ||= basis != null && basis !== accounting.basis;
basis ??= accounting.basis;
costUnits += units;
costRuns++;
}
};
for await (const row of deps.storage.priorMetrics(run)) consume(row);
consume({ sequence: run.sequence, snapshot });
const summary: ChannelRunSummary = {
version: 1,
scope: 'actor_lane',
throughSequence: run.sequence,
includesCurrent: true,
priorRuns: observedRuns - 1,
expectedRuns: run.sequence,
observedRuns,
costUSD: mixedBases
? { coverage: 'unavailable', coveredRuns: 0 }
: {
...metric(costRuns, run.sequence, amountString(costUnits)),
...(basis ? { basis } : {}),
},
elapsedMs: metric(safeCount(elapsedMs) ? elapsedRuns : 0, run.sequence, elapsedMs),
tokens: metric(safeCount(tokens.totalTokens) ? tokenRuns : 0, run.sequence, tokens),
};
return present(summary);
},
};
}

View file

@ -5,7 +5,9 @@ export interface ChannelMessage {
user: string;
tenantId?: string;
isCreatedByUser?: boolean;
isUserSubmitted?: boolean;
isTemporary?: boolean;
expiredAt?: Date | string | null;
langfuseRunId?: string | null;
langfuseSampled?: boolean | null;
langfuseDestinationIds?: string[] | null;

View file

@ -3,6 +3,7 @@ import sharp from 'sharp';
import path from 'node:path';
import mongoose from 'mongoose';
import { Readable } from 'node:stream';
import { createHash } from 'node:crypto';
import { createReadStream } from 'node:fs';
import { mockClient } from 'aws-sdk-client-mock';
import { mkdtemp, readFile, rm } from 'node:fs/promises';
@ -103,6 +104,7 @@ describe('Generated file snapshots', () => {
basePath: 'uploads',
}),
bytes: buffer.length,
sha256: createHash('sha256').update(buffer).digest('hex'),
};
},
getStrategyFunctions: () => ({ saveBuffer }),

View file

@ -1,5 +1,6 @@
import path from 'path';
import { v4 } from 'uuid';
import { createHash } from 'node:crypto';
import { megabyte, fileConfig, imageExtRegex, inferMimeType } from 'librechat-data-provider';
import type { CodeEnvRef, FileSources, getEndpointFileConfig } from 'librechat-data-provider';
import type { CodeFileCommitData } from '@librechat/data-schemas';
@ -70,7 +71,7 @@ export interface CodeOutputProcessorDeps {
Pick<
CodeOutputStoredFile,
'filepath' | 'bytes' | 'width' | 'height' | 'storageKey' | 'storageRegion'
>
> & { sha256: string }
>;
getStrategyFunctions: (source: FileSources) => {
saveBuffer?: (input: {
@ -269,6 +270,10 @@ export async function processCodeOutput(
codeDestination: true,
sourceDispatchedAt,
};
const outputMetadata = (sha256: string) => ({
...codeEnvMetadata,
codeOutput: { messageId, sha256 },
});
if (isImage) {
const usage = 1;
@ -310,7 +315,7 @@ export async function processCodeOutput(
updatedAt: formattedDate,
source: appConfig.fileStrategy,
context: outputPersistence.context,
metadata: codeEnvMetadata,
metadata: outputMetadata(_file.sha256),
...(await retentionExpiryPromise),
};
if (!(await outputPersistence.commit(file))) {
@ -427,7 +432,7 @@ export async function processCodeOutput(
tenantId: req.user.tenantId,
bytes: buffer.length,
updatedAt: formattedDate,
metadata: codeEnvMetadata,
metadata: outputMetadata(createHash('sha256').update(buffer).digest('hex')),
source: appConfig.fileStrategy,
context: outputPersistence.context,
usage: 1,

View file

@ -1,4 +1,5 @@
import sharp from 'sharp';
import { createHash } from 'node:crypto';
import { convertImageBuffer } from './format';
const jpeg = async (): Promise<Buffer> =>
@ -8,8 +9,9 @@ const jpeg = async (): Promise<Buffer> =>
describe('convertImageBuffer', () => {
it('converts JPEG bytes with a PNG filename into an actual PNG', async () => {
const input = await jpeg();
const image = await convertImageBuffer({
buffer: await jpeg(),
buffer: input,
type: 'image/jpeg',
fileName: 'photo.png',
outputType: 'png',
@ -17,6 +19,8 @@ describe('convertImageBuffer', () => {
expect(image.fileName).toBe('photo.png');
expect((await sharp(image.buffer).metadata()).format).toBe('png');
expect(image.sha256).toBe(createHash('sha256').update(image.buffer).digest('hex'));
expect(image.sha256).not.toBe(createHash('sha256').update(input).digest('hex'));
});
it('preserves the buffer when both its type and filename match', async () => {
@ -28,7 +32,11 @@ describe('convertImageBuffer', () => {
outputType: 'jpeg',
});
expect(image).toEqual({ buffer, fileName: 'photo.JPEG' });
expect(image).toEqual({
buffer,
fileName: 'photo.JPEG',
sha256: createHash('sha256').update(buffer).digest('hex'),
});
expect(image.buffer).toBe(buffer);
});

View file

@ -1,5 +1,6 @@
import path from 'path';
import sharp from 'sharp';
import { createHash } from 'node:crypto';
import type { FormatEnum } from 'sharp';
type ImageFormatInput = {
@ -15,17 +16,17 @@ export async function convertImageBuffer({
type,
fileName,
outputType,
}: ImageFormatInput): Promise<{ buffer: Buffer; fileName: string }> {
}: ImageFormatInput): Promise<{ buffer: Buffer; fileName: string; sha256: string }> {
const extension = path.extname(fileName);
const targetExtension = `.${outputType}`;
if (extension.toLowerCase() === targetExtension && type === `image/${outputType}`) {
return { buffer, fileName };
}
return {
buffer: await sharp(buffer)
.toFormat(outputType as keyof FormatEnum)
.toBuffer(),
fileName: `${path.basename(fileName, extension)}${targetExtension}`,
};
const output =
extension.toLowerCase() === targetExtension && type === `image/${outputType}`
? { buffer, fileName }
: {
buffer: await sharp(buffer)
.toFormat(outputType as keyof FormatEnum)
.toBuffer(),
fileName: `${path.basename(fileName, extension)}${targetExtension}`,
};
return { ...output, sha256: createHash('sha256').update(output.buffer).digest('hex') };
}

View file

@ -163,3 +163,7 @@ export * from './channels/authority';
export * from './channels/identity';
export * from './channels/identityHttp';
export * from './channels/artifacts';
export * from './channels/artifactStorage';
export * from './channels/summary';

View file

@ -0,0 +1,68 @@
import mongoose from 'mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { createModels, createMethods, tenantStorage } from '@librechat/data-schemas';
import { getLangfuseDestinationId } from './destinations';
import { resolveLangfuseSession } from './session';
it('requires an owned server-authored sampled message for the shared session resolver', async () => {
const savedEnv = { ...process.env };
const mongo = await MongoMemoryServer.create();
try {
process.env.LANGFUSE_FANOUT_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_COLLECTOR_URL = 'http://127.0.0.1:8788';
process.env.LANGFUSE_TRACING_ENABLED = 'true';
process.env.LANGFUSE_FANOUT_TENANT_EXPORT_DISABLED = 'false';
process.env.LANGFUSE_FANOUT_TENANT_DESTINATIONS = 'test=https://cloud.langfuse.com';
process.env.LANGFUSE_SAMPLE_RATE = '1';
await mongoose.connect(mongo.getUri());
createModels(mongoose);
const db = createMethods(mongoose);
await tenantStorage.run({ tenantId: 'tenant' }, async () => {
await mongoose.models.Message.create({
tenantId: 'tenant',
user: 'owner',
conversationId: 'conversation',
messageId: 'response',
isCreatedByUser: false,
isUserSubmitted: true,
langfuseSampled: true,
langfuseDestinationIds: [getLangfuseDestinationId('https://cloud.langfuse.com', 'project')],
text: 'Imported assistant-shaped text',
});
const resolve = () =>
resolveLangfuseSession({
config: { enabled: true, destination: 'test', projectId: 'project' },
conversationId: 'conversation',
userId: 'owner',
getMessages: db.getMessages,
});
expect(await resolve()).toBeNull();
await mongoose.models.Message.updateOne(
{ messageId: 'response' },
{ $set: { isUserSubmitted: false } },
);
expect(await resolve()).toMatchObject({
url: 'https://cloud.langfuse.com/project/project/sessions/conversation',
});
await mongoose.models.Message.updateOne(
{ messageId: 'response' },
{ $set: { isCreatedByUser: true } },
);
expect(await resolve()).toBeNull();
await mongoose.models.Message.updateOne(
{ messageId: 'response' },
{ $set: { isCreatedByUser: false }, $unset: { isUserSubmitted: '' } },
);
expect(await resolve()).not.toBeNull();
await mongoose.models.Message.updateOne(
{ messageId: 'response' },
{ $set: { user: 'other-owner' } },
);
expect(await resolve()).toBeNull();
});
} finally {
process.env = savedEnv;
await mongoose.disconnect();
await mongo.stop();
}
}, 60000);

View file

@ -1,3 +1,4 @@
import { SERVER_AUTHORED_MESSAGE_FILTER } from '@librechat/data-schemas';
import type { MessageMethods } from '@librechat/data-schemas';
import type { TCustomConfig } from 'librechat-data-provider';
import { resolveLangfuseTenantDestination } from './tenantDestinations';
@ -38,6 +39,7 @@ export async function resolveLangfuseSession({
{
user: userId,
conversationId,
...SERVER_AUTHORED_MESSAGE_FILTER,
langfuseSampled: true,
langfuseDestinationIds: destinationId,
},

View file

@ -38,3 +38,19 @@ it('validates injected runtime host policy without exposing an operator enable s
expect(channelConfigSchema.safeParse({ artifactMaxFiles: 21 }).success).toBe(false);
expect(agentsEndpointSchema.safeParse({ channels: { enabled: true } }).success).toBe(false);
});
it('configures the answer-file byte threshold with the existing default and bounded integer values', () => {
expect(channelConfigSchema.parse({}).artifactAnswerFileThresholdBytes).toBe(6000);
expect(
channelConfigSchema.parse({ artifactAnswerFileThresholdBytes: 0 })
.artifactAnswerFileThresholdBytes,
).toBe(0);
expect(
channelConfigSchema.parse({ artifactAnswerFileThresholdBytes: 8192 })
.artifactAnswerFileThresholdBytes,
).toBe(8192);
for (const value of [-1, 1.5, 50 * 1024 * 1024 + 1])
expect(channelConfigSchema.safeParse({ artifactAnswerFileThresholdBytes: value }).success).toBe(
false,
);
});

View file

@ -1230,6 +1230,8 @@ const managementApiAuthSchema = z
});
export const CHANNEL_DELIVERY_PARTS_HARD_MAX = 100;
export const CHANNEL_ARTIFACT_FILES_HARD_MAX = 20;
export const CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS = 60_000;
/** Storage work per claim transaction; shared by configuration and injected storage defaults. */
export const channelStorageConfigSchema = z.object({
@ -1278,8 +1280,21 @@ export const channelConfigSchema = channelStorageConfigSchema.extend({
.min(1)
.max(50 * 1024 * 1024)
.default(10 * 1024 * 1024),
artifactMaxFiles: z.number().int().min(1).max(20).default(5),
artifactReadTimeoutMs: z.number().int().min(1000).max(60_000).default(30_000),
artifactMaxFiles: z.number().int().min(1).max(CHANNEL_ARTIFACT_FILES_HARD_MAX).default(5),
/** Whole artifact operation budget, including catalog and authorization reads. */
artifactReadTimeoutMs: z
.number()
.int()
.min(1000)
.max(CHANNEL_ARTIFACT_READ_TIMEOUT_HARD_MAX_MS)
.default(30_000),
/** New plain-text answer files require more than this many UTF-8 bytes; fenced answers still qualify. */
artifactAnswerFileThresholdBytes: z
.number()
.int()
.min(0)
.max(50 * 1024 * 1024)
.default(6000),
cleanup: z
.object({
batchSize: z.number().int().min(1).max(100).default(25),

View file

@ -164,6 +164,11 @@ export type RunFileProvenance = {
/** Shared wire bound, not a deployment setting. */
export const MAX_FILE_TEXT_PREVIEW_LENGTH = 240;
/** Identifies the bytes of one generated attachment when its file ID is reused. */
export type CodeOutputProvenance = {
messageId: string;
sha256: string;
};
export type TFile = {
_id?: string;
@ -223,6 +228,7 @@ export type TFile = {
previewError?: string;
metadata?: {
runFile?: RunFileProvenance;
codeOutput?: CodeOutputProvenance;
fileIdentifier?: string;
/**
* Structured form of `fileIdentifier`. Persisted alongside the

View file

@ -0,0 +1,141 @@
import { Types } from 'mongoose';
import { FileContext, CHANNEL_ARTIFACT_FILES_HARD_MAX } from 'librechat-data-provider';
import type {
ResponseArtifactFile,
ResponseArtifactQuery,
RunArtifactRunScope,
} from '~/types/file';
import { getTenantId, isReservedTenantId, SYSTEM_TENANT_ID } from '~/config/tenantContext';
import { SERVER_AUTHORED_MESSAGE_FILTER } from '~/utils/authored';
/** Null denotes an absent/expired owned response; query failures remain operational errors. */
export async function readResponseArtifactCatalog(
mongoose: typeof import('mongoose'),
scope: RunArtifactRunScope,
query: ResponseArtifactQuery,
): Promise<ResponseArtifactFile[] | null> {
if (
[scope.userId, scope.conversationId, scope.runId].some(
(value) => typeof value !== 'string' || !value.trim(),
)
)
throw new TypeError('A complete response artifact scope is required');
if (!['list', 'file', 'authorize'].includes(query.kind))
throw new TypeError('Invalid response artifact query');
const tenantId = scope.tenantId ?? undefined;
const current = getTenantId();
if (
(tenantId != null &&
(!tenantId.trim() || isReservedTenantId(tenantId) || tenantId === SYSTEM_TENANT_ID)) ||
(current && current !== SYSTEM_TENANT_ID && current !== tenantId)
)
throw new TypeError('Response artifact tenant does not match authenticated scope');
if (
query.kind === 'list' &&
(!Number.isSafeInteger(query.limit) ||
query.limit < 1 ||
query.limit > CHANNEL_ARTIFACT_FILES_HARD_MAX + 1)
)
throw new TypeError('Invalid response artifact page size');
if (query.kind === 'file' && (typeof query.fileId !== 'string' || !query.fileId))
throw new TypeError('A response artifact file ID is required');
const partition = tenantId ?? { $in: [null, ''] };
const expiry = { $or: [{ expiredAt: null }, { expiredAt: { $gt: new Date() } }] };
const message = {
user: scope.userId,
tenantId: partition,
conversationId: scope.conversationId,
messageId: scope.runId,
...SERVER_AUTHORED_MESSAGE_FILTER,
...expiry,
};
const Message = mongoose.model('Message');
if (query.kind === 'authorize') return (await Message.exists(message)) ? [] : null;
const users: Array<string | Types.ObjectId> = [scope.userId];
if (Types.ObjectId.isValid(scope.userId)) users.push(new Types.ObjectId(scope.userId));
const rows = await Message.aggregate<{ files: ResponseArtifactFile[] }>([
{ $match: message },
{ $limit: 1 },
{ $project: { attachments: { $cond: [{ $isArray: '$attachments' }, '$attachments', []] } } },
{
$lookup: {
// Collection metadata only; the lookup below explicitly scopes both owner and tenant.
// eslint-disable-next-line no-restricted-syntax
from: mongoose.model('File').collection.name,
let: {
attachmentVersions: {
$map: {
input: '$attachments',
as: 'attachment',
in: [
'$$attachment.file_id',
'$$attachment.metadata.codeOutput.messageId',
'$$attachment.metadata.codeOutput.sha256',
],
},
},
},
pipeline: [
{
$match: {
user: { $in: users },
tenantId: partition,
conversationId: scope.conversationId,
...(query.kind === 'file' ? { file_id: query.fileId } : {}),
$and: [
expiry,
{ $or: [{ expiresAt: null }, { expiresAt: { $gt: new Date() } }] },
{
$or: [
{ context: FileContext.run_artifact, 'metadata.runFile.runId': scope.runId },
{
context: {
$in: [FileContext.execute_code, FileContext.execute_code_snapshot],
},
'metadata.codeOutput.messageId': scope.runId,
'metadata.codeOutput.sha256': /^[a-f0-9]{64}$/,
$expr: {
$in: [
[
'$file_id',
'$metadata.codeOutput.messageId',
'$metadata.codeOutput.sha256',
],
'$$attachmentVersions',
],
},
},
],
},
],
},
},
{ $sort: { createdAt: 1, file_id: 1 } },
{ $limit: query.kind === 'file' ? 1 : query.limit },
{
$project: {
_id: 0,
file_id: 1,
user: { $toString: '$user' },
tenantId: 1,
conversationId: 1,
filename: 1,
filepath: 1,
storageKey: 1,
storageRegion: 1,
bytes: 1,
type: 1,
source: 1,
expiredAt: 1,
expiresAt: 1,
sha256: '$metadata.codeOutput.sha256',
},
},
],
as: 'files',
},
},
{ $project: { _id: 0, files: 1 } },
]);
return rows[0]?.files ?? null;
}

View file

@ -11,6 +11,8 @@ import type { FilterQuery, SortOrder, Model } from 'mongoose';
import type {
IMongoFile,
RunArtifactFile,
ResponseArtifactFile,
ResponseArtifactQuery,
RunArtifactClaim,
RunArtifactScope,
CodeFileCommitData,
@ -23,6 +25,7 @@ import type {
} from '~/types/file';
import type { IChatProjectDocument } from '~/types';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import { readResponseArtifactCatalog } from './artifacts';
import { fileContentUpdate } from './fileContent';
import { escapeRegExp } from '~/utils/string';
import logger from '../config/winston';
@ -408,6 +411,10 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
publishRunArtifactFile: (input: PublishRunArtifactInput) => Promise<RunArtifactFile>;
findRunArtifactFile: (scope: RunArtifactScope) => Promise<RunArtifactFile | null>;
listRunArtifacts: (scope: RunArtifactRunScope) => Promise<RunArtifactFile[]>;
readResponseArtifacts: (
scope: RunArtifactRunScope,
query: ResponseArtifactQuery,
) => Promise<ResponseArtifactFile[] | null>;
findFileById: (file_id: string, options?: Record<string, unknown>) => Promise<IMongoFile | null>;
getFiles: (
filter: FilterQuery<IMongoFile>,
@ -2009,6 +2016,7 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
publishRunArtifactFile,
findRunArtifactFile,
listRunArtifacts,
readResponseArtifacts: (scope, query) => readResponseArtifactCatalog(mongoose, scope, query),
findFileById,
getFiles,
getProjectFiles,

View file

@ -14,6 +14,7 @@ import { createChatExpirationDate, createTempChatExpirationDate } from '~/utils/
import { activeExpirationFilter, createFallbackRetentionDate } from '~/utils/retention';
import { fitBoundAppSnapshots, hasBoundAppSnapshots } from './appSnapshots';
import { prepareSubagentContentDeletion } from './subagentContent';
import { SERVER_AUTHORED_MESSAGE_FILTER } from '~/utils/authored';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import { tenantStorage } from '~/config/tenantContext';
import logger from '~/config/winston';
@ -528,8 +529,7 @@ const traceTenantScope = (tenantId?: string) =>
const SERVER_AUTHORED_SAMPLED_RESPONSE = {
langfuseSampled: true,
isCreatedByUser: false,
isUserSubmitted: { $ne: true },
...SERVER_AUTHORED_MESSAGE_FILTER,
} as const;
export const CLIENT_MESSAGE_SELECT: string = [

View file

@ -1,6 +1,6 @@
import mongoose, { Schema } from 'mongoose';
import { FileContext, FileSources } from 'librechat-data-provider';
import type { RunFileProvenance } from 'librechat-data-provider';
import type { RunFileProvenance, CodeOutputProvenance } from 'librechat-data-provider';
import type { IMongoFile } from '~/types';
import { codeEnvRefMapSchema, codeEnvRefSchema } from './codeEnvRef';
@ -19,6 +19,14 @@ const runFileProvenanceSchema = new Schema<RunFileProvenance>(
{ _id: false },
);
const codeOutputProvenanceSchema = new Schema<CodeOutputProvenance>(
{
messageId: { type: String, required: true },
sha256: { type: String, required: true, match: /^[a-f0-9]{64}$/ },
},
{ _id: false },
);
const file: Schema<IMongoFile> = new Schema(
{
user: {
@ -149,6 +157,7 @@ const file: Schema<IMongoFile> = new Schema(
width: Number,
height: Number,
metadata: {
codeOutput: { type: codeOutputProvenanceSchema, default: undefined },
runFile: {
type: runFileProvenanceSchema,
default: undefined,

View file

@ -88,6 +88,24 @@ export type RunArtifactFile = TFile & {
metadata: NonNullable<TFile['metadata']> & { runFile: RunFileProvenance };
};
/** Reader metadata only; mutable generated files carry their attachment's expected digest. */
export type ResponseArtifactFile = Pick<
TFile,
'file_id' | 'filename' | 'filepath' | 'storageKey' | 'storageRegion' | 'bytes' | 'type' | 'source'
> & {
user: string;
tenantId?: string | null;
conversationId: string;
expiredAt?: Date | null;
expiresAt?: TFile['expiresAt'] | null;
sha256?: string;
};
export type ResponseArtifactQuery =
| { kind: 'list'; limit: number }
| { kind: 'file'; fileId: string }
| { kind: 'authorize' };
export type RunArtifactContent = Pick<
TFile,
| 'filename'

View file

@ -0,0 +1,12 @@
/** Authorship only: callers must also enforce owner, tenant, response and retention scope. */
export const SERVER_AUTHORED_MESSAGE_FILTER = {
isCreatedByUser: false,
isUserSubmitted: { $ne: true },
} as const;
export function isServerAuthoredMessage(message: {
isCreatedByUser?: boolean;
isUserSubmitted?: boolean;
}): boolean {
return message.isCreatedByUser === false && message.isUserSubmitted !== true;
}

View file

@ -13,3 +13,5 @@ export * from './eviction';
export { buildIndexWithRetry, createIndexesWithRetry, isIndexBuildInProgress } from './retry';
export { isFieldNameRejection } from './fields';
export type { IndexBuildOptions } from './retry';
export { SERVER_AUTHORED_MESSAGE_FILTER, isServerAuthoredMessage } from './authored';