diff --git a/docs/sdk/agents.md b/docs/sdk/agents.md index 7bb4eb57fd..555de327ec 100644 --- a/docs/sdk/agents.md +++ b/docs/sdk/agents.md @@ -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. diff --git a/examples/sdk-runtime/README.md b/examples/sdk-runtime/README.md index 0f1491f98d..936ef89271 100644 --- a/examples/sdk-runtime/README.md +++ b/examples/sdk-runtime/README.md @@ -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). diff --git a/examples/sdk-runtime/files.cjs b/examples/sdk-runtime/files.cjs new file mode 100644 index 0000000000..3e6f4e90a9 --- /dev/null +++ b/examples/sdk-runtime/files.cjs @@ -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; + }); diff --git a/packages/api/src/agents/remoteSdk/client.ts b/packages/api/src/agents/remoteSdk/client.ts index 95db8e0790..4fb24822b5 100644 --- a/packages/api/src/agents/remoteSdk/client.ts +++ b/packages/api/src/agents/remoteSdk/client.ts @@ -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>(); + let hostFileChannel: ReturnType | undefined; let hostModelChannel: ReturnType | undefined; const result = new Promise((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 | 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]); diff --git a/packages/api/src/agents/remoteSdk/files.spec.ts b/packages/api/src/agents/remoteSdk/files.spec.ts new file mode 100644 index 0000000000..73db0971ee --- /dev/null +++ b/packages/api/src/agents/remoteSdk/files.spec.ts @@ -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((resolve) => setTimeout(resolve, 10)); +async function collect(content: AsyncIterable) { + const chunks: Uint8Array[] = []; + for await (const chunk of content) chunks.push(chunk); + return Buffer.concat(chunks); +} + +function storage() { + const records = new Map([ + [source.reference, { file: source, data: bytes }], + ]); + const publications = new Map(); + 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 = {}, 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((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((resolve) => { + entered = resolve; + }); + const gate = new Promise((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((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((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(), + }); + 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((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((resolve) => server.close(() => resolve())); + } +}); diff --git a/packages/api/src/agents/remoteSdk/files.ts b/packages/api/src/agents/remoteSdk/files.ts new file mode 100644 index 0000000000..864f123372 --- /dev/null +++ b/packages/api/src/agents/remoteSdk/files.ts @@ -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, + 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; + identity: Readonly; + 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(); + 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 | undefined; + const uploads = new Map< + string, + { + iterator: AsyncIterator; + signal: AbortSignal; + index: number; + pulling: boolean; + } + >(); + let bound = false; + let seal: ReturnType | 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, input: NonNullable) => { + 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; + 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)), + ), + }; + }, + }; +} diff --git a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts index d5049ae662..0dc2f2ae47 100644 --- a/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts +++ b/packages/api/src/agents/remoteSdk/recovery/runtime.cache_integration.spec.ts @@ -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) => { + 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(); + } +}); diff --git a/packages/api/src/agents/remoteSdk/sealed.ts b/packages/api/src/agents/remoteSdk/sealed.ts index d79204529e..c99155da74 100644 --- a/packages/api/src/agents/remoteSdk/sealed.ts +++ b/packages/api/src/agents/remoteSdk/sealed.ts @@ -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 diff --git a/packages/api/src/agents/remoteSdk/server.ts b/packages/api/src/agents/remoteSdk/server.ts index 98b92e25c5..43aa803f51 100644 --- a/packages/api/src/agents/remoteSdk/server.ts +++ b/packages/api/src/agents/remoteSdk/server.ts @@ -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, diff --git a/packages/api/src/agents/remoteSdk/types.ts b/packages/api/src/agents/remoteSdk/types.ts index 21be3d8bf8..3788abf833 100644 --- a/packages/api/src/agents/remoteSdk/types.ts +++ b/packages/api/src/agents/remoteSdk/types.ts @@ -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 & { sources: readonly HostFileDescriptor[] }; modelLifecycle?: HostModelLifecycle; modelProfile?: RemoteSdkModelProfile; model?: ReturnType; @@ -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['createRunStepResumeState']>; } export interface RemoteSdkFactoryInput { + hostFiles?: HostFileBindings & { readonly sources: readonly HostFileDescriptor[] }; /** Retain this model as Graph.overrideModel when supplied by the authenticated host. */ hostModel?: ReturnType; hostTools?: HostToolBindings;