From e50a30653cd439b404432ecfc3efc41ddcedc236 Mon Sep 17 00:00:00 2001 From: Danny Avila Date: Wed, 18 Nov 2026 11:49:24 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=A5=A4=20feat:=20Let=20Remote=20SDK=20Age?= =?UTF-8?q?nts=20Read=20Native=20Chat=20Attachments=20(#18419)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: bind native chat attachments to remote SDK file reads * fix: preserve SDK file settlement and stable storage identity --- .../agents/__tests__/client.billing.spec.js | 78 +++- api/server/controllers/agents/client.js | 6 +- api/server/index.js | 2 + .../services/Endpoints/agents/initialize.js | 10 + api/server/services/Files/strategies.js | 3 + e2e/config/librechat.e2e.yaml | 2 + e2e/setup/remote-sdk-files.cjs | 64 +++ e2e/specs/mock/remote-sdk.spec.ts | 89 +++- .../api/src/agents/files/snapshots.spec.ts | 25 ++ packages/api/src/agents/files/snapshots.ts | 76 +++- packages/api/src/agents/index.ts | 3 + .../src/agents/remoteSdk/attachments.spec.ts | 399 ++++++++++++++++++ .../api/src/agents/remoteSdk/attachments.ts | 365 ++++++++++++++++ packages/api/src/agents/remoteSdk/types.ts | 2 + packages/api/src/agents/run.ts | 4 + packages/api/src/agents/sdk.spec.ts | 17 + packages/api/src/agents/sdk.ts | 19 +- packages/api/src/types/files.ts | 2 + packages/data-provider/src/config.spec.ts | 20 + packages/data-provider/src/config.ts | 14 + .../src/methods/file.publication.spec.ts | 26 ++ packages/data-schemas/src/methods/file.ts | 18 +- 22 files changed, 1218 insertions(+), 26 deletions(-) create mode 100644 e2e/setup/remote-sdk-files.cjs create mode 100644 packages/api/src/agents/remoteSdk/attachments.spec.ts create mode 100644 packages/api/src/agents/remoteSdk/attachments.ts diff --git a/api/server/controllers/agents/__tests__/client.billing.spec.js b/api/server/controllers/agents/__tests__/client.billing.spec.js index 0c6ff6b1f7..8fd162cce5 100644 --- a/api/server/controllers/agents/__tests__/client.billing.spec.js +++ b/api/server/controllers/agents/__tests__/client.billing.spec.js @@ -1,8 +1,15 @@ const { tool } = require('@librechat/agents/langchain/tools'); const { z } = require('zod'); const { GraphEvents } = require('@librechat/agents'); -const { Constants, ContentTypes, EModelEndpoint } = require('librechat-data-provider'); -const { GenerationJobManager } = require('@librechat/api'); +const { + Constants, + ContentTypes, + EModelEndpoint, + agentsEndpointSchema, +} = require('librechat-data-provider'); +const { GenerationJobManager, createSdkFileHost } = require('@librechat/api'); +const { promises: fs } = require('node:fs'); +const { Readable } = require('node:stream'); const AgentClient = require('../client'); const { ModelEndHandler } = require('../callbacks'); const db = require('~/models'); @@ -166,6 +173,73 @@ describe('AgentClient billing through BaseClient and the real runtime', () => { await GenerationJobManager.destroy(); }); + it('settles consumed usage when native SDK snapshot cleanup fails', async () => { + const { client, send, requests } = fixture({ reported: true }); + const file = { + file_id: 'billing-input', + user: 'user-billing', + filepath: '/uploads/input', + filename: 'input.txt', + bytes: 1, + type: 'text/plain', + source: 'local', + object: 'file', + usage: 0, + embedded: false, + }; + const host = createSdkFileHost( + agentsEndpointSchema.parse({ sdkHostFiles: { maxFileBytes: 1, maxChunkBytes: 1 } }) + .sdkHostFiles, + ); + const audit = jest.fn(); + const session = host.createSession({ + req: client.options.req, + audit, + getInputs: () => [file], + loadFiles: async () => [file], + filterFiles: async ({ files }) => files, + getStrategyFunctions: () => ({ + getDownloadStream: async () => Readable.from([Buffer.from('x')]), + }), + }); + const identity = { + runtimeId: 'fixture', + agentId: 'agent-billing', + userId: 'user-billing', + runId: 'file-run', + }; + const bound = session.bind(identity); + const mkdir = jest.spyOn(fs, 'mkdtemp'); + await bound.service.read({ + version: 1, + identity, + reference: bound.sources[0].reference, + revision: bound.sources[0].revision, + offset: 0, + length: 1, + }); + const directory = await mkdir.mock.results[0].value; + client.options.sdkFiles = session; + const remove = jest.spyOn(fs, 'rm').mockRejectedValue(new Error('private filesystem failure')); + try { + await send(); + expect(requests).toHaveLength(1); + expect(audit).toHaveBeenCalledWith({ action: 'cleanup_failed' }); + expect(db.bulkInsertTransactions).toHaveBeenCalledWith( + expect.arrayContaining([ + expect.objectContaining({ tokenType: 'prompt', rawAmount: -300000 }), + expect.objectContaining({ tokenType: 'completion', rawAmount: -5 }), + ]), + ); + expect(client._resolveRun).toBeNull(); + expect(host.snapshot().snapshots).toEqual({ operations: 1, reservedBytes: 1 }); + } finally { + remove.mockRestore(); + mkdir.mockRestore(); + await fs.rm(directory, { recursive: true, force: true }); + } + }); + it('does not bill when real pruning rejects every message before model invocation', async () => { const { send, requests, client } = fixture(); diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.js index ee3b217dc4..5bcee0ea42 100644 --- a/api/server/controllers/agents/client.js +++ b/api/server/controllers/agents/client.js @@ -5056,6 +5056,7 @@ class AgentClient extends BaseClient { (activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers); const createRunPromise = createRun({ sdkModelHost: this.options.req?.app?.locals?.sdkModelHost, + sdkFiles: this.options.sdkFiles, scheduledMCPExecution: getScheduleMCPExecution(getMCPRequestContext(this.options.req)), recordScheduledMCPDenial: createScheduledMCPPolicyRecorder( getScheduleMCPExecution(getMCPRequestContext(this.options.req)), @@ -5358,7 +5359,7 @@ class AgentClient extends BaseClient { rejectPrivateTextAdmission(this.options.req); /** An aborted/erroring run can still have completed compaction before * the failure; retain that model-visible state for actor reconciliation. */ - await this.options.runFiles?.close(); + await Promise.all([this.options.runFiles?.close(), this.options.sdkFiles?.close()]); this.eventActorSummary = getLatestEventActorSummary(this.contentParts) ?? this.eventActorSummary; /** A run that never came to exist has no state of its own: keep the @@ -5874,6 +5875,7 @@ class AgentClient extends BaseClient { (activityLabel ? createAssistantPhaseStampingHandlers(offsetHandlers) : offsetHandlers); run = await createRun({ sdkModelHost: this.options.req?.app?.locals?.sdkModelHost, + sdkFiles: this.options.sdkFiles, sdkResumeState: { content: seedContent, steps: runSteps }, scheduledMCPExecution: getScheduleMCPExecution(getMCPRequestContext(this.options.req)), recordScheduledMCPDenial: createScheduledMCPPolicyRecorder( @@ -6074,7 +6076,7 @@ class AgentClient extends BaseClient { }); } } finally { - await this.options.runFiles?.close(); + await Promise.all([this.options.runFiles?.close(), this.options.sdkFiles?.close()]); this.eventActorSummary = getLatestEventActorSummary(this.contentParts) ?? this.eventActorSummary; /** A run that never came to exist has no state of its own: keep the diff --git a/api/server/index.js b/api/server/index.js index cc026a0c6a..d22405cb43 100644 --- a/api/server/index.js +++ b/api/server/index.js @@ -70,6 +70,7 @@ const { warnOnUnreachableDeliveryPaths, createCodeApiUploadRegistry, createSdkModelHost, + createSdkFileHost, createRequestSanitizer, reportEndpointOverrides, } = require('@librechat/api'); @@ -263,6 +264,7 @@ const startServer = async () => { await initializeFavorites(await loadCustomConfig(false, { storageSelection: true })); registerShutdownTask('favorites persistence', closeFavorites, { priority: -100 }); const appConfig = await getAppConfig({ baseOnly: true }); + app.locals.sdkFileHost = createSdkFileHost(appConfig?.endpoints?.agents?.sdkHostFiles); app.locals.sdkModelHost = createSdkModelHost(appConfig?.endpoints?.agents?.sdkHostModels); await configureSubagentTaskRouting(appConfig?.endpoints?.agents?.subagentActivity); registerBackgroundTaskShutdown({ diff --git a/api/server/services/Endpoints/agents/initialize.js b/api/server/services/Endpoints/agents/initialize.js index 87dd0d1c27..45360b8832 100644 --- a/api/server/services/Endpoints/agents/initialize.js +++ b/api/server/services/Endpoints/agents/initialize.js @@ -40,6 +40,7 @@ const { createLazyAgentHistoryResolver, resolveToolRoleGrants, createChatRunFileBindings, + createChatSdkFileSession, createAxiosInstance, getCodeApiAuthHeaders, getCodeExecutionBaseUrl, @@ -2110,6 +2111,15 @@ const initializeClientWithProvider = async ({ subagentAggregatorsByToolCallId, subagentTasks, runFiles: runFileBindings.session, + sdkFiles: createChatSdkFileSession({ + audit: (event) => logger.warn('[agents:sdk-files]', event), + host: req.app?.locals?.sdkFileHost, + req, + getInputs: () => primaryConfig.currentRequestAttachments, + loadFiles: (ids) => db.getRunFileCandidates(ids, req.user.tenantId, { storageOnly: true }), + filterFiles: filterFilesByAgentAccess, + getStrategyFunctions, + }), /** Resolved endpoint token/pricing config so spending and cost reflect * configured rates for custom-endpoint agents instead of defaults. */ endpointTokenConfig: primaryConfig.endpointTokenConfig, diff --git a/api/server/services/Files/strategies.js b/api/server/services/Files/strategies.js index fd5c57bc97..a21cbbd78c 100644 --- a/api/server/services/Files/strategies.js +++ b/api/server/services/Files/strategies.js @@ -7,6 +7,7 @@ const { uploadFileToS3, saveBufferToS3, getS3FileStream, + resolveStoredS3Key, getS3DownloadURL, deleteFileFromS3, getCloudFrontURL, @@ -121,6 +122,7 @@ const s3Strategy = () => ({ processAvatar: processS3Avatar, handleImageUpload: uploadImageToS3, getDownloadStream: getS3FileStream, + getStorageKey: resolveStoredS3Key, getDownloadURL: getS3DownloadURL, }); @@ -138,6 +140,7 @@ const cloudfrontStrategy = () => ({ processAvatar: processCloudFrontAvatar, handleImageUpload: uploadImageToCloudFront, getDownloadStream: getCloudFrontFileStream, + getStorageKey: resolveStoredS3Key, getDownloadURL: getCloudFrontDownloadURL, }); diff --git a/e2e/config/librechat.e2e.yaml b/e2e/config/librechat.e2e.yaml index be58736d3f..14c49333a8 100644 --- a/e2e/config/librechat.e2e.yaml +++ b/e2e/config/librechat.e2e.yaml @@ -183,9 +183,11 @@ endpoints: # Default capabilities plus run_in_background (off by default upstream) so the # background tool-call e2e can opt an MCP tool into detached dispatch. agents: + sdkHostFiles: {} sdkRuntimes: remote-example: remote: + hostFiles: true url: ws://127.0.0.1:8804/sdk secret: e2e-remote-sdk-fixture-secret-not-a-production-key roles: [ADMIN, USER] diff --git a/e2e/setup/remote-sdk-files.cjs b/e2e/setup/remote-sdk-files.cjs new file mode 100644 index 0000000000..d6e94e33b4 --- /dev/null +++ b/e2e/setup/remote-sdk-files.cjs @@ -0,0 +1,64 @@ +const { createRemoteSdkServer } = require('@librechat/api/sdk'); +const { FakeChatModel } = require('@librechat/agents'); +const { + Annotation, + StateGraph, + START, + END, + messagesStateReducer, +} = require('@langchain/langgraph'); +const { createExampleRun, createExampleModel } = require('../../examples/sdk-runtime/agent.cjs'); + +const runtime = createRemoteSdkServer({ + runtimeId: process.env.SDK_RUNTIME_ID, + secret: process.env.SDK_RUNTIME_SECRET, + authorize: (identity) => identity.runtimeId === process.env.SDK_RUNTIME_ID, + createRun: async (input) => { + if (!input.hostFiles || input.hostFiles.sources.length !== 1) { + throw new Error('Expected one native attachment'); + } + const read = async (file) => { + const chunks = []; + for await (const chunk of input.hostFiles.read(file, input.signal)) chunks.push(chunk); + return Buffer.concat(chunks).toString('utf8'); + }; + const run = await createExampleRun(input, { complex: false }); + run.Graph.overrideModel = createExampleModel(true); + const agent = run.graphRunnable; + const state = Annotation.Root({ + messages: Annotation({ reducer: messagesStateReducer, default: () => [] }), + runStepState: Annotation({ reducer: (_old, next) => next }), + source: Annotation({ reducer: (_old, next) => next }), + }); + run.graphRunnable = new StateGraph(state) + .addNode('capture', async () => { + const source = input.hostFiles.sources[0]; + await read(source); + return { source }; + }) + .addNode('inspect', agent) + .addNode('read_after_approval', async ({ source }) => { + const content = await read(source); + run.Graph.overrideModel = new FakeChatModel({ + responses: [`Remote attachment bytes: ${content}`], + sleep: 10, + }); + return {}; + }) + .addNode('reply', agent) + .addEdge(START, 'capture') + .addEdge('capture', 'inspect') + .addEdge('inspect', 'read_after_approval') + .addEdge('read_after_approval', 'reply') + .addEdge('reply', END) + .compile(input.compileOptions); + return run; + }, + onError: (error) => console.error('Remote file fixture failed', error), +}); +runtime.server.listen(Number(process.env.SDK_RUNTIME_PORT), '127.0.0.1', () => { + console.log('Remote file fixture listening on loopback'); +}); +for (const signal of ['SIGTERM', 'SIGINT']) { + process.once(signal, () => void runtime.close().then(() => process.exit(0))); +} diff --git a/e2e/specs/mock/remote-sdk.spec.ts b/e2e/specs/mock/remote-sdk.spec.ts index b61f5dfe11..a654f9dd00 100644 --- a/e2e/specs/mock/remote-sdk.spec.ts +++ b/e2e/specs/mock/remote-sdk.spec.ts @@ -8,6 +8,7 @@ import { messagesView, requestJson, sendMessage, + uploadViaUnifiedButton, } from './helpers'; import { cleanupAgent, openAgentBuilder, uniqueAgentName } from './agents.helpers'; import { approvalCards, collapseComposerApproval } from './approvals.helpers'; @@ -17,21 +18,25 @@ let workerOutput = ''; test.describe.configure({ mode: 'serial' }); async function startWorker(graph = 'complex') { const outputStart = workerOutput.length; - worker = spawn(process.execPath, ['examples/sdk-runtime/server.cjs'], { - cwd: process.cwd(), - stdio: ['ignore', 'pipe', 'pipe'], - env: { - ...process.env, - SDK_RUNTIME_ID: 'remote-example', - SDK_RUNTIME_PORT: '8804', - SDK_RUNTIME_SECRET: 'e2e-remote-sdk-fixture-secret-not-a-production-key', - SDK_EXAMPLE_GRAPH: graph, - SDK_EXAMPLE_LIVE_MODEL: 'false', - SDK_EXAMPLE_STEP_DELAY_MS: '10000', - SDK_RUNTIME_AGENT_IDS: '', - OPENAI_API_KEY: '', + worker = spawn( + process.execPath, + [graph === 'files' ? 'e2e/setup/remote-sdk-files.cjs' : 'examples/sdk-runtime/server.cjs'], + { + cwd: process.cwd(), + stdio: ['ignore', 'pipe', 'pipe'], + env: { + ...process.env, + SDK_RUNTIME_ID: 'remote-example', + SDK_RUNTIME_PORT: '8804', + SDK_RUNTIME_SECRET: 'e2e-remote-sdk-fixture-secret-not-a-production-key', + SDK_EXAMPLE_GRAPH: graph, + SDK_EXAMPLE_LIVE_MODEL: 'false', + SDK_EXAMPLE_STEP_DELAY_MS: '10000', + SDK_RUNTIME_AGENT_IDS: '', + OPENAI_API_KEY: '', + }, }, - }); + ); worker.stdout?.on('data', (data) => { workerOutput += data.toString(); }); @@ -196,3 +201,59 @@ test('runs the minimal SDK example through the real native UI', async ({ page }, await cleanupAgent(page, agentId); } }); + +test('reads an uploaded native attachment in a separate SDK process and saves the reply', async ({ + page, +}) => { + test.setTimeout(90000); + await stopWorker(); + await startWorker('files'); + let agentId: string | undefined; + try { + await page.goto(NEW_CHAT_PATH); + const token = await getAccessToken(page); + const agent = await requestJson<{ id: string; name: string }>(page, { + path: '/api/agents', + token, + method: 'POST', + body: { + name: uniqueAgentName('SDK native attachment'), + provider: MOCK_ENDPOINTS[1].label, + model: MOCK_ENDPOINTS[1].model, + sdk_runtime: { id: 'remote-example', protocolVersion: 1 }, + }, + }); + agentId = agent.id; + const builder = await openAgentBuilder(page); + await builder.getByRole('combobox', { name: 'Agent', exact: true }).click(); + await page.getByRole('option', { name: agent.name }).click(); + await builder.getByRole('button', { name: 'Select Agent' }).click(); + const content = 'sdk-native-attachment-proof,42'; + const uploaded = await uploadViaUnifiedButton(page, { + name: 'sdk-native.csv', + mimeType: 'text/csv', + content, + }); + expect(uploaded.ok()).toBe(true); + await sendMessage(page, 'Read the attached file through the host file service.'); + await expect(approvalCards(page).first(), workerOutput).toBeVisible({ timeout: 30000 }); + await stopWorker(); + await startWorker('files'); + await page.reload(); + const card = approvalCards(page).first(); + await expect(card).toBeVisible(); + await collapseComposerApproval(page); + await card.getByRole('button', { name: 'Approve', exact: true }).click(); + await card.getByRole('button', { name: 'Submit', exact: true }).click(); + const reply = `Remote attachment bytes: ${content}`; + await expect(messagesView(page).getByText(reply).last(), workerOutput).toBeVisible({ + timeout: 30000, + }); + await page.reload(); + await expect(messagesView(page).getByText(reply).last()).toBeVisible(); + } finally { + await cleanupAgent(page, agentId); + await stopWorker(); + await startWorker(); + } +}); diff --git a/packages/api/src/agents/files/snapshots.spec.ts b/packages/api/src/agents/files/snapshots.spec.ts index f0c0438ca5..177d3bd294 100644 --- a/packages/api/src/agents/files/snapshots.spec.ts +++ b/packages/api/src/agents/files/snapshots.spec.ts @@ -204,3 +204,28 @@ describe('createRunFileSnapshotStore', () => { await store.discard('../../report.csv'); }); }); + +test('reads bounded snapshot ranges without reading the entire file into memory', async () => { + const store = createRunFileSnapshotStore({ + open: async () => Readable.from([Buffer.from('abcdefgh')]), + maxBytes: 8, + maxFiles: 1, + }); + try { + const snapshot = await store.capture(source); + const readFile = jest.spyOn(fs, 'readFile'); + expect((await store.readRange(snapshot.snapshotId, 2, 3)).toString()).toBe('cde'); + expect(await store.readRange(snapshot.snapshotId, 8, 0)).toHaveLength(0); + for (const [offset, length] of [ + [-1, 1], + [7, 2], + [0, Number.MAX_SAFE_INTEGER], + ]) { + await expect(store.readRange(snapshot.snapshotId, offset, length)).rejects.toThrow('range'); + } + expect(readFile).not.toHaveBeenCalled(); + readFile.mockRestore(); + } finally { + await store.close(); + } +}); diff --git a/packages/api/src/agents/files/snapshots.ts b/packages/api/src/agents/files/snapshots.ts index 4d744e3960..0222b4f542 100644 --- a/packages/api/src/agents/files/snapshots.ts +++ b/packages/api/src/agents/files/snapshots.ts @@ -16,6 +16,12 @@ export interface RunFileSnapshot { export interface RunFileSnapshotStore { capture: (source: RunArtifactDescriptor, signal?: AbortSignal) => Promise; read: (snapshotId: string, signal?: AbortSignal) => Promise; + readRange: ( + snapshotId: string, + offset: number, + length: number, + signal?: AbortSignal, + ) => Promise; discard: (snapshotId: string) => Promise; close: () => Promise; } @@ -28,6 +34,7 @@ interface SnapshotEntry { controller: AbortController; reads: Set>; removal?: Promise; + release?: () => void; } /** Keeps immutable private bytes off the heap and outside the public file store. */ @@ -35,12 +42,15 @@ export function createRunFileSnapshotStore({ open, maxBytes, maxFiles, + reserve, }: { open: (source: RunArtifactDescriptor, signal?: AbortSignal) => Promise; /** Aggregate bytes reserved by completed and currently streaming snapshots. */ maxBytes: number; /** Includes captures that have not yet finished opening their source. */ maxFiles: number; + /** Optional shared quota; retained until private bytes have actually been removed. */ + reserve?: (source: RunArtifactDescriptor) => () => void; }): RunFileSnapshotStore { if ( !Number.isSafeInteger(maxBytes) || @@ -126,6 +136,8 @@ export function createRunFileSnapshotStore({ if (entries.get(entry.snapshotId) === entry) { entries.delete(entry.snapshotId); allocatedBytes -= entry.size; + entry.release?.(); + entry.release = undefined; } })(); entry.removal = removal; @@ -149,6 +161,7 @@ export function createRunFileSnapshotStore({ ready: false, controller: new AbortController(), reads: new Set(), + release: reserve?.(source), }; entries.set(entry.snapshotId, entry); const effectiveSignal = AbortSignal.any([ @@ -224,6 +237,66 @@ export function createRunFileSnapshotStore({ return entry ? track(remove(entry)) : Promise.resolve(); } + function readRange( + snapshotId: string, + offset: number, + length: number, + signal?: AbortSignal, + ): Promise { + return track( + (async () => { + assertOpen(signal); + const entry = entries.get(snapshotId); + if (!entry?.ready || !entry.path) + throw new Error('The private artifact snapshot is unavailable.'); + if ( + !Number.isSafeInteger(offset) || + !Number.isSafeInteger(length) || + offset < 0 || + length < 0 || + offset > entry.size || + length > entry.size - offset + ) { + throw new Error('Invalid private artifact snapshot range.'); + } + const effectiveSignal = AbortSignal.any([ + lifetime.signal, + entry.controller.signal, + ...(signal ? [signal] : []), + ]); + const reading = (async () => { + effectiveSignal.throwIfAborted(); + const handle = await fs.open(entry.path!, 'r'); + try { + const buffer = Buffer.alloc(length); + let position = 0; + while (position < length) { + effectiveSignal.throwIfAborted(); + const { bytesRead } = await handle.read( + buffer, + position, + length - position, + offset + position, + ); + if (!bytesRead) throw new Error('The private artifact snapshot is incomplete.'); + position += bytesRead; + } + effectiveSignal.throwIfAborted(); + return buffer; + } finally { + await handle.close(); + } + })(); + entry.reads.add(reading); + try { + return await reading; + } finally { + entry.reads.delete(reading); + } + })(), + ); + } + function close(): Promise { if (closing) return closing; closed = true; @@ -233,11 +306,12 @@ export function createRunFileSnapshotStore({ await Promise.allSettled([...entries.values()].map(remove)); const root = await directory?.catch(() => undefined); if (root) await fs.rm(root, { recursive: true, force: true }); + for (const entry of entries.values()) entry.release?.(); entries.clear(); allocatedBytes = 0; })(); return closing; } - return { capture, read, discard, close }; + return { capture, read, readRange, discard, close }; } diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.ts index 967fce0f57..14b9911340 100644 --- a/packages/api/src/agents/index.ts +++ b/packages/api/src/agents/index.ts @@ -110,3 +110,6 @@ export { captureAuthoredSkills, restoreAuthoredSkills } from './authored'; export { createSdkModelHost } from './remoteSdk/builder'; export type { SdkModelHost } from './remoteSdk/builder'; export * from './turn'; + +export { createSdkFileHost, createChatSdkFileSession } from './remoteSdk/attachments'; +export type { SdkFileHost, SdkFileSession } from './remoteSdk/attachments'; diff --git a/packages/api/src/agents/remoteSdk/attachments.spec.ts b/packages/api/src/agents/remoteSdk/attachments.spec.ts new file mode 100644 index 0000000000..d5805ce64f --- /dev/null +++ b/packages/api/src/agents/remoteSdk/attachments.spec.ts @@ -0,0 +1,399 @@ +import { promises as fs } from 'node:fs'; +import { Readable, PassThrough } from 'node:stream'; +import { agentsEndpointSchema, FileSources } from 'librechat-data-provider'; +import type { TFile } from 'librechat-data-provider'; +import type { SdkFileSession } from './attachments'; +import type { ServerRequest } from '~/types'; +import { resolveStoredS3Key } from '~/storage/s3/crud'; +import { createSdkFileHost } from './attachments'; + +const identity = { + runtimeId: 'runtime', + agentId: 'agent', + runId: 'run', + userId: 'user', + tenantId: 'tenant', + conversationId: 'conversation', +}; +const file: TFile = { + file_id: 'file', + object: 'file', + usage: 0, + user: 'user', + filename: 'input.txt', + filepath: '/private/storage/input', + type: 'text/plain', + bytes: 8, + source: FileSources.local, + embedded: false, +}; +const limits = agentsEndpointSchema.parse({ + sdkHostFiles: { maxFileBytes: 32, maxChunkBytes: 4, maxSnapshotBytes: 1024, maxSnapshotFiles: 2 }, +}).sdkHostFiles!; +const req = { user: { id: 'user', tenantId: 'tenant', role: 'USER' }, config: {} } as ServerRequest; +const sessions: SdkFileSession[] = []; +function setup( + host = createSdkFileHost(limits)!, + sources = [file], + audit?: (event: { action: 'cleanup_failed' }) => void, +) { + let current = structuredClone(sources); + let allowed = true; + const download = jest.fn(async () => Readable.from([Buffer.from('abcdefgh')])); + const loadFiles = jest.fn(async (ids: string[]) => + current.filter((entry) => ids.includes(entry.file_id)), + ); + const filterFiles = jest.fn(async ({ files }: { files: TFile[] }) => (allowed ? files : [])); + const session = host.createSession({ + req, + audit, + getInputs: () => sources, + loadFiles, + filterFiles, + getStrategyFunctions: (source) => ({ + getDownloadStream: download, + ...([FileSources.s3, FileSources.cloudfront].includes(source as FileSources) + ? { getStorageKey: resolveStoredS3Key } + : {}), + }), + }); + sessions.push(session); + const bound = session.bind(identity); + const read = (offset = 0, length = 4) => + bound.service.read({ + version: 1, + identity, + reference: bound.sources[0].reference, + revision: bound.sources[0].revision, + offset, + length, + }); + return { + host, + session, + bound, + read, + download, + loadFiles, + filterFiles, + revoke: () => { + allowed = false; + }, + update: (files: TFile[]) => { + current = files; + }, + }; +} +afterEach(async () => { + await Promise.all(sessions.splice(0).map((session) => session.close())); + jest.restoreAllMocks(); +}); + +test('reads native bytes once with bounded ranges and no locators on the wire', async () => { + const mkdir = jest.spyOn(fs, 'mkdtemp'); + const f = setup(); + expect(f.bound.descriptor.operations).toEqual(['read']); + expect(JSON.stringify(f.bound.sources)).not.toContain('/private/'); + expect(f.bound.sources[0].reference).not.toBe(file.file_id); + const chunks = await Promise.all([f.read(0), f.read(4)]); + expect(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk.data))).toString()).toBe('abcdefgh'); + expect(f.download).toHaveBeenCalledTimes(1); + expect(f.loadFiles).toHaveBeenCalledTimes(3); + expect(f.filterFiles).toHaveBeenCalledWith({ + files: [file], + userId: 'user', + role: 'USER', + agentId: 'agent', + }); + expect(f.host.snapshot().snapshots).toEqual({ operations: 1, reservedBytes: 8 }); + const directory = await mkdir.mock.results[0].value; + await f.session.close(); + await expect(fs.stat(directory)).rejects.toMatchObject({ code: 'ENOENT' }); + expect(f.host.snapshot().snapshots).toEqual({ operations: 0, reservedBytes: 0 }); + await expect(f.read()).rejects.toMatchObject({ code: 'cancelled' }); +}); + +test.each(['revoked', 'deleted', 'changed'] as const)( + 'refuses %s files even after caching bytes', + async (change) => { + const f = setup(); + await f.read(); + if (change === 'revoked') f.revoke(); + if (change === 'deleted') f.update([]); + if (change === 'changed') f.update([{ ...file, filepath: '/replaced/object' }]); + await expect(f.read()).rejects.toMatchObject({ + code: change === 'changed' ? 'conflict' : 'forbidden', + }); + expect(f.download).toHaveBeenCalledTimes(1); + }, +); + +test('rejects forged identities, references, revisions, ranges and writes before storage', async () => { + const f = setup(); + const input = { + version: 1 as const, + identity, + reference: f.bound.sources[0].reference, + revision: f.bound.sources[0].revision, + offset: 0, + length: 4, + }; + for (const changed of [ + { identity: { ...identity, userId: 'other' } }, + { reference: 'file' }, + { revision: 'old' }, + { offset: 7 }, + ]) { + await expect(f.bound.service.read({ ...input, ...changed })).rejects.toBeDefined(); + } + await expect( + f.bound.service.stage( + { + version: 1, + identity, + operationId: 'write', + filename: 'output.txt', + mediaType: 'text/plain', + bytes: 0, + }, + (async function* () {})(), + ), + ).rejects.toMatchObject({ code: 'forbidden' }); + await expect( + f.bound.service.publish({ + version: 1, + identity, + operationId: 'publish', + reference: input.reference, + revision: input.revision, + }), + ).rejects.toMatchObject({ code: 'forbidden' }); + expect(f.download).not.toHaveBeenCalled(); +}); + +test('shares snapshot quotas across sessions and releases them after close', async () => { + const host = createSdkFileHost({ ...limits, maxSnapshotFiles: 1 })!; + const first = setup(host); + const second = setup(host); + await first.read(); + await expect(second.read()).rejects.toMatchObject({ code: 'overflow' }); + expect(second.download).not.toHaveBeenCalled(); + await first.session.close(); + await expect(second.read()).resolves.toMatchObject({ offset: 0 }); +}); + +test.each(['short', 'oversized', 'failed'] as const)( + 'cleans up %s storage responses without exposing bytes', + async (mode) => { + const f = setup(); + f.download.mockImplementationOnce(async () => + Readable.from( + (async function* () { + yield Buffer.from({ short: 'abc', oversized: 'abcdefghijk', failed: 'abcd' }[mode]); + if (mode === 'failed') throw new Error('secret storage credential'); + })(), + ), + ); + await expect(f.read()).rejects.toMatchObject({ + code: mode === 'failed' ? 'unavailable' : 'conflict', + message: `Host file service: ${mode === 'failed' ? 'unavailable' : 'conflict'}`, + }); + expect(f.host.snapshot().snapshots).toEqual({ operations: 0, reservedBytes: 0 }); + await expect(f.read()).resolves.toMatchObject({ offset: 0 }); + }, +); + +test('aborts a streaming snapshot and frees admission after cleanup', async () => { + const f = setup(); + const stream = new PassThrough(); + let opened!: () => void; + const opening = new Promise((resolve) => { + opened = resolve; + }); + f.download.mockImplementationOnce(async () => { + opened(); + return stream; + }); + const reading = f.read(); + const rejected = reading.catch((error: unknown) => error); + await opening; + stream.write(Buffer.from('ab')); + await f.session.close(); + expect(await rejected).toMatchObject({ code: 'cancelled' }); + expect(stream.destroyed).toBe(true); + expect(f.host.snapshot().snapshots).toEqual({ operations: 0, reservedBytes: 0 }); +}); + +test('binds stable references on reconstruction but refuses a different tenant or run', () => { + const f = setup(); + expect(setup().bound.sources).toEqual(f.bound.sources); + expect( + f.session.bind({ + conversationId: identity.conversationId, + tenantId: identity.tenantId, + userId: identity.userId, + runId: identity.runId, + agentId: identity.agentId, + runtimeId: identity.runtimeId, + }), + ).toBe(f.bound); + expect(() => f.session.bind({ ...identity, tenantId: 'other' })).toThrow(); + expect(() => f.session.bind({ ...identity, runId: 'other' })).toThrow(); +}); + +test('does not admit ephemeral storage or oversized files', () => { + expect(() => setup(undefined, [{ ...file, source: FileSources.execute_code }])).toThrow(); + expect(() => setup(undefined, [{ ...file, bytes: 33 }])).toThrow(); +}); + +test('rechecks revocation during a download before returning any bytes', async () => { + const f = setup(); + f.download.mockImplementationOnce(async () => { + f.revoke(); + return Readable.from([Buffer.from('abcdefgh')]); + }); + await expect(f.read()).rejects.toMatchObject({ code: 'forbidden' }); +}); + +test('retains reservations for a timed-out snapshot until run cleanup settles', async () => { + const f = setup(createSdkFileHost({ ...limits, timeoutMs: 25 })!); + const stream = new PassThrough(); + f.download.mockResolvedValueOnce(stream); + await expect(f.read()).rejects.toMatchObject({ code: 'timeout' }); + expect(f.host.snapshot().snapshots.reservedBytes).toBe(8); + await f.session.close(); + expect(stream.destroyed).toBe(true); + expect(f.host.snapshot().snapshots.reservedBytes).toBe(0); +}); + +test('fails closed for protected raw file bytes instead of inspecting only metadata', () => { + const host = createSdkFileHost(limits)!; + const download = jest.fn(); + const session = host.createSession({ + req: { + ...req, + config: { filters: { files: { pii: { uninspectable: 'block' } } } }, + } as ServerRequest, + getInputs: () => [file], + loadFiles: async () => [file], + filterFiles: async ({ files }) => files, + getStrategyFunctions: (source) => ({ + getDownloadStream: download, + ...([FileSources.s3, FileSources.cloudfront].includes(source as FileSources) + ? { getStorageKey: resolveStoredS3Key } + : {}), + }), + }); + sessions.push(session); + expect(() => session.bind(identity)).toThrow('forbidden'); + expect(download).not.toHaveBeenCalled(); +}); + +test('retains process quota when failed capture cleanup cannot remove private bytes', async () => { + const f = setup(); + f.download.mockResolvedValueOnce(Readable.from([Buffer.from('short')])); + const remove = jest.spyOn(fs, 'rm').mockRejectedValueOnce(new Error('disk unavailable')); + await expect(f.read()).rejects.toMatchObject({ code: 'unavailable' }); + expect(f.host.snapshot().snapshots).toEqual({ operations: 1, reservedBytes: 8 }); + remove.mockRestore(); + await f.session.close(); + expect(f.host.snapshot().snapshots).toEqual({ operations: 0, reservedBytes: 0 }); +}); + +test('keeps admission for an uncooperative opener until its late stream is destroyed', async () => { + const f = setup(createSdkFileHost({ ...limits, timeoutMs: 25 })!); + let resolve!: (stream: Readable) => void; + f.download.mockReturnValueOnce( + new Promise((done) => { + resolve = done; + }), + ); + await expect(f.read()).rejects.toMatchObject({ code: 'timeout' }); + const closing = f.session.close(); + await new Promise((done) => setImmediate(done)); + const late = new PassThrough(); + try { + expect(f.host.snapshot()).toEqual({ + operations: { operations: 1, reservedBytes: 8 }, + snapshots: { operations: 1, reservedBytes: 8 }, + }); + } finally { + resolve(late); + await closing; + } + expect(late.destroyed).toBe(true); + expect(f.host.snapshot().snapshots).toEqual({ operations: 0, reservedBytes: 0 }); +}); + +test('does not clone extracted content into the file binding', () => { + const host = createSdkFileHost(limits)!; + const clone = jest.spyOn(global, 'structuredClone'); + const input = { ...file, text: 'already-loaded extracted content' }; + const session = host.createSession({ + req, + getInputs: () => [input], + loadFiles: async () => [input], + filterFiles: async ({ files }) => files, + getStrategyFunctions: () => ({ getDownloadStream: async () => Readable.from([]) }), + }); + sessions.push(session); + session.bind(identity); + expect(clone.mock.calls).toEqual([ + [expect.objectContaining({ file_id: file.file_id, filepath: file.filepath })], + ]); + expect(clone.mock.calls[0][0]).not.toHaveProperty('text'); +}); + +test.each([FileSources.s3, FileSources.cloudfront])( + 'keeps %s references valid across URL renewal and legacy-key backfill', + async (source) => { + const key = 'uploads/user/input.txt'; + const original = { + ...file, + source, + filepath: `https://bucket.s3.amazonaws.com/${key}?X-Amz-Signature=old`, + }; + const refreshed = { + ...original, + storageKey: key, + filepath: `https://bucket.s3.amazonaws.com/${key}?X-Amz-Signature=new`, + }; + const f = setup(undefined, [original]); + f.update([refreshed]); + await expect(f.read()).resolves.toMatchObject({ offset: 0 }); + expect(f.download).toHaveBeenCalledWith(req, key, expect.anything()); + const resumed = setup(undefined, [refreshed]); + expect(resumed.bound.sources).toEqual(f.bound.sources); + await expect( + resumed.bound.service.read({ + version: 1, + identity, + reference: f.bound.sources[0].reference, + revision: f.bound.sources[0].revision, + offset: 4, + length: 4, + }), + ).resolves.toMatchObject({ offset: 4 }); + resumed.update([{ ...refreshed, storageKey: 'uploads/user/replaced.txt' }]); + await expect(resumed.read()).rejects.toMatchObject({ code: 'conflict' }); + }, +); + +test('isolates failed cleanup and diagnostic errors while retaining disk quota', async () => { + const mkdir = jest.spyOn(fs, 'mkdtemp'); + const audit = jest.fn(() => { + throw new Error('diagnostic failed'); + }); + const f = setup(undefined, [file], audit); + await f.read(); + const directory = await mkdir.mock.results[0].value; + const remove = jest.spyOn(fs, 'rm').mockRejectedValue(new Error('filesystem unavailable')); + try { + await expect(f.session.close()).resolves.toBeUndefined(); + expect(audit).toHaveBeenCalledWith({ action: 'cleanup_failed' }); + expect(f.host.snapshot().snapshots).toEqual({ operations: 1, reservedBytes: 8 }); + } finally { + remove.mockRestore(); + await fs.rm(directory, { recursive: true, force: true }); + } +}); diff --git a/packages/api/src/agents/remoteSdk/attachments.ts b/packages/api/src/agents/remoteSdk/attachments.ts new file mode 100644 index 0000000000..5f1c4bbda6 --- /dev/null +++ b/packages/api/src/agents/remoteSdk/attachments.ts @@ -0,0 +1,365 @@ +import { createHash } from 'node:crypto'; +import { FileSources } from 'librechat-data-provider'; +import { Readable, addAbortSignal } from 'node:stream'; +import { HostFileAdmission, HostFileServiceError, createHostFileService } from '@librechat/agents'; +import type { TAgentsEndpoint, TFile } from 'librechat-data-provider'; +import type { HostFileDescriptor } from '@librechat/agents'; +import type { RunArtifactDescriptor } from '~/files/code/publication'; +import type { TFilterFilesByAgentAccess } from '~/agents/resources'; +import type { ServerRequest, StrategyFunctions } from '~/types'; +import type { RunFileSnapshot } from '~/agents/files/snapshots'; +import type { RemoteSdkHostServices } from './types'; +import type { SdkAgentIdentity } from './identity'; +import { assertModelBoundContent } from '~/middleware/modelBoundContent'; +import { createRunFileSnapshotStore } from '~/agents/files/snapshots'; +import { hasActiveFilePolicy } from '~/protection/files'; +import { resolveDownloadPath } from '~/storage/path'; + +type Limits = NonNullable['sdkHostFiles']>; +type Binding = NonNullable; +type NativeFile = Pick< + TFile, + | 'file_id' + | 'user' + | 'source' + | 'filepath' + | 'bytes' + | 'type' + | 'filename' + | 'updatedAt' + | 'storageKey' +>; +interface Inputs { + req: ServerRequest; + audit?: (event: { action: 'cleanup_failed' }) => void; + /** Host-selected, already hydrated attachments; never IDs supplied by the worker. */ + getInputs: () => readonly TFile[]; + loadFiles: (ids: string[]) => Promise; + filterFiles: TFilterFilesByAgentAccess; + getStrategyFunctions: (source: string) => StrategyFunctions; +} +export interface SdkFileSession { + bind(identity: Readonly, signal?: AbortSignal): Binding; + close(): Promise; +} +export interface SdkFileHost { + createSession(inputs: Inputs): SdkFileSession; + snapshot(): { + operations: ReturnType; + snapshots: ReturnType; + }; +} + +const nativeSources = new Set([ + FileSources.local, + FileSources.s3, + FileSources.cloudfront, + FileSources.azure_blob, + FileSources.firebase, +]); +const digest = (value: unknown): string => + createHash('sha256').update(JSON.stringify(value)).digest('hex'); +const identityKey = (identity: Readonly): string => + digest([ + identity.runtimeId, + identity.agentId, + identity.runId, + identity.userId, + identity.tenantId, + identity.conversationId, + ]); +/** Revision includes the canonical object locator, but the locator never crosses the bridge. */ +function stableLocator(file: NativeFile): string { + const locator = resolveDownloadPath(file); + if (file.source !== FileSources.local && /^https?:\/\//.test(locator)) { + const url = new URL(locator); + return url.origin + url.pathname; + } + return locator; +} +const revision = (file: NativeFile, locator: string): string => + digest([ + file.file_id, + file.user, + file.source ?? FileSources.local, + locator, + file.bytes, + file.type, + file.filename, + file.updatedAt, + ]); + +/** One process owner, shared across users, runtimes, and concurrent/resumed turns. */ +export function createSdkFileHost(limits: Limits | undefined): SdkFileHost | undefined { + if (!limits) return undefined; + const operations = new HostFileAdmission({ + maxConcurrentOperations: limits.maxConcurrentOperations, + maxBufferedBytes: limits.maxBufferedBytes, + }); + const snapshots = new HostFileAdmission({ + maxConcurrentOperations: limits.maxSnapshotFiles, + maxBufferedBytes: limits.maxSnapshotBytes, + }); + return { + snapshot: () => ({ operations: operations.snapshot(), snapshots: snapshots.snapshot() }), + createSession({ + req, + audit, + getInputs, + loadFiles, + filterFiles, + getStrategyFunctions, + }): SdkFileSession { + const user = req.user; + if (!user) throw new HostFileServiceError('forbidden'); + const { id: userId, tenantId, role } = user; + const fileRevision = (file: NativeFile): string => + revision( + file, + getStrategyFunctions(file.source ?? FileSources.local).getStorageKey?.(file) ?? + stableLocator(file), + ); + let binding: Binding | undefined; + let boundIdentity: string | undefined; + let closed = false; + const captures = new Map>(); + const openings = new WeakMap>(); + const selected = new Map(); + const lifetime = new AbortController(); + const store = createRunFileSnapshotStore({ + maxBytes: limits.maxSnapshotBytes, + maxFiles: limits.maxSnapshotFiles, + reserve: (source) => { + const item = selected.get(source.id); + if (!item) throw new HostFileServiceError('forbidden'); + const release = snapshots.acquire(item.file.bytes); + return () => { + const pending = openings.get(source); + if (pending) void pending.then(release, release); + else release(); + }; + }, + open: async (source, signal) => { + const item = selected.get(source.id); + if (!item) throw new HostFileServiceError('forbidden'); + const opening = Promise.resolve().then(() => { + signal?.throwIfAborted(); + return getStrategyFunctions(item.file.source ?? FileSources.local).getDownloadStream( + req, + resolveDownloadPath(item.file), + { signal }, + ); + }); + openings.set(source, opening); + const stream = await opening; + if (signal?.aborted) { + stream.destroy(); + signal.throwIfAborted(); + } + if (signal) addAbortSignal(signal, stream); + // Bound actual disk consumption even when storage disagrees with metadata. + return Readable.from( + (async function* () { + let bytes = 0; + try { + for await (const chunk of stream) { + signal?.throwIfAborted(); + if (!Buffer.isBuffer(chunk) && !(chunk instanceof Uint8Array)) + throw new HostFileServiceError('unavailable'); + bytes += chunk.byteLength; + if (bytes > item.file.bytes) throw new HostFileServiceError('conflict'); + yield chunk; + } + if (bytes !== item.file.bytes) throw new HostFileServiceError('conflict'); + } finally { + stream.destroy(); + } + })(), + ); + }, + }); + async function authorize( + item: { file: NativeFile; descriptor: HostFileDescriptor }, + identity: Readonly, + ): Promise { + const files = await loadFiles([item.file.file_id]); + const admitted = await filterFiles({ + files, + userId: identity.userId, + role, + agentId: identity.agentId, + }); + const current = admitted.find((file) => file.file_id === item.file.file_id); + if (!current) throw new HostFileServiceError('forbidden'); + if (fileRevision(current) !== item.descriptor.revision) + throw new HostFileServiceError('conflict'); + assertModelBoundContent({ filters: req.config?.filters, files: [current] }); + item.file.filepath = current.filepath; + item.file.storageKey = current.storageKey; + } + return { + bind(identity, signal) { + if (closed) throw new HostFileServiceError('unavailable'); + if (identity.userId !== userId || identity.tenantId !== (tenantId ?? undefined)) + throw new HostFileServiceError('forbidden'); + const key = identityKey(identity); + if (binding) { + if (key !== boundIdentity) throw new HostFileServiceError('forbidden'); + return binding; + } + const inputs = [...new Map(getInputs().map((file) => [file.file_id, file])).values()]; + if (inputs.length > limits.maxSnapshotFiles) throw new HostFileServiceError('overflow'); + // Raw byte reads cannot substitute metadata inspection for content transformation. + if (inputs.length && hasActiveFilePolicy(req.config?.filters)) + throw new HostFileServiceError('forbidden'); + assertModelBoundContent({ filters: req.config?.filters, files: inputs }); + selected.clear(); + const sources = inputs.map((file): HostFileDescriptor => { + if (!nativeSources.has(file.source ?? FileSources.local)) + throw new HostFileServiceError('incompatible'); + if ( + !Number.isSafeInteger(file.bytes) || + file.bytes < 0 || + file.bytes > limits.maxFileBytes + ) + throw new HostFileServiceError('overflow'); + const descriptor = Object.freeze({ + reference: digest([key, file.file_id]), + revision: fileRevision(file), + filename: file.filename, + mediaType: file.type, + bytes: file.bytes, + }); + const { + file_id, + user, + source, + filepath, + bytes, + type, + filename, + updatedAt, + storageKey, + } = file; + selected.set(descriptor.reference, { + file: structuredClone({ + file_id, + user, + source, + filepath, + bytes, + type, + filename, + updatedAt, + storageKey, + }), + descriptor, + }); + return descriptor; + }); + const effectiveSignal = AbortSignal.any([lifetime.signal, ...(signal ? [signal] : [])]); + const service = createHostFileService({ + identity, + descriptor: { + version: 1, + operations: ['read'], + maxFileBytes: limits.maxFileBytes, + maxChunkBytes: limits.maxChunkBytes, + }, + admission: operations, + timeoutMs: limits.timeoutMs, + signal: effectiveSignal, + store: { + async read(request, readSignal) { + const item = selected.get(request.reference); + if (!item) throw new HostFileServiceError('forbidden'); + if (request.revision !== item.descriptor.revision) + throw new HostFileServiceError('conflict'); + if ( + request.offset > item.file.bytes || + request.length > item.file.bytes - request.offset + ) + throw new HostFileServiceError('conflict'); + let capture = captures.get(request.reference); + if (!capture) { + // A snapshot belongs to the run, not to whichever chunk request arrived first. + capture = (async () => { + await authorize(item, identity); + effectiveSignal.throwIfAborted(); + const source = { + id: request.reference, + name: item.file.filename, + sessionId: identity.runId, + }; + try { + return await store.capture(source, effectiveSignal); + } finally { + // SDK timeouts may return early; admission stays held until an + // uncooperative native opener settles and its late stream is destroyed. + await openings.get(source)?.catch(() => undefined); + } + })(); + captures.set(request.reference, capture); + void capture.catch(() => { + if (captures.get(request.reference) === capture) + captures.delete(request.reference); + }); + } + const captured = await capture; + readSignal?.throwIfAborted(); + const data = await store.readRange( + captured.snapshotId, + request.offset, + request.length, + readSignal, + ); + // Check current permission/revision after IO, including cached snapshots. + await authorize(item, identity); + readSignal?.throwIfAborted(); + return { + reference: request.reference, + revision: request.revision, + offset: request.offset, + data, + }; + }, + async stage() { + throw new HostFileServiceError('incompatible'); + }, + async publish() { + throw new HostFileServiceError('incompatible'); + }, + }, + }); + binding = { ...service, sources: Object.freeze(sources) }; + boundIdentity = key; + return binding; + }, + async close() { + closed = true; + lifetime.abort(); + await Promise.allSettled(captures.values()); + await store.close().catch(() => { + // Cleanup must not prevent usage settlement or turn finalization. The + // snapshot store retains quota for private bytes it could not delete. + try { + audit?.({ action: 'cleanup_failed' }); + } catch { + /* Diagnostics cannot own settlement. */ + } + }); + captures.clear(); + selected.clear(); + }, + }; + }, + }; +} + +/** Request wiring supplies native storage and authorization; absence stays opt-out. */ +export function createChatSdkFileSession({ + host, + ...inputs +}: Inputs & { host?: SdkFileHost }): SdkFileSession | undefined { + return host?.createSession(inputs); +} diff --git a/packages/api/src/agents/remoteSdk/types.ts b/packages/api/src/agents/remoteSdk/types.ts index 3788abf833..7e268bfd17 100644 --- a/packages/api/src/agents/remoteSdk/types.ts +++ b/packages/api/src/agents/remoteSdk/types.ts @@ -30,6 +30,8 @@ export interface RemoteSdkRecoveryOptions { export interface RemoteSdkOptions { /** Opt in to the saved-agent host model, configured by the operator. */ hostModel?: boolean; + /** Opt in to native host attachment reads. */ + hostFiles?: boolean; recovery?: RemoteSdkRecoveryOptions; url: string; secret: string; diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.ts index 890208da9d..aadb3159ae 100644 --- a/packages/api/src/agents/run.ts +++ b/packages/api/src/agents/run.ts @@ -65,6 +65,7 @@ import type { LangfuseTraceContext } from '~/langfuse/identity'; import type { ResolvedAlwaysApplySkill } from '~/agents/skills'; import type { CodeExecutionContext } from '~/agents/execution'; import type { SubagentCodeHostArgSpecs } from '~/code/targets'; +import type { SdkFileSession } from './remoteSdk/attachments'; import type { MCPToolAlias } from '~/tools/classification'; import type { ReviewedToolApprovals } from './hitl/modes'; import type { SubagentUsageEvent } from '~/agents/usage'; @@ -2326,6 +2327,7 @@ export async function createRun({ sessionStartSource, loadSdkRuntime, sdkModelHost, + sdkFiles, sdkResumeState, streaming = true, streamUsage = true, @@ -2483,6 +2485,7 @@ export async function createRun({ toolInputValidationErrors?: Map; loadSdkRuntime?: SdkAgentRuntimeLoader; sdkModelHost?: SdkModelHost; + sdkFiles?: SdkFileSession; sdkResumeState?: import('./remoteSdk/types').RemoteSdkResumeState; } & Pick< RunConfig, @@ -3343,6 +3346,7 @@ export async function createRun({ config: runConfig, loadModule: loadSdkRuntime, modelHost: sdkModelHost, + files: sdkFiles, resumeState: sdkResumeState, signal, identity: { diff --git a/packages/api/src/agents/sdk.spec.ts b/packages/api/src/agents/sdk.spec.ts index d83b5744be..2133c9636a 100644 --- a/packages/api/src/agents/sdk.spec.ts +++ b/packages/api/src/agents/sdk.spec.ts @@ -263,3 +263,20 @@ it('refuses remote execution when host model protection cannot cross the boundar ), ).toMatchObject({ binding: remoteBinding, remote: remoteEndpoint.sdkRuntimes.private.remote }); }); + +test('refuses native file-enabled runtimes in callers without a file host', async () => { + await expect( + createSdkAgentRun({ + config: config(), + identity, + registration: { + binding, + remote: { + url: 'ws://127.0.0.1:8804/sdk', + secret: 'file-test-secret-at-least-32-characters', + hostFiles: true, + }, + }, + }), + ).rejects.toMatchObject({ code: 'sdk_runtime_unavailable' }); +}); diff --git a/packages/api/src/agents/sdk.ts b/packages/api/src/agents/sdk.ts index bdb88fba11..5c8a201b27 100644 --- a/packages/api/src/agents/sdk.ts +++ b/packages/api/src/agents/sdk.ts @@ -6,6 +6,7 @@ import { extractEnvVariable } from 'librechat-data-provider'; import type { Agent, SdkRuntimeBinding, TAgentsEndpoint } from 'librechat-data-provider'; import type { RunConfig } from '@librechat/agents'; import type { RemoteSdkOptions, RemoteSdkResumeState } from './remoteSdk/types'; +import type { SdkFileSession } from './remoteSdk/attachments'; import type { SdkAgentIdentity } from './remoteSdk/identity'; import type { SdkModelHost } from './remoteSdk/builder'; import { createRemoteSdkRun } from './remoteSdk/client'; @@ -121,6 +122,7 @@ export async function createSdkAgentRun({ signal, resumeState, modelHost, + files, loadModule = requireRuntime, }: { registration: SdkRegistration; @@ -129,6 +131,7 @@ export async function createSdkAgentRun({ signal?: AbortSignal; resumeState?: RemoteSdkResumeState; modelHost?: SdkModelHost; + files?: SdkFileSession; loadModule?: SdkAgentRuntimeLoader; }): ReturnType { signal?.throwIfAborted(); @@ -141,16 +144,24 @@ export async function createSdkAgentRun({ runtimeId: registration.binding.id, }); if (registration.remote != null) { - if (registration.remote.hostModel && !modelHost) { + if ( + (registration.remote.hostModel && !modelHost) || + (registration.remote.hostFiles && !files) + ) { throw new SdkAgentRuntimeError('sdk_runtime_unavailable'); } return createRemoteSdkRun({ config, identity: boundIdentity, resumeState, - hostServices: registration.remote.hostModel - ? modelHost?.bind(config, boundIdentity, signal) - : undefined, + hostServices: { + ...(registration.remote.hostModel + ? modelHost?.bind(config, boundIdentity, signal) + : undefined), + ...(registration.remote.hostFiles + ? { files: files?.bind(boundIdentity, signal) } + : undefined), + }, remote: { ...registration.remote, secret: extractEnvVariable(registration.remote.secret) }, }); } diff --git a/packages/api/src/types/files.ts b/packages/api/src/types/files.ts index b69f9613db..0b2de86967 100644 --- a/packages/api/src/types/files.ts +++ b/packages/api/src/types/files.ts @@ -182,6 +182,8 @@ export interface ProcessedFile { /** Subset of storage strategy functions needed by download and delete access flows. */ export interface StrategyFunctions { + /** Canonical object identity independent of renewable delivery URLs. */ + getStorageKey?: (file: { filepath: string; storageKey?: string | null }) => string; getDownloadStream: ( req: ServerRequest, filepath: string, diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts index e1dba1cd70..d7386708ab 100644 --- a/packages/data-provider/src/config.spec.ts +++ b/packages/data-provider/src/config.spec.ts @@ -3522,6 +3522,26 @@ describe('complete channel operator configuration', () => { }); describe('remote SDK runtime configuration', () => { + it('keeps native file reads opt-in and bounds process budgets', () => { + expect(agentsEndpointSchema.parse({}).sdkHostFiles).toBeUndefined(); + const parsed = agentsEndpointSchema.parse({ + sdkHostFiles: {}, + sdkRuntimes: { + runtime: { + remote: { url: 'wss://runtime.example/sdk', secret: 'secret', hostFiles: true }, + }, + }, + }); + expect(parsed.sdkHostFiles?.maxChunkBytes).toBe(262144); + expect(parsed.sdkRuntimes?.runtime).toMatchObject({ remote: { hostFiles: true } }); + for (const field of Object.keys(parsed.sdkHostFiles!)) { + for (const value of [0, -1, Number.MAX_SAFE_INTEGER]) + expect(agentsEndpointSchema.safeParse({ sdkHostFiles: { [field]: value } }).success).toBe( + false, + ); + } + expect(agentsEndpointSchema.safeParse({ sdkHostFiles: { unknown: true } }).success).toBe(false); + }); it('opts into builder models with bounded process-wide admission', () => { expect(agentsEndpointSchema.parse({}).sdkHostModels).toBeUndefined(); const result = agentsEndpointSchema.parse({ diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 435f13c038..c72a692cb9 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -1905,6 +1905,19 @@ export const agentsEndpointSchema = baseEndpointSchema }) .strict() .optional(), + /** Native attachment reads; budgets are shared by every run in this server process. */ + sdkHostFiles: z + .object({ + maxConcurrentOperations: z.number().int().min(1).max(10000).default(32), + maxBufferedBytes: z.number().int().min(1024).max(1073741824).default(16777216), + maxSnapshotBytes: z.number().int().min(1024).max(10737418240).default(268435456), + maxSnapshotFiles: z.number().int().min(1).max(10000).default(128), + maxFileBytes: z.number().int().min(1).max(1073741824).default(20971520), + maxChunkBytes: z.number().int().min(1).max(1048576).default(262144), + timeoutMs: z.number().int().min(100).max(600000).default(60000), + }) + .strict() + .optional(), /** Trusted server-side SDK modules. Unconfigured runtimes cannot execute. */ sdkRuntimes: z .record( @@ -1926,6 +1939,7 @@ export const agentsEndpointSchema = baseEndpointSchema .regex(/^wss?:\/\//), secret: z.string().min(1), hostModel: z.boolean().optional(), + hostFiles: z.boolean().optional(), recovery: z .object({ routes: z diff --git a/packages/data-schemas/src/methods/file.publication.spec.ts b/packages/data-schemas/src/methods/file.publication.spec.ts index 3796f3519e..f889dc5889 100644 --- a/packages/data-schemas/src/methods/file.publication.spec.ts +++ b/packages/data-schemas/src/methods/file.publication.spec.ts @@ -52,6 +52,32 @@ describe('Run artifact persistence', () => { }, }); + it('projects storage authorization without fetching extracted content', async () => { + const file = await methods.publishRunArtifactFile({ + scope, + provenance: provenance(), + file: content(), + }); + const [metadata] = await methods.getRunFileCandidates([file.file_id], scope.tenantId, { + storageOnly: true, + }); + expect(metadata).toMatchObject({ + file_id: file.file_id, + user: scope.userId, + filepath: file.filepath, + bytes: file.bytes, + updatedAt: file.updatedAt, + }); + expect(metadata).not.toHaveProperty('text'); + expect(metadata).not.toHaveProperty('metadata'); + expect((await methods.getRunFileCandidates([file.file_id], scope.tenantId))[0].text).toBe( + content().text, + ); + expect( + await methods.getRunFileCandidates([file.file_id], 'foreign', { storageOnly: true }), + ).toEqual([]); + }); + beforeAll(async () => { mongo = await MongoMemoryServer.create(); await mongoose.connect(mongo.getUri()); diff --git a/packages/data-schemas/src/methods/file.ts b/packages/data-schemas/src/methods/file.ts index 8bd5958c24..d4c35541b4 100644 --- a/packages/data-schemas/src/methods/file.ts +++ b/packages/data-schemas/src/methods/file.ts @@ -406,7 +406,11 @@ function serializeRunArtifact( /** Factory function that takes mongoose instance and returns the file methods */ export function createFileMethods(mongoose: typeof import('mongoose')): { - getRunFileCandidates: (fileIds: readonly string[], tenantId?: string | null) => Promise; + getRunFileCandidates: ( + fileIds: readonly string[], + tenantId?: string | null, + options?: { storageOnly?: boolean }, + ) => Promise; claimRunArtifactFile: (scope: RunArtifactScope) => Promise; publishRunArtifactFile: (input: PublishRunArtifactInput) => Promise; findRunArtifactFile: (scope: RunArtifactScope) => Promise; @@ -521,15 +525,23 @@ export function createFileMethods(mongoose: typeof import('mongoose')): { async function getRunFileCandidates( fileIds: readonly string[], tenantId?: string | null, + options?: { storageOnly?: boolean }, ): Promise { if (fileIds.length === 0) { return []; } const File = mongoose.models.File as Model; - const files = await File.find({ + const query = File.find({ file_id: { $in: fileIds }, tenantId: tenantId ?? null, - }).lean(); + }); + // Range-read authorization must not fetch extracted file content for every chunk. + if (options?.storageOnly) { + query.select( + 'file_id user source filepath storageKey bytes type filename updatedAt object usage embedded', + ); + } + const files = await query.lean(); return files.map(({ user, _id, ...file }) => ({ ...file, user: String(user),