🛻 feat: Bridge Host File Services to Remote SDK Graphs (#18410)

* feat: bridge SDK host file services over remote transport

* docs: clarify file rollout and close example startup cleanup
This commit is contained in:
Danny Avila 2026-11-18 09:03:03 -05:00 • committed by GitHub
parent dcbccb4341
commit 09ea0c9273
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 1463 additions and 7 deletions

View file

@ -166,7 +166,7 @@ adapters and unverified behaviors remain release gates for products that depend
| Stream circuit breakers and tool-policy hooks | Forwarded to the worker; hook failure stops execution | Domain tools must also authorize signed caller identity; trusted factories must retain the supplied adapters. |
| Agent-builder model, parameters, tools, capabilities | Opt-in saved-agent primary model settings execute on the host; host schema tools are available | Worker must retain the host model/profile. Fallbacks, local graph tools, and context/summary policy still require adapters. |
| Host MCP, web/code/browser tools, user tool credentials | Authorized root-agent schema tools execute through host RPC | Host credentials remain local; child-agent authorization and broader host-service parity remain separate integrations. |
| Uploaded files, generated artifacts, download authorization | Message data can cross the wire | Host file services, sandbox storage, and artifact authorization do not have remote adapters; attachment/file parity is not established. |
| Uploaded files, generated artifacts, download authorization | Programmatic SDK file read/stage/publish transport; native host adapter pending | Native authorization/storage/publication activation, sandbox storage, and artifact UI acceptance remain separate; attachment/file parity is not established. |
| Live steering and mid-stream preemption | Not integrated | A remote execution-control adapter and acceptance tests are required. |
| Foreground/nested/detached subagents | Worker may construct its own SDK graph | Native configured compositions are rejected; detached child checkpoint threads/context/usage sinks are not integrated. |
| Context pruning, compaction, summaries, cache/fading policy | Worker can use SDK features; terminal context metadata is returned | Host configuration and continuation policy are not automatically installed on the worker. Main-chat behavioral/performance parity is not established. |
@ -454,3 +454,41 @@ Before initial admission, child/summary model calls without root lineage and con
attempts fail closed; parallel/composed admission needs its own ownership contract. This does not
establish full main-chat parity. Context pruning, summary/compaction configuration, child/multi-model
routing, files, production billing/tracing and Console UI acceptance remain separate work.
## Host file transport (SDK 4.2.10)
Programmatic hosts can pass `hostServices.files` to `createRemoteSdkRun`: an already authorized
`createHostFileService` binding plus a `sources` array of `HostFileDescriptor` values. A worker
advertising `hostFiles: 1` receives `input.hostFiles`, the SDK's `read`, `stage`, and `publish`
bindings with those source descriptors. Older workers fail before graph execution when files are
requested; hosts without a file binding retain the existing behavior. Host services and credentials
are never serialized into the worker.
The transport uses the existing authenticated, bidirectional WebSocket and recovery protocol.
Reads fetch one range at a time; uploads are pulled by the host one chunk at a time. No transfer
buffers an entire file. Negotiated chunk size is capped by the SDK binding and the connection's
frame/buffer limits, including encoding overhead. Per-invocation cancellation propagates through
both directions, and execution cancellation ends all transfers. File payloads are encrypted before
they enter RPC queues and replay journals. Source descriptors are public metadata, so hosts must
only supply metadata approved for the runtime.
Use a shared `HostFileAdmission` in the host's quota scope. The SDK enforces bound execution
identity, byte length, SHA-256, deadlines, and cleanup admission; the adapter must still reauthorize
canonical ACLs/revisions on each operation and apply file/content policies before returning bytes
or publishing. A reference is not a URL, path, or download credential. Source lists do not create
child/sibling grants. Publication receipts must flow through the host's native persistence and
attachment events. The transport never retries a mutation as a new logical operation: live reconnect
replays existing RPC traffic, while explicit retries require durable host reconciliation using the
SDK operation ID. Process-restart recovery of an in-flight transfer is not supported.
**Activation boundary:** this is the programmatic transport adapter. The stock Console/chat caller
does not yet install a native file service. LibreChat's authorized attachment reads, private durable
staging, publication receipts/events, previews, retention, and browser downloads must be wired in
that next adapter slice. This transport does not establish file/artifact UI parity, sandbox mounts, rich UI
artifacts, or production restart-safe publication. No policy gate is bypassed to enable files.
Run `node examples/sdk-runtime/files.cjs` after building `@librechat/api` for a key-free example.
It starts a separate worker process, runs a transform → publish → SDK reply graph, validates the
result digest, and reports bytes, publication count, message events, and loopback completion time.
Temporary filesystem storage and in-memory mutation receipts are fixtures; they are not a
production storage adapter or a latency-parity benchmark.

View file

@ -70,9 +70,9 @@ Its test attachment also records send-to-approval and approval-to-visible-output
This example validates the initial transport. It does **not** establish all main-chat features.
Read the [parity matrix and rollout gates](../../docs/sdk/agents.md#main-chat-parity-and-rollout-gates)
before enabling a product workflow. In particular, host model/PII protection blocks remote
execution, and model/tool builder settings, files/artifacts, steering, nested usage/billing, and
host tracing policies are not automatically inherited by the worker.
before enabling a product workflow. Protected execution requires the opt-in host model and policy
adapters. File transport is programmatic; native file/artifact activation, steering, nested
usage/billing, and host tracing policies are not automatically inherited by the worker.
## Recovering a dropped host-worker connection
@ -177,3 +177,18 @@ remain gated. Combining initial admission with explicit provider-text output pro
only with SDK 4.2.9 invocation-context support. Upgrade separately deployed workers to SDK 4.2.9
and this bridge version; older workers stay gated. See [the parity matrix](../../docs/sdk/agents.md#main-chat-parity-and-rollout-gates)
and [configuration](../../docs/sdk/agents.md#saved-agent-builder-models) before enabling it.
## File transport example
After building `@librechat/api`, run `node examples/sdk-runtime/files.cjs`. It launches its own
separate worker process and runs a custom graph that reads an authorized host file, streams an
uppercase transform into private staging, publishes it, and produces a normal SDK chat reply.
The script verifies the digest and single publication, reports elapsed loopback time and SDK
message events, then removes its temporary files. No model credentials are needed.
The example explicitly supplies `createRemoteSdkRun({ hostServices: { files } })` with an SDK
`createHostFileService` binding and authorized source descriptors. It does not activate files for
stock Console/chat callers. Its temporary filesystem and in-memory receipts are test fixtures;
production adapters still need native ACL/policy checks, durable retry reconciliation, attachment
events, previews, retention, and authorized browser downloads. See the
[host file transport contract](../../docs/sdk/agents.md#host-file-transport-sdk-4210).

View file

@ -0,0 +1,297 @@
/**
* Key-free, separate-process file transport demonstration. The temporary filesystem and
* in-memory receipts are fixtures, not LibreChat's production authorization/publication adapter.
*/
const { once } = require('node:events');
const { fork } = require('node:child_process');
const { tmpdir } = require('node:os');
const { join } = require('node:path');
const { mkdtemp, open, rename, rm, writeFile } = require('node:fs/promises');
const { createHash, randomUUID } = require('node:crypto');
const {
Annotation,
StateGraph,
START,
END,
messagesStateReducer,
} = require('@langchain/langgraph');
const { HumanMessage } = require('@librechat/agents/langchain/messages');
const {
Run,
Providers,
FakeChatModel,
GraphEvents,
createHostFileService,
HostFileAdmission,
HostFileServiceError,
} = require('@librechat/agents');
const { createRemoteSdkRun, createRemoteSdkServer } = require('@librechat/api/sdk');
const identity = {
runtimeId: 'file-example',
agentId: 'example',
userId: 'fixture-user',
runId: 'fixture-run',
conversationId: 'fixture-conversation',
};
const config = {
runId: identity.runId,
returnContent: true,
tokenCounter: () => 1,
graphConfig: {
type: 'standard',
agents: [
{
agentId: identity.agentId,
provider: Providers.OPENAI,
clientOptions: { model: 'fixture' },
tools: [],
},
],
},
};
async function createFileRun(input) {
const files = input.hostFiles;
if (!files?.sources.length) throw new Error('An authorized host file is required');
const run = await Run.create({ ...config, ...input.config });
run.Graph.overrideModel = new FakeChatModel({
responses: ['The transformed file has been published.'],
sleep: 1,
});
const agent = run.graphRunnable;
const State = Annotation.Root({
messages: Annotation({ reducer: messagesStateReducer, default: () => [] }),
artifact: Annotation({ reducer: (_previous, value) => value }),
runStepState: Annotation({ reducer: (_previous, value) => value }),
});
run.graphRunnable = new StateGraph(State)
.addNode('transform', async () => {
const source = files.sources[0];
// ASCII fixture: transformation preserves byte length. General encodings must supply
// the actual output length and stream bounded chunks through their own encoder.
const transformed = async function* () {
for await (const chunk of files.read(source, input.signal)) {
yield Buffer.from(Buffer.from(chunk).toString('ascii').toUpperCase(), 'ascii');
}
};
return {
artifact: await files.stage(
{
operationId: 'uppercase-upload',
filename: 'uppercase.txt',
mediaType: 'text/plain',
bytes: source.bytes,
},
transformed(),
input.signal,
),
};
})
.addNode('publish', async (state) => {
await files.publish(state.artifact, 'uppercase-publication', input.signal);
return {};
})
.addNode('reply', agent)
.addEdge(START, 'transform')
.addEdge('transform', 'publish')
.addEdge('publish', 'reply')
.addEdge('reply', END)
.compile(input.compileOptions);
return run;
}
async function worker() {
const server = createRemoteSdkServer({
runtimeId: identity.runtimeId,
secret: process.env.SDK_FILE_EXAMPLE_SECRET,
authorize: (who) => Object.entries(identity).every(([key, value]) => who[key] === value),
createRun: createFileRun,
});
server.server.listen(0, '127.0.0.1', () => process.send({ port: server.server.address().port }));
process.once('message', () => {
void server.close().then(() => process.disconnect());
});
}
async function main() {
const directory = await mkdtemp(join(tmpdir(), 'librechat-sdk-files-'));
const secret = randomUUID() + randomUUID();
const records = new Map();
const publications = new Map();
const bytes = Buffer.from('bounded host file transport\n'.repeat(4096));
const source = {
reference: 'input',
revision: 'immutable-1',
filename: 'input.txt',
mediaType: 'text/plain',
bytes: bytes.length,
};
const sourcePath = join(directory, 'input');
try {
await writeFile(sourcePath, bytes);
} catch (error) {
await rm(directory, { recursive: true, force: true });
throw error;
}
records.set(source.reference, { file: source, path: sourcePath });
function resolve(reference, revision) {
const record = records.get(reference);
if (!record) throw new HostFileServiceError('forbidden');
if (record.file.revision !== revision) throw new HostFileServiceError('conflict');
return record;
}
const store = {
read: async (request, signal) => {
signal?.throwIfAborted();
const record = resolve(request.reference, request.revision);
const handle = await open(record.path, 'r');
try {
const data = Buffer.alloc(request.length);
const { bytesRead } = await handle.read(data, 0, data.length, request.offset);
return {
reference: request.reference,
revision: request.revision,
offset: request.offset,
data: data.subarray(0, bytesRead),
};
} finally {
await handle.close();
}
},
stage: async (request, content, signal) => {
const path = join(directory, randomUUID());
const handle = await open(path, 'wx');
const hash = createHash('sha256');
let committed = false;
try {
for await (const chunk of content) {
signal?.throwIfAborted();
await handle.writeFile(chunk);
hash.update(chunk);
}
const sha256 = hash.digest('hex');
const file = {
reference: request.operationId,
revision: sha256,
filename: request.filename,
mediaType: request.mediaType,
bytes: request.bytes,
sha256,
};
const previous = records.get(request.operationId);
if (previous) {
if (previous.file.sha256 !== sha256) throw new HostFileServiceError('conflict');
return previous.file;
}
records.set(file.reference, { file, path });
committed = true;
return file;
} finally {
await handle.close();
if (!committed) await rm(path, { force: true });
}
},
publish: async (request, signal) => {
signal?.throwIfAborted();
const record = resolve(request.reference, request.revision);
const previous = publications.get(request.operationId);
if (previous) {
if (
previous.file.reference !== record.file.reference ||
previous.file.revision !== record.file.revision
)
throw new HostFileServiceError('conflict');
return previous;
}
const publishedPath = join(directory, 'published-' + randomUUID());
await rename(record.path, publishedPath);
record.path = publishedPath;
const receipt = { operationId: request.operationId, file: record.file };
publications.set(request.operationId, receipt);
return receipt;
},
};
const child = fork(__filename, ['--worker'], {
env: { ...process.env, SDK_FILE_EXAMPLE_SECRET: secret },
stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
});
try {
const [{ port }] = await Promise.race([
once(child, 'message'),
once(child, 'exit').then(() => {
throw new Error('Worker exited before listening');
}),
]);
const files = createHostFileService({
identity,
descriptor: {
version: 1,
operations: ['read', 'stage', 'publish'],
maxFileBytes: 1024 * 1024,
maxChunkBytes: 16 * 1024,
},
store,
admission: new HostFileAdmission({
maxConcurrentOperations: 4,
maxBufferedBytes: 128 * 1024,
}),
timeoutMs: 10000,
});
let events = 0;
const started = performance.now();
const run = await createRemoteSdkRun({
config: {
...config,
customHandlers: {
[GraphEvents.ON_MESSAGE_DELTA]: {
handle: () => {
events++;
},
},
},
},
identity,
remote: { url: `ws://127.0.0.1:${port}/sdk`, secret },
hostServices: { files: { ...files, sources: [source] } },
});
const content = await run.processStream(
{ messages: [new HumanMessage('Transform and publish the attachment')] },
{ version: 'v2', configurable: { thread_id: identity.conversationId } },
);
const expected = createHash('sha256')
.update(bytes.toString('ascii').toUpperCase())
.digest('hex');
if (
publications.size !== 1 ||
records.get('uppercase-upload')?.file.sha256 !== expected ||
!events
)
throw new Error('File graph acceptance failed');
console.log(
JSON.stringify(
{
bytes: bytes.length,
publications: publications.size,
messageEvents: events,
elapsedMs: Math.round(performance.now() - started),
content,
},
null,
2,
),
);
} finally {
if (child.connected) child.send('stop');
const timer = setTimeout(() => child.kill(), 5000);
if (child.exitCode === null) await once(child, 'exit');
clearTimeout(timer);
await rm(directory, { recursive: true, force: true });
}
}
if (process.argv.includes('--worker')) void worker().catch(() => process.exit(1));
else
void main().catch((error) => {
console.error(error);
process.exitCode = 1;
});

View file

@ -29,6 +29,7 @@ import { createHostToolService } from './hostTools';
import { createSnapshotReceiver } from './snapshot';
import { createHostPolicyChannel } from './policy';
import { createHostModelChannel } from './model';
import { createHostFileChannel } from './files';
import { createSdkPeer } from './peer';
/** Construct a real local Run whose execution is delegated to one operator-trusted runtime. */
@ -227,6 +228,7 @@ export async function createRemoteSdkRun({
snapshot = undefined;
let settled = false;
const hostInvocations = new Set<Promise<unknown>>();
let hostFileChannel: ReturnType<typeof createHostFileChannel> | undefined;
let hostModelChannel: ReturnType<typeof createHostModelChannel> | undefined;
const result = new Promise<RemoteSdkSnapshot>((resolve, reject) => {
const finish = (value?: RemoteSdkSnapshot) => {
@ -250,6 +252,15 @@ export async function createRemoteSdkRun({
signal: execution.signal,
})
: undefined;
hostFileChannel = hostServices?.files
? createHostFileChannel({
files: hostServices.files,
identity,
peer: { call: (...args) => peer.call(...args) },
limits,
signal: execution.signal,
})
: undefined;
let hostToolInvoke: ReturnType<typeof createHostToolService> | undefined;
const peer = createSdkPeer(socket, {
...limits,
@ -287,6 +298,16 @@ export async function createRemoteSdkRun({
onCall: async (method, data, _timeoutMs, signal) => {
if (execution.signal.aborted || options.signal?.aborted)
throw new Error('SDK runtime execution stopped');
if (method.startsWith('files.')) {
if (!hostFileChannel) throw new Error('Host files are unavailable');
const invocation = hostFileChannel.call(method, data, signal);
hostInvocations.add(invocation);
try {
return await invocation;
} finally {
hostInvocations.delete(invocation);
}
}
if (method === 'model.node.end') {
if (!modelAdmission || !hostServices?.modelLifecycle)
throw new Error('Model admission unavailable');
@ -436,6 +457,7 @@ export async function createRemoteSdkRun({
'agents' in config.graphConfig ? config.graphConfig.agents[0] : config.graphConfig;
const start: RemoteSdkStart = {
transportVersion: 2,
files: hostFileChannel?.descriptor,
modelAdmission: modelAdmission
? { version: 1, maxEntries: hostServices!.modelLifecycle!.maxEntries }
: undefined,
@ -483,6 +505,7 @@ export async function createRemoteSdkRun({
void (async () => {
const capabilities = (await peer.call('capabilities', null)) as {
transportVersion?: number;
hostFiles?: number;
hostTools?: number;
providerText?: number;
hostModel?: number;
@ -492,6 +515,8 @@ export async function createRemoteSdkRun({
};
if (capabilities?.transportVersion !== 2)
throw new Error('Worker transport capability unavailable');
if (hostFileChannel && capabilities?.hostFiles !== 1)
throw new Error('Worker host file capability unavailable');
if (modelAdmission && capabilities?.modelAdmission !== 1)
throw new Error('Worker model admission capability unavailable');
if (
@ -522,6 +547,7 @@ export async function createRemoteSdkRun({
hostServices?.modelLifecycle?.dispose();
providerText?.dispose();
hostModelChannel?.dispose();
hostFileChannel?.dispose();
// A failed/cancelled remote run may leave host cleanup running. Keep the host
// execution enrolled until those handlers drain, even if the wire has closed.
await Promise.allSettled([...hostInvocations]);

View file

@ -0,0 +1,559 @@
import { once } from 'node:events';
import { createHash } from 'node:crypto';
import WebSocket, { WebSocketServer } from 'ws';
import { HumanMessage } from '@librechat/agents/langchain/messages';
import { Run, Providers, FakeChatModel, GraphEvents } from '@librechat/agents';
import { Annotation, StateGraph, START, END, messagesStateReducer } from '@langchain/langgraph';
import { createHostFileService, HostFileAdmission, HostFileServiceError } from '@librechat/agents';
import type { HostFileDescriptor, HostFileStore } from '@librechat/agents';
import type { RunConfig, RunStepResumeState } from '@librechat/agents';
import type { AddressInfo } from 'node:net';
import { createHostFileChannel, createWorkerFileChannel } from './files';
import { createPolicyReceiver, createPolicySender } from './sealed';
import { createRemoteSdkServer } from './server';
import { createRemoteSdkRun } from './client';
import { remoteSdkLimits } from './types';
import { encodeSdkValue } from './wire';
import { createSdkPeer } from './peer';
const identity = {
runtimeId: 'runtime',
agentId: 'agent',
userId: 'user',
tenantId: 'tenant',
runId: 'run',
conversationId: 'conversation',
};
const descriptor = {
version: 1 as const,
operations: ['read', 'stage', 'publish'] as const,
maxFileBytes: 1024 * 1024,
maxChunkBytes: 4,
};
const source: HostFileDescriptor = {
reference: 'input',
revision: 'v1',
filename: 'input.txt',
mediaType: 'text/plain',
bytes: 8,
};
const bytes = Buffer.from('abcdefgh');
const digest = (value: Uint8Array) => createHash('sha256').update(value).digest('hex');
const limits = remoteSdkLimits({ rpcTimeoutMs: 1000, maxRunMs: 5000 });
const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 10));
async function collect(content: AsyncIterable<Uint8Array>) {
const chunks: Uint8Array[] = [];
for await (const chunk of content) chunks.push(chunk);
return Buffer.concat(chunks);
}
function storage() {
const records = new Map<string, { file: HostFileDescriptor; data: Uint8Array }>([
[source.reference, { file: source, data: bytes }],
]);
const publications = new Map<string, HostFileDescriptor>();
let allowed = true;
const resolve = (reference: string, revision: string) => {
const row = records.get(reference);
if (!allowed || !row) throw new HostFileServiceError('forbidden');
if (row.file.revision !== revision) throw new HostFileServiceError('conflict');
return row;
};
const store: HostFileStore = {
read: jest.fn(async (request) => ({
reference: request.reference,
revision: request.revision,
offset: request.offset,
data: resolve(request.reference, request.revision).data.subarray(
request.offset,
request.offset + request.length,
),
})),
stage: jest.fn(async (request, content) => {
const data = await collect(content);
const file = {
reference: request.operationId,
revision: digest(data),
filename: request.filename,
mediaType: request.mediaType,
bytes: data.length,
sha256: digest(data),
};
const previous = records.get(file.reference);
if (previous && previous.file.revision !== file.revision)
throw new HostFileServiceError('conflict');
records.set(file.reference, { file, data });
return file;
}),
publish: jest.fn(async (request) => {
const row = resolve(request.reference, request.revision);
const previous = publications.get(request.operationId);
if (previous && previous.reference !== row.file.reference)
throw new HostFileServiceError('conflict');
publications.set(request.operationId, row.file);
return { operationId: request.operationId, file: row.file };
}),
};
return {
store,
records,
publications,
revoke: () => {
allowed = false;
},
};
}
async function fixture(overrides: Partial<HostFileStore> = {}, workerIdentity = identity) {
const memory = storage();
Object.assign(memory.store, overrides);
const controller = new AbortController();
const admission = new HostFileAdmission({ maxConcurrentOperations: 4, maxBufferedBytes: 32 });
const files = createHostFileService({
identity,
descriptor,
store: memory.store,
admission,
timeoutMs: 1000,
signal: controller.signal,
});
const server = new WebSocketServer({ port: 0, host: '127.0.0.1' });
await once(server, 'listening');
const incoming = once(server, 'connection');
const socket = new WebSocket(`ws://127.0.0.1:${(server.address() as AddressInfo).port}`);
await once(socket, 'open');
const [hostSocket] = (await incoming) as [WebSocket];
const frames: string[] = [];
socket.on('message', (data) => frames.push(data.toString()));
hostSocket.on('message', (data) => frames.push(data.toString()));
const host = createHostFileChannel({
files: { ...files, sources: [source] },
identity,
limits,
signal: controller.signal,
peer: { call: (...args) => hostPeer.call(...args) },
});
const worker = createWorkerFileChannel({
limits,
signal: controller.signal,
peer: { call: (...args) => workerPeer.call(...args) },
});
const peerOptions = {
...limits,
timeoutMs: limits.rpcTimeoutMs,
onClose: () => controller.abort(),
onFrame: async () => {
throw new Error('Unexpected frame');
},
};
const hostPeer = createSdkPeer(hostSocket, {
...peerOptions,
onCall: (method, data, _timeout, signal) => host.call(method, data, signal),
});
const workerPeer = createSdkPeer(socket, {
...peerOptions,
onCall: (method, data, _timeout, signal) => {
if (method !== 'files.chunk') throw new Error('Unexpected method');
return worker.accept(data, signal);
},
});
return {
...memory,
host,
worker,
binding: worker.bind(workerIdentity, host.descriptor),
admission,
frames,
controller,
hostPeer,
workerPeer,
close: async () => {
controller.abort();
hostPeer.close();
workerPeer.close();
socket.terminate();
hostSocket.terminate();
host.dispose();
worker.dispose();
await new Promise<void>((resolve) => server.close(() => resolve()));
},
};
}
it('round trips bounded bytes, private staging, and publication on real WebSockets without plaintext payloads', async () => {
const f = await fixture();
try {
expect(f.binding.sources).toEqual([source]);
expect(await collect(f.binding.read(source))).toEqual(bytes);
const staged = await f.binding.stage(
{ operationId: 'upload', filename: 'report.txt', mediaType: 'text/plain', bytes: 8 },
(async function* () {
yield bytes.subarray(0, 4);
yield bytes.subarray(4);
})(),
);
expect(f.publications.size).toBe(0);
expect(staged.sha256).toBe(digest(bytes));
expect(await f.binding.publish(staged, 'publication')).toEqual({
operationId: 'publication',
file: staged,
});
expect(await f.binding.publish(staged, 'publication')).toEqual({
operationId: 'publication',
file: staged,
});
expect(f.publications.size).toBe(1);
expect(f.frames.join('')).not.toContain('abcd');
expect(f.frames.join('')).not.toContain(Buffer.from('abcd').toString('base64'));
expect(f.admission.snapshot()).toEqual({ operations: 0, reservedBytes: 0 });
} finally {
await f.close();
}
});
it('pulls reads on demand and rechecks canonical ACLs between ranges', async () => {
const f = await fixture();
try {
const stream = f.binding.read(source)[Symbol.asyncIterator]();
expect(f.store.read).not.toHaveBeenCalled();
expect((await stream.next()).value).toEqual(bytes.subarray(0, 4));
await tick();
expect(f.store.read).toHaveBeenCalledTimes(1);
f.revoke();
await expect(stream.next()).rejects.toMatchObject({ code: 'forbidden' });
} finally {
await f.close();
}
});
it.each(['runtimeId', 'agentId', 'runId', 'userId', 'tenantId', 'conversationId'] as const)(
'rejects a foreign %s before touching storage',
async (key) => {
const f = await fixture({}, { ...identity, [key]: 'foreign' });
try {
await expect(collect(f.binding.read(source))).rejects.toMatchObject({ code: 'forbidden' });
expect(f.store.read).not.toHaveBeenCalled();
} finally {
await f.close();
}
},
);
it('does not pull upload bytes before host storage asks for them', async () => {
let release!: () => void;
let entered!: () => void;
const ready = new Promise<void>((resolve) => {
entered = resolve;
});
const gate = new Promise<void>((resolve) => {
release = resolve;
});
const memory = storage();
const f = await fixture({
stage: async (...args) => {
entered();
await gate;
return memory.store.stage(...args);
},
});
const produced = jest.fn();
try {
const staging = f.binding.stage(
{ operationId: 'upload', filename: 'report', mediaType: 'text/plain', bytes: 8 },
(async function* () {
produced();
yield bytes.subarray(0, 4);
produced();
yield bytes.subarray(4);
})(),
);
await ready;
expect(produced).not.toHaveBeenCalled();
release();
await staging;
expect(produced).toHaveBeenCalledTimes(2);
} finally {
release();
await f.close();
}
});
it.each([3, 9])(
'rejects an upload whose declared length is %s and never publishes it',
async (length) => {
const f = await fixture();
try {
await expect(
f.binding.stage(
{ operationId: 'upload', filename: 'report', mediaType: 'text/plain', bytes: length },
(async function* () {
yield bytes.subarray(0, 4);
yield bytes.subarray(4);
})(),
),
).rejects.toMatchObject({ code: length < bytes.length ? 'overflow' : 'incompatible' });
expect(f.store.publish).not.toHaveBeenCalled();
expect(f.records.size).toBe(1);
} finally {
await f.close();
}
},
);
it('cancels a staged upload, runs source cleanup, and retains no publication', async () => {
let entered!: () => void;
const ready = new Promise<void>((resolve) => {
entered = resolve;
});
const cleaned = jest.fn();
const f = await fixture({
stage: async (_request, content, signal) => {
for await (const _chunk of content) {
entered();
await new Promise<void>((resolve) => {
signal?.addEventListener('abort', () => resolve(), { once: true });
});
signal?.throwIfAborted();
}
throw new Error('Unexpected EOF');
},
});
const cancel = new AbortController();
try {
const pending = f.binding.stage(
{ operationId: 'upload', filename: 'report', mediaType: 'text/plain', bytes: 8 },
(async function* () {
try {
yield bytes.subarray(0, 4);
yield bytes.subarray(4);
} finally {
cleaned();
}
})(),
cancel.signal,
);
await ready;
cancel.abort(new Error('private cancellation text'));
await expect(pending).rejects.toMatchObject({ code: 'cancelled' });
await tick();
expect(cleaned).toHaveBeenCalledTimes(1);
expect(f.admission.snapshot().operations).toBe(0);
expect(f.publications.size).toBe(0);
expect(f.frames.join('')).not.toContain('private cancellation text');
} finally {
await f.close();
}
});
it('redacts storage errors and rejects stale revisions', async () => {
const f = await fixture({
read: async () => {
throw new Error('/private/credentials secret');
},
});
try {
await expect(collect(f.binding.read(source))).rejects.toMatchObject({
code: 'unavailable',
message: 'Host file service: unavailable',
});
expect(f.frames.join('')).not.toContain('credentials');
} finally {
await f.close();
}
const other = await fixture();
try {
await expect(collect(other.binding.read({ ...source, revision: 'old' }))).rejects.toMatchObject(
{ code: 'conflict' },
);
} finally {
await other.close();
}
});
it('rejects oversized raw read requests before storage despite bypassing worker bindings', async () => {
const f = await fixture();
const receiver = createPolicyReceiver(limits.maxFrameBytes, 'files');
try {
const seal = createPolicySender(f.host.descriptor.publicKey, limits.maxFrameBytes, 'files');
const request = {
version: 1,
identity,
reference: source.reference,
revision: source.revision,
offset: 0,
length: 5,
};
const result = await f.workerPeer.call(
'files.read',
seal(
JSON.stringify(
encodeSdkValue({
id: '10101010-1010-4010-8010-101010101010',
publicKey: receiver.publicKey,
request,
}),
),
),
);
expect(result).toEqual({ version: 1, ok: false, code: 'overflow' });
expect(f.store.read).not.toHaveBeenCalled();
} finally {
receiver.dispose();
await f.close();
}
});
it('feeds file bindings into a custom graph and preserves native SDK message events', async () => {
const memory = storage();
const files = createHostFileService({
identity,
descriptor,
store: memory.store,
admission: new HostFileAdmission({ maxConcurrentOperations: 4, maxBufferedBytes: 32 }),
timeoutMs: 1000,
});
const secret = 'file-bridge-test-secret-at-least-32-characters';
const config: RunConfig = {
runId: identity.runId,
tokenCounter: () => 1,
returnContent: true,
graphConfig: {
type: 'standard',
agents: [
{
agentId: identity.agentId,
provider: Providers.OPENAI,
clientOptions: { model: 'test' },
tools: [],
},
],
},
};
const observed = jest.fn();
const runtime = createRemoteSdkServer({
runtimeId: identity.runtimeId,
secret,
authorize: (who) => who.userId === identity.userId,
createRun: async (input) => {
const hostFiles = input.hostFiles;
if (!hostFiles) throw new Error('Files not negotiated');
const run = await Run.create({ ...config, ...input.config });
if (!run.Graph) throw new Error('Missing graph');
run.Graph.overrideModel = new FakeChatModel({ responses: ['Artifact published'], sleep: 1 });
const agent = run.graphRunnable;
if (!agent) throw new Error('Missing compiled agent');
const state = Annotation.Root({
messages: Annotation({ reducer: messagesStateReducer, default: () => [] }),
runStepState: Annotation<RunStepResumeState | undefined>(),
});
run.graphRunnable = new StateGraph(state)
.addNode('artifact', async () => {
const staged = await hostFiles.stage(
{
operationId: 'graph-upload',
filename: 'report.txt',
mediaType: 'text/plain',
bytes: source.bytes,
},
hostFiles.read(hostFiles.sources[0], input.signal),
input.signal,
);
await hostFiles.publish(staged, 'graph-publication', input.signal);
return {};
})
.addNode('reply', (state, config) => agent.invoke(state, config))
.addEdge(START, 'artifact')
.addEdge('artifact', 'reply')
.addEdge('reply', END)
.compile();
return run;
},
});
await new Promise<void>((resolve) => runtime.server.listen(0, '127.0.0.1', resolve));
try {
const run = await createRemoteSdkRun({
config: {
...config,
customHandlers: { [GraphEvents.ON_MESSAGE_DELTA]: { handle: observed } },
},
identity,
remote: {
url: `ws://127.0.0.1:${(runtime.server.address() as AddressInfo).port}/sdk`,
secret,
},
hostServices: { files: { ...files, sources: [source] } },
});
const content = await run.processStream(
{ messages: [new HumanMessage('Publish the report')] },
{ version: 'v2', configurable: { thread_id: identity.conversationId } },
);
expect(memory.publications.size).toBe(1);
expect(JSON.stringify(content)).toContain('Artifact published');
expect(observed).toHaveBeenCalled();
} finally {
await runtime.close();
}
});
it('fails before execution when an older worker does not advertise file support', async () => {
const server = new WebSocketServer({ port: 0, host: '127.0.0.1' });
await once(server, 'listening');
const executed = jest.fn();
server.on('connection', (socket) => {
createSdkPeer(socket, {
...limits,
timeoutMs: limits.rpcTimeoutMs,
onClose: () => undefined,
onFrame: async () => undefined,
onCall: async (method) => {
if (method === 'capabilities') return { transportVersion: 2 };
executed();
return { accepted: true };
},
});
});
const memory = storage();
const files = createHostFileService({
identity,
descriptor,
store: memory.store,
admission: new HostFileAdmission({ maxConcurrentOperations: 4, maxBufferedBytes: 32 }),
timeoutMs: 1000,
});
try {
const run = await createRemoteSdkRun({
identity,
config: {
runId: identity.runId,
tokenCounter: () => 1,
graphConfig: {
type: 'standard',
agents: [
{
agentId: identity.agentId,
provider: Providers.OPENAI,
clientOptions: { model: 'test' },
tools: [],
},
],
},
},
remote: {
url: `ws://127.0.0.1:${(server.address() as AddressInfo).port}/sdk`,
secret: 'older-file-worker-test-secret-at-least-32-characters',
},
hostServices: { files: { ...files, sources: [source] } },
});
await expect(
run.processStream(
{ messages: [new HumanMessage('read')] },
{ version: 'v2', configurable: { thread_id: identity.conversationId } },
),
).rejects.toThrow('execution failed');
expect(executed).not.toHaveBeenCalled();
expect(memory.store.read).not.toHaveBeenCalled();
} finally {
for (const client of server.clients) client.terminate();
await new Promise<void>((resolve) => server.close(() => resolve()));
}
});

View file

@ -0,0 +1,388 @@
import { z } from 'zod';
import { randomUUID } from 'node:crypto';
import {
HostFileAdmission,
HostFileServiceError,
createHostFileBindings,
hostFileDescriptorSchema,
hostFileServiceDescriptorSchema,
hostFileReadRequestSchema,
hostFileStageRequestSchema,
hostFilePublishRequestSchema,
} from '@librechat/agents';
import type { HostFileService, HostFileDescriptor, HostFileErrorCode } from '@librechat/agents';
import type { RemoteSdkHostServices, RemoteSdkLimits, RemoteSdkStart } from './types';
import type { SdkAgentIdentity } from './identity';
import type { SdkRpc } from './peer';
import { createPolicyReceiver, createPolicySender } from './sealed';
import { encodeSdkValue, decodeSdkValue } from './wire';
export const fileChannelSchema = z
.object({
version: z.literal(1),
publicKey: z.string().length(60),
descriptor: hostFileServiceDescriptorSchema,
sources: z.array(hostFileDescriptorSchema),
})
.strict();
const envelopeSchema = z
.object({
id: z.string().uuid(),
publicKey: z.string().length(60),
request: z.unknown(),
})
.strict();
const chunkSchema = z
.object({
id: z.string().uuid(),
index: z.number().int().nonnegative(),
})
.strict();
const resultSchema = z.discriminatedUnion('ok', [
z.object({ version: z.literal(1), ok: z.literal(true), value: z.unknown() }).strict(),
z
.object({
version: z.literal(1),
ok: z.literal(false),
code: z.enum([
'incompatible',
'forbidden',
'conflict',
'overflow',
'cancelled',
'timeout',
'unavailable',
]),
})
.strict(),
]);
const bytesSchema = z.instanceof(Uint8Array);
const uploadSchema = z.discriminatedUnion('done', [
z.object({ done: z.literal(true) }).strict(),
z.object({ done: z.literal(false), data: bytesSchema }).strict(),
]);
function failure(error: unknown, signal?: AbortSignal) {
let code: HostFileErrorCode = 'unavailable';
if (error instanceof HostFileServiceError) code = error.code;
if (signal?.aborted) code = 'cancelled';
return { version: 1 as const, ok: false as const, code };
}
function parseRequest(method: string, request: unknown) {
if (method === 'files.read') return hostFileReadRequestSchema.parse(request);
if (method === 'files.stage') return hostFileStageRequestSchema.parse(request);
if (method === 'files.publish') return hostFilePublishRequestSchema.parse(request);
throw new HostFileServiceError('incompatible');
}
function reply(value: unknown): unknown {
const result = resultSchema.safeParse(value);
if (!result.success) throw new HostFileServiceError('incompatible');
if (!result.data.ok) throw new HostFileServiceError(result.data.code);
return result.data.value;
}
/** Leave room for two base64 encodings, metadata, encryption, and the RPC envelope. */
function chunkLimit(limits: RemoteSdkLimits): number {
const bytes = Math.floor((Math.min(limits.maxFrameBytes, limits.maxBufferedBytes) - 8192) / 4);
if (bytes < 1) throw new HostFileServiceError('overflow');
return bytes;
}
function sealValue(
seal: ReturnType<typeof createPolicySender>,
value: unknown,
limits: RemoteSdkLimits,
) {
const sealed = seal(JSON.stringify(encodeSdkValue(value)));
// RPC ids/methods are bounded by the peer. Include their envelope budget before sending.
if (
Buffer.byteLength(JSON.stringify(sealed)) + 256 >
Math.min(limits.maxFrameBytes, limits.maxBufferedBytes)
)
throw new HostFileServiceError('overflow');
return sealed;
}
/** File contents are sealed before they reach RPC queues or durable recovery journals. */
export function createHostFileChannel(options: {
files: NonNullable<RemoteSdkHostServices['files']>;
identity: Readonly<SdkAgentIdentity>;
peer: { call: SdkRpc };
limits: RemoteSdkLimits;
signal: AbortSignal;
}) {
const receiver = createPolicyReceiver(options.limits.maxFrameBytes, 'files');
const descriptor = {
...options.files.descriptor,
maxChunkBytes: Math.min(options.files.descriptor.maxChunkBytes, chunkLimit(options.limits)),
};
// Reuse SDK validation, including duplicate operations and inconsistent limits.
createHostFileBindings({
identity: options.identity,
descriptor,
service: options.files.service,
});
const sources = options.files.sources.map((file) => hostFileDescriptorSchema.parse(file));
const active = new Set<string>();
return {
descriptor: { version: 1 as const, publicKey: receiver.publicKey, descriptor, sources },
dispose: receiver.dispose,
call: async (method: string, data: unknown, invocationSignal?: AbortSignal) => {
const signal = invocationSignal
? AbortSignal.any([options.signal, invocationSignal])
: options.signal;
let id: string | undefined;
try {
signal.throwIfAborted();
const envelope = envelopeSchema.parse(decodeSdkValue(JSON.parse(receiver.open(data))));
if (active.has(envelope.id)) throw new HostFileServiceError('conflict');
id = envelope.id;
active.add(id);
const seal = createPolicySender(envelope.publicKey, options.limits.maxFrameBytes, 'files');
const request = parseRequest(method, envelope.request);
for (const key of [
'runtimeId',
'agentId',
'runId',
'userId',
'tenantId',
'conversationId',
] as const)
if (request.identity[key] !== options.identity[key])
throw new HostFileServiceError('forbidden');
let value: unknown;
if ('offset' in request) {
if (!descriptor.operations.includes('read')) throw new HostFileServiceError('forbidden');
if (request.length > descriptor.maxChunkBytes) throw new HostFileServiceError('overflow');
value = await options.files.service.read(request, signal);
} else if ('filename' in request) {
if (!descriptor.operations.includes('stage')) throw new HostFileServiceError('forbidden');
if (request.bytes > descriptor.maxFileBytes) throw new HostFileServiceError('overflow');
const content = async function* () {
for (let index = 0; ; index++) {
signal.throwIfAborted();
const packet = reply(
await options.peer.call(
'files.chunk',
sealValue(seal, { id: envelope.id, index }, options.limits),
options.limits.rpcTimeoutMs,
signal,
),
);
const received = z
.object({
id: z.literal(envelope.id),
index: z.literal(index),
chunk: uploadSchema,
})
.strict()
.parse(decodeSdkValue(JSON.parse(receiver.open(packet))));
const chunk = received.chunk;
if (chunk.done) return;
if (chunk.data.byteLength > descriptor.maxChunkBytes)
throw new HostFileServiceError('overflow');
yield chunk.data;
}
};
value = await options.files.service.stage(request, content(), signal);
} else {
if (!descriptor.operations.includes('publish'))
throw new HostFileServiceError('forbidden');
value = await options.files.service.publish(request, signal);
}
return {
version: 1 as const,
ok: true as const,
value: sealValue(seal, { id, value }, options.limits),
};
} catch (error) {
return failure(error, signal);
} finally {
if (id) active.delete(id);
}
},
};
}
/** Pull uploads one chunk at a time; no whole-file buffer and no speculative producer reads. */
export function createWorkerFileChannel(options: {
peer: { call: SdkRpc };
limits: RemoteSdkLimits;
signal: AbortSignal;
}) {
let receiver: ReturnType<typeof createPolicyReceiver> | undefined;
const uploads = new Map<
string,
{
iterator: AsyncIterator<Uint8Array>;
signal: AbortSignal;
index: number;
pulling: boolean;
}
>();
let bound = false;
let seal: ReturnType<typeof createPolicySender> | undefined;
let maxChunkBytes = 0;
return {
dispose: () => receiver?.dispose(),
accept: async (data: unknown, invocationSignal?: AbortSignal) => {
try {
if (!seal || !receiver) throw new HostFileServiceError('forbidden');
const chunk = chunkSchema.parse(decodeSdkValue(JSON.parse(receiver.open(data))));
const upload = uploads.get(chunk.id);
if (!upload || upload.pulling || upload.index !== chunk.index)
throw new HostFileServiceError('conflict');
upload.signal.throwIfAborted();
invocationSignal?.throwIfAborted();
upload.pulling = true;
try {
const next = await upload.iterator.next();
upload.signal.throwIfAborted();
invocationSignal?.throwIfAborted();
if (
!next.done &&
(!(next.value instanceof Uint8Array) || next.value.byteLength > maxChunkBytes)
)
throw new HostFileServiceError('overflow');
upload.index++;
return {
version: 1 as const,
ok: true as const,
value: sealValue(
seal,
{
id: chunk.id,
index: chunk.index,
chunk: next.done ? { done: true } : { done: false, data: next.value },
},
options.limits,
),
};
} finally {
upload.pulling = false;
}
} catch (error) {
return failure(error, options.signal);
}
},
bind: (identity: Readonly<SdkAgentIdentity>, input: NonNullable<RemoteSdkStart['files']>) => {
if (bound) throw new HostFileServiceError('conflict');
const channel = fileChannelSchema.parse(input);
if (channel.descriptor.maxChunkBytes > chunkLimit(options.limits))
throw new HostFileServiceError('overflow');
maxChunkBytes = channel.descriptor.maxChunkBytes;
seal = createPolicySender(channel.publicKey, options.limits.maxFrameBytes, 'files');
const recipient = createPolicyReceiver(options.limits.maxFrameBytes, 'files');
receiver = recipient;
bound = true;
const admission = new HostFileAdmission({
maxConcurrentOperations: Math.max(
1,
Math.floor(options.limits.maxBufferedBytes / (2 * maxChunkBytes)),
),
maxBufferedBytes: options.limits.maxBufferedBytes,
});
const invoke = async (
method: string,
request: unknown,
signal: AbortSignal,
id = randomUUID(),
) => {
signal.throwIfAborted();
const result = reply(
await options.peer.call(
method,
sealValue(
seal!,
{
id,
publicKey: recipient.publicKey,
request,
},
options.limits,
),
options.limits.maxRunMs,
signal,
),
);
const envelope = z
.object({ id: z.literal(id), value: z.unknown() })
.strict()
.parse(decodeSdkValue(JSON.parse(recipient.open(result))));
return envelope.value;
};
const bindSignal = (signal?: AbortSignal) =>
signal ? AbortSignal.any([options.signal, signal]) : options.signal;
const service: HostFileService = {
version: 1,
read: async (request, signal) => {
const release = admission.acquire(2 * maxChunkBytes);
try {
return z
.object({
reference: z.string(),
revision: z.string(),
offset: z.number(),
data: bytesSchema,
})
.strict()
.parse(await invoke('files.read', request, bindSignal(signal)));
} finally {
release();
}
},
stage: async (request, content, signal) => {
const release = admission.acquire(2 * maxChunkBytes);
const id = randomUUID();
let iterator: AsyncIterator<Uint8Array>;
try {
iterator = content[Symbol.asyncIterator]();
} catch (error) {
release();
throw error;
}
const boundSignal = bindSignal(signal);
uploads.set(id, { iterator, signal: boundSignal, index: 0, pulling: false });
try {
return hostFileDescriptorSchema.parse(
await invoke('files.stage', request, boundSignal, id),
);
} finally {
// A cancelled generator may still be cleaning up: keep its capacity charged.
void Promise.resolve()
.then(() => iterator.return?.())
.catch(() => undefined)
.finally(() => {
uploads.delete(id);
release();
});
}
},
publish: async (request, signal) => {
const release = admission.acquire(2 * maxChunkBytes);
try {
return z
.object({ operationId: z.string(), file: hostFileDescriptorSchema })
.strict()
.parse(await invoke('files.publish', request, bindSignal(signal)));
} finally {
release();
}
},
};
const bindings = createHostFileBindings({
identity,
descriptor: channel.descriptor,
service,
});
return {
...bindings,
sources: Object.freeze(
channel.sources.map((file): HostFileDescriptor => Object.freeze(file)),
),
};
},
};
}

View file

@ -1,8 +1,8 @@
import { z } from 'zod';
import jwt from 'jsonwebtoken';
import { randomUUID } from 'node:crypto';
import { createServer, connect } from 'node:net';
import { request as httpRequest } from 'node:http';
import { randomUUID, createHash } from 'node:crypto';
import { tool } from '@librechat/agents/langchain/tools';
import { setTimeout as delay } from 'node:timers/promises';
import { ChatGenerationChunk } from '@langchain/core/outputs';
@ -10,6 +10,8 @@ import { ensureHandler } from '@langchain/core/callbacks/manager';
import { FakeChatModel as TestModel } from '@langchain/core/utils/testing';
import { HumanMessage, AIMessageChunk } from '@librechat/agents/langchain/messages';
import {
createHostFileService,
HostFileAdmission,
createHostProviderTextService,
createHostModelService,
HostModelAdmission,
@ -21,7 +23,13 @@ import {
MemorySaver,
HookRegistry,
} from '@librechat/agents';
import type { RunConfig, ToolCallRequest, ToolExecuteBatchRequest } from '@librechat/agents';
import type {
RunConfig,
ToolCallRequest,
ToolExecuteBatchRequest,
HostFileStageRequest,
HostFilePublishRequest,
} from '@librechat/agents';
import type { AddressInfo, Socket } from 'node:net';
import type { RedisTestClient } from '../../../stream/__tests__/helpers/redis';
import type { RemoteSdkFactoryInput } from '../types';
@ -1147,3 +1155,103 @@ it.each(['input', 'output', 'combined'] as const)(
}
},
);
it('recovers file upload chunks and a committed publication receipt without repeating mutations', async () => {
const raw = Buffer.from('PRIVATE-FILE-CONTENT-FOR-RECOVERY');
const descriptor = {
reference: 'input',
revision: 'v1',
filename: 'input.txt',
mediaType: 'text/plain',
bytes: raw.length,
};
let produced = 0;
const runtime = await fixture(async (input) => {
const files = input.hostFiles;
if (!files) throw new Error('Missing file capability');
const content = async function* () {
for await (const chunk of files.read(files.sources[0], input.signal)) {
produced++;
yield chunk;
}
};
const staged = await files.stage(
{ operationId: 'upload', filename: 'output.txt', mediaType: 'text/plain', bytes: raw.length },
content(),
input.signal,
);
await files.publish(staged, 'publication', input.signal);
return factory(input);
});
const stage = jest.fn(
async (_request: HostFileStageRequest, content: AsyncIterable<Uint8Array>) => {
const chunks: Uint8Array[] = [];
for await (const chunk of content) {
chunks.push(chunk);
if (chunks.length === 1) {
runtime.drop();
await delay(60);
}
}
const data = Buffer.concat(chunks);
expect(data).toEqual(raw);
return {
...descriptor,
reference: 'staged',
sha256: createHash('sha256').update(data).digest('hex'),
};
},
);
const publish = jest.fn(async (request: HostFilePublishRequest) => {
const committed = {
operationId: request.operationId,
file: { ...descriptor, reference: 'published' },
};
runtime.drop();
await delay(60);
return committed;
});
const files = createHostFileService({
identity,
descriptor: {
version: 1,
operations: ['read', 'stage', 'publish'],
maxFileBytes: 1024,
maxChunkBytes: 8,
},
admission: new HostFileAdmission({ maxConcurrentOperations: 4, maxBufferedBytes: 64 }),
timeoutMs: 5000,
store: {
read: async (request) => ({
reference: request.reference,
revision: request.revision,
offset: request.offset,
data: raw.subarray(request.offset, request.offset + request.length),
}),
stage,
publish,
},
});
try {
const run = await createRemoteSdkRun({
config: hostConfig(async () => undefined),
identity,
remote: runtime.remote,
hostServices: { files: { ...files, sources: [descriptor] } },
});
await run.processStream(
{ messages: [new HumanMessage('copy')] },
{ version: 'v2', configurable: { thread_id: identity.conversationId } },
);
expect(stage).toHaveBeenCalledTimes(1);
expect(publish).toHaveBeenCalledTimes(1);
expect(produced).toBe(Math.ceil(raw.length / 8));
expect(runtime.createRun).toHaveBeenCalledTimes(1);
expect(runtime.connections()).toBeGreaterThan(1);
expect(runtime.errors).toEqual([]);
expect(runtime.journalEntries.join('')).not.toContain('PRIVATE-FILE');
expect(runtime.journalEntries.join('')).not.toContain(raw.subarray(0, 8).toString('base64'));
} finally {
await runtime.close();
}
});

View file

@ -10,7 +10,7 @@ import {
} from 'node:crypto';
import type { KeyObject } from 'node:crypto';
type Purpose = 'provider-text' | 'model';
type Purpose = 'provider-text' | 'model' | 'files';
const base64 = z.string().regex(/^[A-Za-z0-9+/]*={0,2}$/);
const publicKeySchema = base64.length(60);
const envelopeSchema = z

View file

@ -23,6 +23,7 @@ import type { SdkAgentIdentity } from './identity';
import { createWorkerModelLifecycle, supportsModelInvocationContext } from './admission';
import { policyDescriptorSchema, createWorkerProviderTextPolicy } from './policy';
import { createRuntimeRecovery, recoveryClaimSchema } from './recovery/server';
import { createWorkerFileChannel, fileChannelSchema } from './files';
import { remoteSdkLimits, isRemoteSdkSecret } from './types';
import { RECOVERY_HEADER_BYTES } from './recovery/socket';
import { createWorkerToolService } from './hostTools';
@ -52,6 +53,7 @@ const claimSchema = z.object({
});
const startSchema = z.object({
transportVersion: z.literal(2),
files: fileChannelSchema.optional(),
modelAdmission: z
.object({ version: z.literal(1), maxEntries: z.number().int().min(16).max(65536) })
.strict()
@ -268,6 +270,7 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
timer.unref();
const cleanup = () => {
controller.abort();
workerFiles.dispose();
clearTimeout(timer);
if (!running) active.delete(controller);
};
@ -276,6 +279,11 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
call: (method, data, _timeoutMs, signal) =>
peer.call(method, data, method === 'tools' ? limits.maxRunMs : undefined, signal),
});
const workerFiles = createWorkerFileChannel({
peer: { call: (...args) => peer.call(...args) },
limits,
signal: controller.signal,
});
const workerModel = createWorkerModelChannel({
peer: { call: (...args) => peer.call(...args) },
limits,
@ -294,12 +302,14 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
return {
transportVersion: 2,
hostTools: 2,
hostFiles: 1,
providerText: 1,
hostModel: 1,
builderModel: 1,
modelAdmission: 1,
...(supportsModelInvocationContext && { modelAdmissionWithProviderText: 1 }),
};
if (method === 'files.chunk') return workerFiles.accept(data, signal);
if (method === 'model.chunk') return workerModel.accept(data, signal);
if (method === 'tool.result') return workerTools.accept(data);
if (method === 'tool.session') return workerTools.accept(data, 'session');
@ -370,6 +380,7 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
],
});
}
const hostFiles = request.files ? workerFiles.bind(identity, request.files) : undefined;
const hostTools = request.hostTools?.length
? createHostToolBindings({
identity,
@ -412,6 +423,7 @@ export function createRemoteSdkServer(options: RemoteSdkServerOptions): {
const run = await options.createRun({
identity,
hostTools,
hostFiles,
hostModel,
config: {
runId: identity.runId,

View file

@ -1,5 +1,9 @@
import type {
AgentInputs,
createHostFileService,
HostFileBindings,
HostFileDescriptor,
HostFileServiceDescriptor,
createHostProviderTextService,
createHostModelService,
HostModelDescriptor,
@ -69,6 +73,8 @@ export interface RemoteSdkModelProfile {
/** Explicit host-owned capabilities; never reconstructed from worker claims or YAML. */
export interface RemoteSdkHostServices {
/** Already authorized host binding; storage credentials and policy stay with the host. */
files?: ReturnType<typeof createHostFileService> & { sources: readonly HostFileDescriptor[] };
modelLifecycle?: HostModelLifecycle;
modelProfile?: RemoteSdkModelProfile;
model?: ReturnType<typeof createHostModelService>;
@ -77,6 +83,12 @@ export interface RemoteSdkHostServices {
export interface RemoteSdkStart {
transportVersion: 2;
files?: {
version: 1;
publicKey: string;
descriptor: HostFileServiceDescriptor;
sources: HostFileDescriptor[];
};
modelAdmission?: { version: 1; maxEntries: number };
model?: { version: 1; publicKey: string; descriptor: HostModelDescriptor };
providerText?: { version: 1; publicKey: string; limits: HostProviderTextDescriptor };
@ -113,6 +125,7 @@ export interface RemoteSdkSnapshot {
runSteps?: ReturnType<NonNullable<SdkRun['Graph']>['createRunStepResumeState']>;
}
export interface RemoteSdkFactoryInput {
hostFiles?: HostFileBindings & { readonly sources: readonly HostFileDescriptor[] };
/** Retain this model as Graph.overrideModel when supplied by the authenticated host. */
hostModel?: ReturnType<HostChatModel['bindTools']>;
hostTools?: HostToolBindings;