🥤 feat: Let Remote SDK Agents Read Native Chat Attachments (#18419)

* feat: bind native chat attachments to remote SDK file reads

* fix: preserve SDK file settlement and stable storage identity
This commit is contained in:
Danny Avila 2026-11-18 11:49:24 -05:00 • committed by GitHub
parent 25a5a80d5d
commit e50a30653c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 1218 additions and 26 deletions

View file

@ -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();

View file

@ -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

View file

@ -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({

View file

@ -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,

View file

@ -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,
});

View file

@ -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]

View file

@ -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)));
}

View file

@ -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();
}
});

View file

@ -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();
}
});

View file

@ -16,6 +16,12 @@ export interface RunFileSnapshot {
export interface RunFileSnapshotStore {
capture: (source: RunArtifactDescriptor, signal?: AbortSignal) => Promise<RunFileSnapshot>;
read: (snapshotId: string, signal?: AbortSignal) => Promise<Buffer>;
readRange: (
snapshotId: string,
offset: number,
length: number,
signal?: AbortSignal,
) => Promise<Buffer>;
discard: (snapshotId: string) => Promise<void>;
close: () => Promise<void>;
}
@ -28,6 +34,7 @@ interface SnapshotEntry {
controller: AbortController;
reads: Set<Promise<Buffer>>;
removal?: Promise<void>;
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<Readable>;
/** 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<Buffer> {
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<void> {
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 };
}

View file

@ -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';

View file

@ -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<void>((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<Readable>((done) => {
resolve = done;
}),
);
await expect(f.read()).rejects.toMatchObject({ code: 'timeout' });
const closing = f.session.close();
await new Promise<void>((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 });
}
});

View file

@ -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<NonNullable<TAgentsEndpoint>['sdkHostFiles']>;
type Binding = NonNullable<RemoteSdkHostServices['files']>;
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<TFile[]>;
filterFiles: TFilterFilesByAgentAccess;
getStrategyFunctions: (source: string) => StrategyFunctions;
}
export interface SdkFileSession {
bind(identity: Readonly<SdkAgentIdentity>, signal?: AbortSignal): Binding;
close(): Promise<void>;
}
export interface SdkFileHost {
createSession(inputs: Inputs): SdkFileSession;
snapshot(): {
operations: ReturnType<HostFileAdmission['snapshot']>;
snapshots: ReturnType<HostFileAdmission['snapshot']>;
};
}
const nativeSources = new Set<string>([
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<SdkAgentIdentity>): 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<string, Promise<RunFileSnapshot>>();
const openings = new WeakMap<RunArtifactDescriptor, Promise<Readable>>();
const selected = new Map<string, { file: NativeFile; descriptor: HostFileDescriptor }>();
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<SdkAgentIdentity>,
): Promise<void> {
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);
}

View file

@ -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;

View file

@ -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<string, ToolInputValidationError>;
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: {

View file

@ -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' });
});

View file

@ -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<typeof Run.create> {
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) },
});
}

View file

@ -182,6 +182,8 @@ export interface ProcessedFile<T = IMongoFile> {
/** 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,

View file

@ -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({

View file

@ -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

View file

@ -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());

View file

@ -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<TFile[]>;
getRunFileCandidates: (
fileIds: readonly string[],
tenantId?: string | null,
options?: { storageOnly?: boolean },
) => Promise<TFile[]>;
claimRunArtifactFile: (scope: RunArtifactScope) => Promise<RunArtifactClaim>;
publishRunArtifactFile: (input: PublishRunArtifactInput) => Promise<RunArtifactFile>;
findRunArtifactFile: (scope: RunArtifactScope) => Promise<RunArtifactFile | null>;
@ -521,15 +525,23 @@ export function createFileMethods(mongoose: typeof import('mongoose')): {
async function getRunFileCandidates(
fileIds: readonly string[],
tenantId?: string | null,
options?: { storageOnly?: boolean },
): Promise<TFile[]> {
if (fileIds.length === 0) {
return [];
}
const File = mongoose.models.File as Model<IMongoFile>;
const files = await File.find({
const query = File.find({
file_id: { $in: fileIds },
tenantId: tenantId ?? null,
}).lean<PlainFileDocument[]>();
});
// 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<PlainFileDocument[]>();
return files.map(({ user, _id, ...file }) => ({
...file,
user: String(user),