From aae13f6817456e8b2f27914b719fbab6cc4ff8a9 Mon Sep 17 00:00:00 2001 From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com> Date: Tue, 10 Nov 2026 21:04:02 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=8E=20feat:=20Resolve=20Channel=20Atta?= =?UTF-8?q?chments=20and=20Usage=20Summaries=20(#17608)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📎 feat: Resolve Channel Attachments and Usage Summaries * fix: Bound Response Artifact Catalogs and Reauthorize Trace Disclosure * fix: unify channel artifact budgets and generated provenance --- api/server/routes/assistants/avatar.spec.js | 13 +- .../services/Files/Code/process.spec.js | 28 + api/server/services/Files/images/convert.js | 10 +- e2e/specs/mock/quotes.spec.ts | 2 + .../api/src/admin/langfuse.handler.spec.ts | 2 + .../api/src/channels/artifactStorage.spec.ts | 214 +++++ packages/api/src/channels/artifactStorage.ts | 80 ++ packages/api/src/channels/artifacts.spec.ts | 809 ++++++++++++++++++ packages/api/src/channels/artifacts.ts | 311 +++++++ packages/api/src/channels/summary.spec.ts | 479 +++++++++++ packages/api/src/channels/summary.ts | 271 ++++++ packages/api/src/channels/types.ts | 2 + packages/api/src/files/code/process.spec.ts | 2 + packages/api/src/files/code/process.ts | 11 +- packages/api/src/files/format.spec.ts | 12 +- packages/api/src/files/format.ts | 23 +- packages/api/src/index.ts | 4 + packages/api/src/langfuse/session.spec.ts | 68 ++ packages/api/src/langfuse/session.ts | 2 + .../specs/responseStorage.spec.ts | 16 + packages/data-provider/src/config.ts | 19 +- packages/data-provider/src/types/files.ts | 6 + .../data-schemas/src/methods/artifacts.ts | 141 +++ packages/data-schemas/src/methods/file.ts | 8 + packages/data-schemas/src/methods/message.ts | 4 +- packages/data-schemas/src/schema/file.ts | 11 +- packages/data-schemas/src/types/file.ts | 18 + packages/data-schemas/src/utils/authored.ts | 12 + packages/data-schemas/src/utils/index.ts | 2 + 29 files changed, 2554 insertions(+), 26 deletions(-) create mode 100644 packages/api/src/channels/artifactStorage.spec.ts create mode 100644 packages/api/src/channels/artifactStorage.ts create mode 100644 packages/api/src/channels/artifacts.spec.ts create mode 100644 packages/api/src/channels/artifacts.ts create mode 100644 packages/api/src/channels/summary.spec.ts create mode 100644 packages/api/src/channels/summary.ts create mode 100644 packages/api/src/langfuse/session.spec.ts create mode 100644 packages/data-schemas/src/methods/artifacts.ts create mode 100644 packages/data-schemas/src/utils/authored.ts diff --git a/api/server/routes/assistants/avatar.spec.js b/api/server/routes/assistants/avatar.spec.js index 4518a265a8..634e56b425 100644 --- a/api/server/routes/assistants/avatar.spec.js +++ b/api/server/routes/assistants/avatar.spec.js @@ -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(); diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.js index 04c11a5094..3e1e5e2094 100644 --- a/api/server/services/Files/Code/process.spec.js +++ b/api/server/services/Files/Code/process.spec.js @@ -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', diff --git a/api/server/services/Files/images/convert.js b/api/server/services/Files/images/convert.js index 2752d7e451..62a1f5a45c 100644 --- a/api/server/services/Files/images/convert.js +++ b/api/server/services/Files/images/convert.js @@ -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; diff --git a/e2e/specs/mock/quotes.spec.ts b/e2e/specs/mock/quotes.spec.ts index 7e336a3cc7..2a9e5eee1b 100644 --- a/e2e/specs/mock/quotes.spec.ts +++ b/e2e/specs/mock/quotes.spec.ts @@ -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 diff --git a/packages/api/src/admin/langfuse.handler.spec.ts b/packages/api/src/admin/langfuse.handler.spec.ts index edd14c44e1..bb55d60d84 100644 --- a/packages/api/src/admin/langfuse.handler.spec.ts +++ b/packages/api/src/admin/langfuse.handler.spec.ts @@ -460,6 +460,8 @@ describe('createAdminLangfuseHandlers', () => { { user: 'u1', conversationId: 'conversation-1', + isCreatedByUser: false, + isUserSubmitted: { $ne: true }, langfuseSampled: true, langfuseDestinationIds: getLangfuseDestinationId( 'https://cloud.langfuse.com', diff --git a/packages/api/src/channels/artifactStorage.spec.ts b/packages/api/src/channels/artifactStorage.spec.ts new file mode 100644 index 0000000000..46a217a2e3 --- /dev/null +++ b/packages/api/src/channels/artifactStorage.spec.ts @@ -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(); +}); diff --git a/packages/api/src/channels/artifactStorage.ts b/packages/api/src/channels/artifactStorage.ts new file mode 100644 index 0000000000..ea3a094612 --- /dev/null +++ b/packages/api/src/channels/artifactStorage.ts @@ -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; + getStrategyFunctions: (source: FileSources) => + | { + getDownloadStream?: ( + request: ChannelArtifactStorageRequest, + path: string, + options: { signal: AbortSignal }, + ) => Promise; + } + | undefined; +} + +export interface ChannelArtifactReader { + readFile: ( + file: ResponseArtifactFile, + run: ChannelRunRecord, + signal: AbortSignal, + ) => Promise; +} + +const supportedSources = new Set([ + 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 }, + ); + }, + }; +} diff --git a/packages/api/src/channels/artifacts.spec.ts b/packages/api/src/channels/artifacts.spec.ts new file mode 100644 index 0000000000..85389b7a3a --- /dev/null +++ b/packages/api/src/channels/artifacts.spec.ts @@ -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; +let run: ChannelRunRecord; +let deps: ChannelArtifactDependencies; +let service: ReturnType; +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(); +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 = {}, +) { + 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((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((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((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((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); +}); diff --git a/packages/api/src/channels/artifacts.ts b/packages/api/src/channels/artifacts.ts new file mode 100644 index 0000000000..b7a2176205 --- /dev/null +++ b/packages/api/src/channels/artifacts.ts @@ -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; + readFile: ( + file: ResponseArtifactFile, + run: ChannelRunRecord, + signal: AbortSignal, + ) => Promise; + limits: () => Promise; +} +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; + + 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(work: () => Promise): Promise { + this.assertActive(); + let rejectAbort!: (error: ChannelArtifactError) => void; + const expired = new Promise((_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 { + 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(); + } + }, + }; +} diff --git a/packages/api/src/channels/summary.spec.ts b/packages/api/src/channels/summary.spec.ts new file mode 100644 index 0000000000..2e58dbb785 --- /dev/null +++ b/packages/api/src/channels/summary.spec.ts @@ -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 { + 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 { + 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( + 'SummaryMessage', + new mongoose.Schema({ 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(), + ]) { + 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(); + }); +}); diff --git a/packages/api/src/channels/summary.ts b/packages/api/src/channels/summary.ts new file mode 100644 index 0000000000..efbbf691a7 --- /dev/null +++ b/packages/api/src/channels/summary.ts @@ -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; + getMessage: (scope: { + tenantId: string; + user: string; + conversationId: string; + messageId: string; + }) => Promise; + /** Existing configured/trusted UI destination resolver. Never infer a UI from an export endpoint. */ + resolveSession: (run: ChannelRunRecord) => Promise; +} + +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; + 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(coveredRuns: number, expectedRuns: number, value: T): ChannelSummaryMetric { + 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 { + 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; +} { + return { + async summarize(run, snapshot) { + const present = async (metrics: ChannelRunSummary): Promise => { + 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); + }, + }; +} diff --git a/packages/api/src/channels/types.ts b/packages/api/src/channels/types.ts index f209ca0d75..c0ed100326 100644 --- a/packages/api/src/channels/types.ts +++ b/packages/api/src/channels/types.ts @@ -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; diff --git a/packages/api/src/files/code/process.spec.ts b/packages/api/src/files/code/process.spec.ts index 78fd940062..ab877a14ef 100644 --- a/packages/api/src/files/code/process.spec.ts +++ b/packages/api/src/files/code/process.spec.ts @@ -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 }), diff --git a/packages/api/src/files/code/process.ts b/packages/api/src/files/code/process.ts index d6fee74123..38f1de4bd7 100644 --- a/packages/api/src/files/code/process.ts +++ b/packages/api/src/files/code/process.ts @@ -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, diff --git a/packages/api/src/files/format.spec.ts b/packages/api/src/files/format.spec.ts index 155aff537a..fd85342269 100644 --- a/packages/api/src/files/format.spec.ts +++ b/packages/api/src/files/format.spec.ts @@ -1,4 +1,5 @@ import sharp from 'sharp'; +import { createHash } from 'node:crypto'; import { convertImageBuffer } from './format'; const jpeg = async (): Promise => @@ -8,8 +9,9 @@ const jpeg = async (): Promise => 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); }); diff --git a/packages/api/src/files/format.ts b/packages/api/src/files/format.ts index baae9d0191..613a2e4cfb 100644 --- a/packages/api/src/files/format.ts +++ b/packages/api/src/files/format.ts @@ -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') }; } diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts index f49399be0b..fbbdd6541d 100644 --- a/packages/api/src/index.ts +++ b/packages/api/src/index.ts @@ -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'; diff --git a/packages/api/src/langfuse/session.spec.ts b/packages/api/src/langfuse/session.spec.ts new file mode 100644 index 0000000000..0904177860 --- /dev/null +++ b/packages/api/src/langfuse/session.spec.ts @@ -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); diff --git a/packages/api/src/langfuse/session.ts b/packages/api/src/langfuse/session.ts index 8d2150045b..95d1788f46 100644 --- a/packages/api/src/langfuse/session.ts +++ b/packages/api/src/langfuse/session.ts @@ -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, }, diff --git a/packages/data-provider/specs/responseStorage.spec.ts b/packages/data-provider/specs/responseStorage.spec.ts index 88a4cdac6c..8d19c7bf55 100644 --- a/packages/data-provider/specs/responseStorage.spec.ts +++ b/packages/data-provider/specs/responseStorage.spec.ts @@ -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, + ); +}); diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 6356d4bf7e..56904863f2 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -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), diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.ts index d068b79567..3c1ef61067 100644 --- a/packages/data-provider/src/types/files.ts +++ b/packages/data-provider/src/types/files.ts @@ -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 diff --git a/packages/data-schemas/src/methods/artifacts.ts b/packages/data-schemas/src/methods/artifacts.ts new file mode 100644 index 0000000000..f7636563da --- /dev/null +++ b/packages/data-schemas/src/methods/artifacts.ts @@ -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 { + 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 = [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; +} diff --git a/packages/data-schemas/src/methods/file.ts b/packages/data-schemas/src/methods/file.ts index a61b9e6d5e..8bd5958c24 100644 --- a/packages/data-schemas/src/methods/file.ts +++ b/packages/data-schemas/src/methods/file.ts @@ -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; findRunArtifactFile: (scope: RunArtifactScope) => Promise; listRunArtifacts: (scope: RunArtifactRunScope) => Promise; + readResponseArtifacts: ( + scope: RunArtifactRunScope, + query: ResponseArtifactQuery, + ) => Promise; findFileById: (file_id: string, options?: Record) => Promise; getFiles: ( filter: FilterQuery, @@ -2009,6 +2016,7 @@ export function createFileMethods(mongoose: typeof import('mongoose')): { publishRunArtifactFile, findRunArtifactFile, listRunArtifacts, + readResponseArtifacts: (scope, query) => readResponseArtifactCatalog(mongoose, scope, query), findFileById, getFiles, getProjectFiles, diff --git a/packages/data-schemas/src/methods/message.ts b/packages/data-schemas/src/methods/message.ts index c2e07f57b4..e24eebc853 100644 --- a/packages/data-schemas/src/methods/message.ts +++ b/packages/data-schemas/src/methods/message.ts @@ -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 = [ diff --git a/packages/data-schemas/src/schema/file.ts b/packages/data-schemas/src/schema/file.ts index 48c6a9cb46..049da22d87 100644 --- a/packages/data-schemas/src/schema/file.ts +++ b/packages/data-schemas/src/schema/file.ts @@ -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( { _id: false }, ); +const codeOutputProvenanceSchema = new Schema( + { + messageId: { type: String, required: true }, + sha256: { type: String, required: true, match: /^[a-f0-9]{64}$/ }, + }, + { _id: false }, +); + const file: Schema = new Schema( { user: { @@ -149,6 +157,7 @@ const file: Schema = new Schema( width: Number, height: Number, metadata: { + codeOutput: { type: codeOutputProvenanceSchema, default: undefined }, runFile: { type: runFileProvenanceSchema, default: undefined, diff --git a/packages/data-schemas/src/types/file.ts b/packages/data-schemas/src/types/file.ts index 1fb6b58c87..5aef52d8a2 100644 --- a/packages/data-schemas/src/types/file.ts +++ b/packages/data-schemas/src/types/file.ts @@ -88,6 +88,24 @@ export type RunArtifactFile = TFile & { metadata: NonNullable & { 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' diff --git a/packages/data-schemas/src/utils/authored.ts b/packages/data-schemas/src/utils/authored.ts new file mode 100644 index 0000000000..6549f1b946 --- /dev/null +++ b/packages/data-schemas/src/utils/authored.ts @@ -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; +} diff --git a/packages/data-schemas/src/utils/index.ts b/packages/data-schemas/src/utils/index.ts index 921d73a95f..6c56f05e18 100644 --- a/packages/data-schemas/src/utils/index.ts +++ b/packages/data-schemas/src/utils/index.ts @@ -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';