@myagentroam/node 0.9.68 → 0.9.70

package/dist/capabilities.js

@@ -11,10 +11,11 @@ const runtimeCredentialCapability = () => ({
     httpVersions: ['1.1', '2']
 });
 const workspaceDirectTransferCapability = () => ({
-    apiVersion: 1,
-    probe: true,
+    apiVersion: 2,
+    transport: true,
     upload: true,
     download: true,
+    range: true,
     gitCommitBlob: true,
     maxChunkBytes: 256 * 1024
 });

package/dist/connector.js

@@ -1,5 +1,5 @@
 import { dirname, resolve } from 'node:path';
-import { createEnvelope } from '@myagentroam/protocol';
+import { createEnvelope, directNodeCommandSchema } from '@myagentroam/protocol';
 import { hostedConversationStorePath, loadNodeConfig, directTransferUdpPortRange, nodeDataDirectory, nodeDatabasePath } from './config.js';
 import { NodeMetrics, nodeLog } from './operational.js';
 import { assertLocalSqlitePath } from './storage.js';
@@ -1075,36 +1075,6 @@ export class NodeConnector {
                     void this.terminalManager.shutdown();
             }
         });
-        this.directTransferService = new DirectTransferService({
-            nodeGeneration: () => this.nodeGeneration,
-            send: (type, payload) => this.send(type, payload),
-            udpPortRange: () => directTransferUdpPortRange(this.config),
-            openUpload: async (descriptor) => {
-                if (descriptor.resource.kind !== 'WORKSPACE_FILE')
-                    throw new Error('DIRECT_RESOURCE_UNSUPPORTED');
-                const workspace = this.workspaceCoordinator.require(descriptor.resource.workspaceId);
-                const upload = await this.workspaceUploadService.createDirect(workspace, {
-                    path: descriptor.resource.path,
-                    size: descriptor.size,
-                    sha256: descriptor.sha256,
-                    overwrite: descriptor.overwrite === true,
-                    ...(descriptor.composerAttachment === undefined
-                        ? {}
-                        : { composerAttachment: descriptor.composerAttachment })
-                });
-                return {
-                    offset: upload.receivedBytes,
-                    write: (bytes) => this.workspaceUploadService.writeDirect(upload.uploadId, bytes),
-                    complete: (size, sha256) => this.workspaceUploadService.completeDirect(upload.uploadId, size, sha256),
-                    cancel: () => this.workspaceUploadService.cancel(upload.uploadId)
-                };
-            },
-            openDownload: async (descriptor) => {
-                if (this.workspaceWorkbenchService === undefined)
-                    throw new Error('DIRECT_RESOURCE_UNAVAILABLE');
-                return this.workspaceWorkbenchService.directDownload(descriptor);
-            }
-        });
         this.controlMessages = new NodeControlMessageService({
             config: () => this.config,
             register: (nodeId, credential) => this.connectionLifecycle.register(nodeId, credential),
@@ -1113,12 +1083,7 @@ export class NodeConnector {
             inspectWorkspace: (envelope) => this.workspaceCoordinator.inspect(envelope),
             handleNodeRequest: (envelope) => this.nodeRequests.handle(envelope),
             handleRuntimeCredentialResponse: (envelope) => this.runtimeCredentials.handle(envelope),
-            handleDirectTransfer: (envelope) => this.directTransferService.handle({
-                type: envelope.type,
-                ...(typeof envelope.payload === 'object' && envelope.payload !== null
-                    ? envelope.payload
-                    : {})
-            }),
+            handleDirectTransfer: (envelope) => this.handleDirectTransfer(envelope),
             reconcileRuns: (envelope) => this.runEventBridge.reconcile(envelope),
             runners: this.runners,
             deliverSessionChannelMessage: (envelope) => this.runnerChannelMessages.handle(envelope),
@@ -1419,9 +1384,72 @@ export class NodeConnector {
         this.database ??= new NodeDatabase(nodeDatabasePath(this.config, this.configPath), () => this.config?.nodeId ?? 'unregistered');
         this.database.closeRunningTerminalSessions();
         await this.initializeConversationHosting();
+        this.directTransferService ??= this.createDirectTransferService();
         this.connectionLifecycle.start();
         this.controlChannel.connect();
     }
+    createDirectTransferService() {
+        try {
+            return new DirectTransferService({
+                nodeGeneration: () => this.nodeGeneration,
+                send: (type, payload) => this.send(type, payload),
+                udpPortRange: () => directTransferUdpPortRange(this.config),
+                openUpload: async (descriptor) => {
+                    if (descriptor.direction !== 'UPLOAD' || descriptor.resource.kind !== 'WORKSPACE_FILE')
+                        throw new Error('DIRECT_RESOURCE_UNSUPPORTED');
+                    const workspace = this.workspaceCoordinator.require(descriptor.resource.workspaceId);
+                    const upload = await this.workspaceUploadService.createDirect(workspace, {
+                        path: descriptor.resource.path,
+                        size: descriptor.size,
+                        sha256: descriptor.sha256,
+                        overwrite: descriptor.overwrite === true,
+                        ...(descriptor.composerAttachment === undefined
+                            ? {}
+                            : { composerAttachment: descriptor.composerAttachment })
+                    });
+                    return {
+                        offset: upload.receivedBytes,
+                        write: (bytes) => this.workspaceUploadService.writeDirect(upload.uploadId, bytes),
+                        complete: (size, sha256) => this.workspaceUploadService.completeDirect(upload.uploadId, size, sha256),
+                        cancel: () => this.workspaceUploadService.cancel(upload.uploadId)
+                    };
+                },
+                openDownload: async (descriptor) => {
+                    if (this.workspaceWorkbenchService === undefined)
+                        throw new Error('DIRECT_RESOURCE_UNAVAILABLE');
+                    return this.workspaceWorkbenchService.directDownload(descriptor);
+                }
+            });
+        }
+        catch (error) {
+            if (!(error instanceof Error) || error.message !== 'DIRECT_UDP_PORT_UNAVAILABLE')
+                throw error;
+            const range = directTransferUdpPortRange(this.config);
+            nodeLog('direct-transfer.udp-unavailable', {
+                portRangeBegin: range.begin,
+                portRangeEnd: range.end
+            });
+            return undefined;
+        }
+    }
+    handleDirectTransfer(envelope) {
+        const command = {
+            type: envelope.type,
+            ...(typeof envelope.payload === 'object' && envelope.payload !== null ? envelope.payload : {})
+        };
+        if (this.directTransferService !== undefined)
+            return this.directTransferService.handle(command);
+        const parsed = directNodeCommandSchema.safeParse(command);
+        if (!parsed.success)
+            return false;
+        this.send('direct.error', {
+            type: 'direct.error',
+            directSessionId: parsed.data.directSessionId,
+            code: 'DIRECT_UDP_PORT_UNAVAILABLE',
+            message: 'The configured direct-transfer UDP port range is unavailable.'
+        });
+        return true;
+    }
     clearMissionRetry(sessionId) {
         const retry = this.missionRetryTimers.get(sessionId);
         if (retry !== undefined)
@@ -1600,7 +1628,8 @@ export class NodeConnector {
         const terminalDrain = this.terminalManager.shutdown();
         this.terminalChannel.stop();
         this.runtimeCredentials.close();
-        this.directTransferService.close();
+        this.directTransferService?.dispose();
+        this.directTransferService = undefined;
         this.controlChannel.stop();
         const database = this.database;
         this.database = undefined;

package/dist/service/direct-transfer-service.js

@@ -1,31 +1,40 @@
 import { directDataControlFrameSchema, directNodeCommandSchema } from '@myagentroam/protocol';
+import { IceUdpMuxListener as NativeIceUdpMuxListener } from 'node-datachannel';
 import { RTCPeerConnection } from 'node-datachannel/polyfill';
 const MAX_HOST_CANDIDATES = 32;
-const MAX_ACTIVE_SESSIONS = 32;
+const MAX_ACTIVE_TRANSPORTS = 128;
+const MAX_ACTIVE_TRANSFERS = 128;
 const DATA_CHANNEL_HIGH_WATER_BYTES = 4 * 1024 * 1024;
 const DATA_CHANNEL_LOW_WATER_BYTES = 1024 * 1024;
 const LEASE_GRACE_MS = 30_000;
 const LEASE_CHECK_MS = 5_000;
 export class DirectTransferService {
     options;
-    sessions = new Map();
+    transports = new Map();
+    transfers = new Map();
     now;
     createPeerConnection;
+    iceUdpMuxListener;
+    peerConfiguration;
     leaseGraceMs;
     leaseCheckMs;
+    disposed = false;
     constructor(options) {
         this.options = options;
         this.now = options.now ?? Date.now;
+        const range = options.udpPortRange?.() ?? { begin: 49_152, end: 49_215 };
+        const createIceUdpMuxListener = options.createIceUdpMuxListener ?? ((port) => new NativeIceUdpMuxListener(port));
+        this.iceUdpMuxListener = bindIceUdpMuxListener(range, createIceUdpMuxListener);
+        const udpPort = this.iceUdpMuxListener.port();
+        this.peerConfiguration = {
+            iceServers: [],
+            enableIceUdpMux: true,
+            portRangeBegin: udpPort,
+            portRangeEnd: udpPort
+        };
         this.createPeerConnection =
             options.createPeerConnection ??
-                (() => {
-                    const range = options.udpPortRange?.() ?? { begin: 49_152, end: 49_215 };
-                    return new RTCPeerConnection({
-                        iceServers: [],
-                        portRangeBegin: range.begin,
-                        portRangeEnd: range.end
-                    });
-                });
+                ((configuration) => new RTCPeerConnection(configuration));
         this.leaseGraceMs = options.leaseGraceMs ?? LEASE_GRACE_MS;
         this.leaseCheckMs = options.leaseCheckMs ?? LEASE_CHECK_MS;
     }
@@ -46,56 +55,85 @@ export class DirectTransferService {
         return true;
     }
     close() {
-        for (const session of [...this.sessions.values()])
-            void this.remove(session, 'DIRECT_NODE_STOPPED');
+        for (const transfer of [...this.transfers.values()])
+            void this.removeTransfer(transfer, 'DIRECT_NODE_STOPPED');
+        for (const transport of [...this.transports.values()])
+            this.removeTransport(transport, 'DIRECT_NODE_STOPPED');
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.close();
+        this.iceUdpMuxListener.stop();
     }
     async dispatch(command) {
         if (command.type === 'direct.prepare') {
-            this.prepare(command);
+            if (command.purpose === 'TRANSPORT')
+                this.prepareTransport(command);
+            else
+                this.prepareTransfer(command);
             return;
         }
-        const session = this.sessions.get(command.directSessionId);
-        if (session === undefined)
-            throw new Error('DIRECT_SESSION_INVALID');
         if (command.type === 'direct.signal') {
-            await this.signal(session, command.signal);
+            const transport = this.transports.get(command.directSessionId);
+            if (transport === undefined)
+                throw new Error('DIRECT_TRANSFER_SESSION_NOT_FOUND');
+            await this.signal(transport, command.signal);
             return;
         }
         if (command.type === 'direct.grant') {
-            if (command.browserFingerprint !== fingerprint(session.peer.remoteDescription?.sdp) ||
-                command.nodeFingerprint !== fingerprint(session.peer.localDescription?.sdp) ||
+            const transfer = this.transfers.get(command.directSessionId);
+            const transport = this.transports.get(command.transportSessionId);
+            if (transfer === undefined ||
+                transport === undefined ||
+                transfer.command.transportSessionId !== command.transportSessionId ||
+                command.browserFingerprint !== fingerprint(transport.peer.remoteDescription?.sdp) ||
+                command.nodeFingerprint !== fingerprint(transport.peer.localDescription?.sdp) ||
                 command.openExpiresAt <= this.now() ||
-                command.expiresAt > session.command.expiresAt)
-                throw new Error('DIRECT_GRANT_INVALID');
-            session.grant = command;
+                command.expiresAt > transfer.command.expiresAt)
+                throw new Error('DIRECT_TRANSFER_GRANT_INVALID');
+            transfer.grant = command;
             return;
         }
-        if (command.type === 'direct.heartbeat') {
-            if (session.command.expiresAt <= this.now())
-                await this.remove(session, 'DIRECT_SESSION_EXPIRED');
-            else
-                session.lastLeaseAliveAt = this.now();
+        const transport = this.transports.get(command.directSessionId);
+        if (transport !== undefined) {
+            if (command.type === 'direct.heartbeat') {
+                transport.lastLeaseAliveAt = this.now();
+                transport.leaseExpiresAt = command.expiresAt;
+                return;
+            }
+            this.removeTransport(transport, command.code);
             return;
         }
-        await this.remove(session, command.code);
+        const transfer = this.transfers.get(command.directSessionId);
+        if (transfer === undefined)
+            throw new Error('DIRECT_TRANSFER_SESSION_NOT_FOUND');
+        if (command.type === 'direct.heartbeat') {
+            transfer.lastLeaseAliveAt = this.now();
+            transfer.leaseExpiresAt = command.expiresAt;
+        }
+        else
+            await this.removeTransfer(transfer, command.code);
     }
-    prepare(command) {
+    prepareTransport(command) {
         if (command.nodeGeneration !== this.options.nodeGeneration())
             throw new Error('DIRECT_NODE_GENERATION_MISMATCH');
-        if (this.sessions.has(command.directSessionId))
-            throw new Error('DIRECT_SESSION_CONFLICT');
-        if (this.sessions.size >= MAX_ACTIVE_SESSIONS)
+        if (this.transports.has(command.directSessionId) || this.transfers.has(command.directSessionId))
+            throw new Error('DIRECT_TRANSFER_SESSION_CONFLICT');
+        if (this.transports.size >= MAX_ACTIVE_TRANSPORTS)
             throw new Error('DIRECT_SESSION_LIMIT_REACHED');
-        const peer = this.createPeerConnection();
-        const session = {
+        const peer = this.createPeerConnection(this.peerConfiguration);
+        const transport = {
             command,
             peer,
-            opened: false,
-            uploadCommitted: false,
-            processing: Promise.resolve(),
-            sentCandidateKeys: new Set()
+            sentCandidateKeys: new Set(),
+            lastLeaseAliveAt: this.now(),
+            leaseExpiresAt: command.expiresAt,
+            leaseTimer: undefined
         };
-        this.sessions.set(command.directSessionId, session);
+        transport.leaseTimer = this.startLeaseWatch(() => transport.leaseExpiresAt, () => transport.lastLeaseAliveAt, () => this.removeTransport(transport, 'DIRECT_TRANSFER_CONTROL_UNAVAILABLE'));
+        this.transports.set(command.directSessionId, transport);
         peer.onicecandidate = (event) => {
             const candidate = event.candidate;
             if (candidate === null) {
@@ -108,7 +146,7 @@ export class DirectTransferService {
             }
             const json = candidate.toJSON();
             if (typeof json.candidate !== 'string' ||
-                !acceptHostCandidate(json.candidate, session.sentCandidateKeys))
+                !acceptHostCandidate(json.candidate, transport.sentCandidateKeys))
                 return;
             this.emit(command.directSessionId, {
                 type: 'direct.signal',
@@ -123,178 +161,198 @@ export class DirectTransferService {
                 }
             });
         };
-        peer.ondatachannel = (event) => this.attachChannel(session, event.channel);
+        peer.ondatachannel = (event) => this.attachPendingChannel(transport, event.channel);
         peer.onconnectionstatechange = () => {
             if (peer.connectionState === 'connected')
-                this.emit(session.command.directSessionId, {
+                this.emit(command.directSessionId, {
                     type: 'direct.connected',
-                    directSessionId: session.command.directSessionId
+                    directSessionId: command.directSessionId
                 });
             if (peer.connectionState === 'failed' || peer.connectionState === 'closed')
-                void this.remove(session, 'DIRECT_CONNECTION_FAILED');
+                this.removeTransport(transport, 'DIRECT_CONNECTION_FAILED');
         };
     }
-    async signal(session, signal) {
+    prepareTransfer(command) {
+        if (command.nodeGeneration !== this.options.nodeGeneration())
+            throw new Error('DIRECT_NODE_GENERATION_MISMATCH');
+        if (this.transfers.has(command.directSessionId) || this.transports.has(command.directSessionId))
+            throw new Error('DIRECT_TRANSFER_SESSION_CONFLICT');
+        const transport = this.transports.get(command.transportSessionId);
+        if (transport === undefined ||
+            transport.command.workbenchConnectionId !== command.workbenchConnectionId ||
+            transport.command.nodeGeneration !== command.nodeGeneration ||
+            transport.peer.connectionState !== 'connected')
+            throw new Error('DIRECT_TRANSFER_UNAVAILABLE');
+        if (this.transfers.size >= MAX_ACTIVE_TRANSFERS)
+            throw new Error('DIRECT_SESSION_LIMIT_REACHED');
+        const transfer = {
+            command,
+            uploadCommitted: false,
+            opened: false,
+            processing: Promise.resolve(),
+            lastLeaseAliveAt: this.now(),
+            leaseExpiresAt: command.expiresAt,
+            leaseTimer: undefined
+        };
+        transfer.leaseTimer = this.startLeaseWatch(() => transfer.leaseExpiresAt, () => transfer.lastLeaseAliveAt, () => void this.removeTransfer(transfer, 'DIRECT_TRANSFER_CONTROL_UNAVAILABLE'));
+        this.transfers.set(command.directSessionId, transfer);
+    }
+    async signal(transport, signal) {
         if (signal.kind === 'CANDIDATE') {
             if (!safeHostCandidate(signal.candidate.candidate))
-                throw new Error('DIRECT_CANDIDATE_REJECTED');
-            await session.peer.addIceCandidate(signal.candidate);
+                throw new Error('DIRECT_TRANSFER_CANDIDATE_REJECTED');
+            await transport.peer.addIceCandidate(signal.candidate);
             return;
         }
         if (signal.kind === 'END_OF_CANDIDATES') {
-            await session.peer.addIceCandidate(null);
+            await transport.peer.addIceCandidate(null);
             return;
         }
         if (!hostOnlySdp(signal.sdp))
-            throw new Error('DIRECT_CANDIDATE_REJECTED');
-        await session.peer.setRemoteDescription({
+            throw new Error('DIRECT_TRANSFER_CANDIDATE_REJECTED');
+        await transport.peer.setRemoteDescription({
             type: signal.kind === 'OFFER' ? 'offer' : 'answer',
             sdp: signal.sdp
         });
         if (signal.kind !== 'OFFER')
             return;
-        const answer = await session.peer.createAnswer();
-        await session.peer.setLocalDescription(answer);
-        const localSdp = session.peer.localDescription?.sdp;
-        const filtered = filterIceCandidates(localSdp, session.sentCandidateKeys);
-        const sdp = filtered.sdp;
+        const answer = await transport.peer.createAnswer();
+        await transport.peer.setLocalDescription(answer);
+        const localSdp = transport.peer.localDescription?.sdp;
+        const sdp = filterIceCandidates(localSdp, transport.sentCandidateKeys).sdp;
         const localFingerprint = fingerprint(localSdp);
         if (sdp === undefined || localFingerprint === undefined)
             throw new Error('DIRECT_FINGERPRINT_MISSING');
-        this.emit(session.command.directSessionId, {
+        this.emit(transport.command.directSessionId, {
             type: 'direct.signal',
-            directSessionId: session.command.directSessionId,
+            directSessionId: transport.command.directSessionId,
             signal: { kind: 'ANSWER', sdp, fingerprint: localFingerprint }
         });
     }
-    attachChannel(session, channel) {
-        session.channel = channel;
+    attachPendingChannel(transport, channel) {
         channel.binaryType = 'arraybuffer';
+        let attached = false;
+        channel.onmessage = (event) => {
+            if (attached)
+                return;
+            attached = true;
+            void this.openChannel(transport, channel, event.data).catch((error) => {
+                channel.close();
+                const id = openFrameSessionId(event.data);
+                if (id !== undefined)
+                    this.fail(id, errorCode(error), errorMessage(error));
+            });
+        };
+    }
+    async openChannel(transport, channel, data) {
+        if (typeof data !== 'string')
+            throw new Error('DIRECT_OPEN_REQUIRED');
+        const parsed = directDataControlFrameSchema.parse(JSON.parse(data));
+        if (parsed.type !== 'OPEN')
+            throw new Error('DIRECT_OPEN_REQUIRED');
+        const transfer = this.transfers.get(parsed.directSessionId);
+        const grant = transfer?.grant;
+        if (transfer === undefined ||
+            grant === undefined ||
+            transfer.command.transportSessionId !== transport.command.directSessionId ||
+            parsed.grant !== grant.grant ||
+            grant.openExpiresAt <= this.now() ||
+            grant.expiresAt <= this.now())
+            throw new Error('DIRECT_TRANSFER_GRANT_INVALID');
+        transfer.channel = channel;
+        transfer.opened = true;
         channel.onmessage = (event) => {
-            session.processing = session.processing
-                .then(() => this.channelMessage(session, event.data))
-                .catch((error) => this.fail(session.command.directSessionId, errorCode(error), errorMessage(error)));
+            transfer.processing = transfer.processing
+                .then(() => this.channelMessage(transfer, event.data))
+                .catch((error) => this.fail(transfer.command.directSessionId, errorCode(error), errorMessage(error)));
         };
         channel.onclose = () => {
-            if (this.sessions.get(session.command.directSessionId) === session)
-                void this.remove(session, 'DIRECT_CHANNEL_CLOSED');
+            if (this.transfers.get(transfer.command.directSessionId) === transfer)
+                void this.removeTransfer(transfer, 'DIRECT_CHANNEL_CLOSED');
         };
+        await this.open(transfer);
     }
-    async channelMessage(session, data) {
-        if (!session.opened) {
-            if (typeof data !== 'string')
-                throw new Error('DIRECT_OPEN_REQUIRED');
-            const parsed = directDataControlFrameSchema.parse(JSON.parse(data));
-            if (parsed.type !== 'OPEN')
-                throw new Error('DIRECT_OPEN_REQUIRED');
-            const grant = session.grant;
-            if (grant === undefined ||
-                parsed.directSessionId !== session.command.directSessionId ||
-                parsed.grant !== grant.grant ||
-                grant.openExpiresAt <= this.now() ||
-                grant.expiresAt <= this.now())
-                throw new Error('DIRECT_GRANT_INVALID');
-            session.opened = true;
-            if (session.command.purpose === 'TRANSFER')
-                this.startLeaseWatch(session);
-            await this.open(session);
-            return;
-        }
-        if (session.command.purpose !== 'TRANSFER' || session.command.transfer === undefined)
-            throw new Error('DIRECT_FRAME_INVALID');
-        if (session.command.transfer.direction === 'DOWNLOAD') {
+    async channelMessage(transfer, data) {
+        const descriptor = transfer.command.transfer;
+        const expectedSize = transferredSize(descriptor);
+        const expectedSha256 = transferredSha256(descriptor);
+        if (descriptor.direction === 'DOWNLOAD') {
             if (typeof data !== 'string')
                 throw new Error('DIRECT_FRAME_INVALID');
             const control = directDataControlFrameSchema.parse(JSON.parse(data));
-            if (control.type !== 'ACK' || control.offset !== session.command.transfer.size)
+            if (control.type !== 'ACK' || control.offset !== expectedSize)
                 throw new Error('DIRECT_FRAME_INVALID');
-            this.emit(session.command.directSessionId, {
+            this.emit(transfer.command.directSessionId, {
                 type: 'direct.complete',
-                directSessionId: session.command.directSessionId,
-                size: session.command.transfer.size,
-                sha256: session.command.transfer.sha256
+                directSessionId: transfer.command.directSessionId,
+                size: expectedSize,
+                sha256: expectedSha256
             });
-            await this.remove(session);
+            await this.removeTransfer(transfer);
             return;
         }
         if (typeof data === 'string') {
             const control = directDataControlFrameSchema.parse(JSON.parse(data));
-            if (control.type !== 'COMPLETE' || session.upload === undefined)
+            if (control.type !== 'COMPLETE' || transfer.upload === undefined)
                 throw new Error('DIRECT_FRAME_INVALID');
-            if (control.size !== session.command.transfer.size ||
-                control.sha256 !== session.command.transfer.sha256)
+            if (control.size !== descriptor.size || control.sha256 !== descriptor.sha256)
                 throw new Error('DIRECT_INTEGRITY_FAILED');
-            await session.upload.complete(control.size, control.sha256);
-            session.uploadCommitted = true;
-            this.emit(session.command.directSessionId, {
+            await transfer.upload.complete(control.size, control.sha256);
+            transfer.uploadCommitted = true;
+            this.emit(transfer.command.directSessionId, {
                 type: 'direct.complete',
-                directSessionId: session.command.directSessionId,
+                directSessionId: transfer.command.directSessionId,
                 size: control.size,
                 sha256: control.sha256
             });
-            await this.remove(session);
+            await this.removeTransfer(transfer);
             return;
         }
         const bytes = toBytes(data);
-        if (bytes.byteLength === 0 || bytes.byteLength > 256 * 1024 || session.upload === undefined)
+        if (bytes.byteLength === 0 || bytes.byteLength > 256 * 1024 || transfer.upload === undefined)
             throw new Error('DIRECT_CHUNK_INVALID');
-        const offset = await session.upload.write(bytes);
-        session.channel?.send(JSON.stringify({ type: 'ACK', offset }));
+        const offset = await transfer.upload.write(bytes);
+        transfer.channel?.send(JSON.stringify({ type: 'ACK', offset }));
     }
-    async open(session) {
-        if (session.command.purpose === 'PROBE') {
-            session.channel?.send(JSON.stringify({ type: 'ACK', offset: 0 }));
-            this.emit(session.command.directSessionId, {
-                type: 'direct.probe-result',
-                directSessionId: session.command.directSessionId,
-                result: 'DIRECT_AVAILABLE'
-            });
-            await this.remove(session);
-            return;
-        }
-        const descriptor = session.command.transfer;
-        if (descriptor === undefined)
-            throw new Error('DIRECT_TRANSFER_INVALID');
+    async open(transfer) {
+        const descriptor = transfer.command.transfer;
         if (descriptor.direction === 'UPLOAD') {
             if (this.options.openUpload === undefined)
                 throw new Error('DIRECT_UPLOAD_UNAVAILABLE');
-            session.upload = await this.options.openUpload(descriptor);
-            session.channel?.send(JSON.stringify({ type: 'ACK', offset: session.upload.offset }));
-            this.emit(session.command.directSessionId, {
+            transfer.upload = await this.options.openUpload(descriptor);
+            transfer.channel?.send(JSON.stringify({ type: 'ACK', offset: transfer.upload.offset }));
+            this.emit(transfer.command.directSessionId, {
                 type: 'direct.opened',
-                directSessionId: session.command.directSessionId,
-                offset: session.upload.offset
+                directSessionId: transfer.command.directSessionId,
+                offset: transfer.upload.offset
             });
             return;
         }
         if (this.options.openDownload === undefined)
             throw new Error('DIRECT_DOWNLOAD_UNAVAILABLE');
         const source = await this.options.openDownload(descriptor);
-        session.channel?.send(JSON.stringify({ type: 'ACK', offset: source.offset }));
-        this.emit(session.command.directSessionId, {
+        const expectedSize = transferredSize(descriptor);
+        const expectedSha256 = transferredSha256(descriptor);
+        transfer.channel?.send(JSON.stringify({ type: 'ACK', offset: source.offset }));
+        this.emit(transfer.command.directSessionId, {
             type: 'direct.opened',
-            directSessionId: session.command.directSessionId,
+            directSessionId: transfer.command.directSessionId,
             offset: source.offset
         });
-        for await (const chunk of source.chunks) {
+        for await (const chunk of source.chunks)
             for (let offset = 0; offset < chunk.byteLength; offset += 256 * 1024) {
-                if (this.sessions.get(session.command.directSessionId) !== session)
+                if (this.transfers.get(transfer.command.directSessionId) !== transfer)
                     return;
-                const channel = session.channel;
+                const channel = transfer.channel;
                 if (channel === undefined)
                     throw new Error('DIRECT_CHANNEL_CLOSED');
-                await this.waitForSendCapacity(session, channel);
+                await this.waitForSendCapacity(transfer, channel);
                 const end = Math.min(chunk.byteLength, offset + 256 * 1024);
                 channel.send(chunk.buffer.slice(chunk.byteOffset + offset, chunk.byteOffset + end));
             }
-        }
-        session.channel?.send(JSON.stringify({
-            type: 'COMPLETE',
-            size: descriptor.size,
-            sha256: descriptor.sha256
-        }));
+        transfer.channel?.send(JSON.stringify({ type: 'COMPLETE', size: expectedSize, sha256: expectedSha256 }));
     }
-    async waitForSendCapacity(session, channel) {
+    async waitForSendCapacity(transfer, channel) {
         if (channel.readyState !== 'open')
             throw new Error('DIRECT_CHANNEL_CLOSED');
         if (channel.bufferedAmount <= DATA_CHANNEL_HIGH_WATER_BYTES)
@@ -304,62 +362,105 @@ export class DirectTransferService {
             const complete = (error) => {
                 channel.removeEventListener('bufferedamountlow', available);
                 channel.removeEventListener('close', closed);
-                if (error === undefined)
-                    resolve();
-                else
-                    reject(error);
+                error === undefined ? resolve() : reject(error);
             };
             const available = () => complete();
             const closed = () => complete(new Error('DIRECT_CHANNEL_CLOSED'));
             channel.addEventListener('bufferedamountlow', available, { once: true });
             channel.addEventListener('close', closed, { once: true });
-            if (this.sessions.get(session.command.directSessionId) !== session ||
+            if (this.transfers.get(transfer.command.directSessionId) !== transfer ||
                 channel.readyState !== 'open')
                 closed();
             else if (channel.bufferedAmount <= DATA_CHANNEL_LOW_WATER_BYTES)
                 available();
         });
     }
-    startLeaseWatch(session) {
-        session.lastLeaseAliveAt = this.now();
-        session.leaseTimer = setInterval(() => {
+    startLeaseWatch(expiresAt, lastAlive, expire) {
+        const timer = setInterval(() => {
             const now = this.now();
-            if (session.command.expiresAt <= now) {
-                void this.remove(session, 'DIRECT_SESSION_EXPIRED');
-                return;
-            }
-            if (now - (session.lastLeaseAliveAt ?? now) > this.leaseGraceMs)
-                void this.remove(session, 'DIRECT_LEASE_EXPIRED');
+            if (expiresAt() <= now || now - lastAlive() > this.leaseGraceMs)
+                expire();
         }, this.leaseCheckMs);
+        return timer;
     }
     emit(directSessionId, event) {
-        if (this.sessions.has(directSessionId))
+        if (this.transports.has(directSessionId) || this.transfers.has(directSessionId))
             this.options.send(event.type, event);
     }
     fail(directSessionId, code, message) {
-        const session = this.sessions.get(directSessionId);
         this.options.send('direct.error', { type: 'direct.error', directSessionId, code, message });
-        if (session !== undefined)
-            void this.remove(session);
+        const transfer = this.transfers.get(directSessionId);
+        if (transfer !== undefined)
+            void this.removeTransfer(transfer);
+        const transport = this.transports.get(directSessionId);
+        if (transport !== undefined)
+            this.removeTransport(transport);
+    }
+    removeTransport(transport, code) {
+        if (!this.transports.delete(transport.command.directSessionId))
+            return;
+        clearInterval(transport.leaseTimer);
+        for (const transfer of [...this.transfers.values()])
+            if (transfer.command.transportSessionId === transport.command.directSessionId)
+                void this.removeTransfer(transfer, code ?? 'DIRECT_CONNECTION_FAILED');
+        transport.peer.close();
+        if (code !== undefined)
+            this.options.send('direct.error', {
+                type: 'direct.error',
+                directSessionId: transport.command.directSessionId,
+                code,
+                message: directErrorMessage(code)
+            });
     }
-    async remove(session, code) {
-        if (!this.sessions.delete(session.command.directSessionId))
+    async removeTransfer(transfer, code) {
+        if (!this.transfers.delete(transfer.command.directSessionId))
             return;
-        if (session.leaseTimer !== undefined)
-            clearInterval(session.leaseTimer);
-        if (!session.uploadCommitted)
-            await session.upload?.cancel().catch(() => undefined);
-        session.channel?.close();
-        session.peer.close();
+        clearInterval(transfer.leaseTimer);
+        if (!transfer.uploadCommitted)
+            await transfer.upload?.cancel().catch(() => undefined);
+        transfer.channel?.close();
         if (code !== undefined)
             this.options.send('direct.error', {
                 type: 'direct.error',
-                directSessionId: session.command.directSessionId,
+                directSessionId: transfer.command.directSessionId,
                 code,
                 message: directErrorMessage(code)
             });
     }
 }
+function transferredSize(descriptor) {
+    return descriptor.direction === 'DOWNLOAD' && descriptor.range !== undefined
+        ? descriptor.range.length
+        : descriptor.size;
+}
+function transferredSha256(descriptor) {
+    return descriptor.direction === 'DOWNLOAD' && descriptor.range !== undefined
+        ? descriptor.range.sha256
+        : descriptor.sha256;
+}
+function openFrameSessionId(data) {
+    if (typeof data !== 'string')
+        return undefined;
+    try {
+        const value = JSON.parse(data);
+        return typeof value.directSessionId === 'string' ? value.directSessionId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function bindIceUdpMuxListener(range, create) {
+    let lastError;
+    for (let port = range.begin; port <= range.end; port += 1) {
+        try {
+            return create(port);
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error('DIRECT_UDP_PORT_UNAVAILABLE', { cause: lastError });
+}
 export function fingerprint(sdp) {
     const match = sdp?.match(/^a=fingerprint:(sha-256 [A-F0-9:]+)\r?$/imu);
     return match?.[1];

package/dist/service/workspace-file-service.js

@@ -63,37 +63,78 @@ export class WorkspaceFileService {
         const service = this;
         return (async function* () {
             const hash = createHash('sha256');
-            let offset = 0;
-            while (true) {
+            let offset = input.range?.offset ?? 0;
+            const endOffset = input.range === undefined ? input.size : input.range.offset + input.range.length;
+            while (offset < endOffset) {
                 const range = (await service.readContent(workspace, {
                     path: input.path,
                     offset,
-                    limit: 512 * 1024
+                    limit: Math.min(512 * 1024, endOffset - offset)
                 }, workspacePath));
-                if (range.size !== input.size)
+                if (range.size !== input.size || range.sourceRevision !== input.revision)
                     throw new Error('DIRECT_FILE_REVISION_CHANGED');
                 const bytes = Buffer.from(range.contentBase64, 'base64');
                 hash.update(bytes);
                 offset += bytes.length;
                 if (bytes.length > 0)
                     yield bytes;
-                if (range.nextOffset === null)
+                if (offset === endOffset)
                     break;
                 if (range.nextOffset !== offset)
                     throw new Error('DIRECT_FILE_REVISION_CHANGED');
             }
-            if (offset !== input.size || hash.digest('hex') !== input.sha256)
+            const expectedHash = input.range?.sha256 ?? input.sha256;
+            if (offset !== endOffset || hash.digest('hex') !== expectedHash)
                 throw new Error('DIRECT_FILE_REVISION_CHANGED');
         })();
     }
     async directMetadata(workspace, input, workspacePath = workspace.path) {
+        if (input.offset !== undefined ||
+            input.length !== undefined ||
+            input.size !== undefined ||
+            input.sha256 !== undefined) {
+            if (!Number.isSafeInteger(input.offset) ||
+                input.offset < 0 ||
+                !Number.isSafeInteger(input.length) ||
+                input.length < 1 ||
+                !Number.isSafeInteger(input.size) ||
+                input.size < 0 ||
+                typeof input.sha256 !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(input.sha256) ||
+                typeof input.revision !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(input.revision))
+                throw new Error('FILE_RANGE_INVALID');
+            const offset = input.offset;
+            const length = input.length;
+            const expectedSize = input.size;
+            if (offset + length > expectedSize)
+                throw new Error('FILE_RANGE_INVALID');
+            const read = (await this.readContent(workspace, { ...input, offset, limit: length }, workspacePath));
+            const bytes = Buffer.from(read.contentBase64, 'base64');
+            if (read.size !== expectedSize ||
+                read.sourceRevision !== input.revision ||
+                bytes.length !== length)
+                throw new Error('DIRECT_FILE_REVISION_CHANGED');
+            return {
+                size: expectedSize,
+                sha256: input.sha256,
+                revision: input.revision,
+                range: {
+                    offset,
+                    length,
+                    sha256: createHash('sha256').update(bytes).digest('hex')
+                }
+            };
+        }
         const hash = createHash('sha256');
         let offset = 0;
         let size;
+        let revision;
         while (true) {
             const range = (await this.readContent(workspace, { ...input, offset, limit: 512 * 1024 }, workspacePath));
             size ??= range.size;
-            if (range.size !== size)
+            revision ??= range.sourceRevision;
+            if (range.size !== size || range.sourceRevision !== revision)
                 throw new Error('DIRECT_FILE_REVISION_CHANGED');
             const bytes = Buffer.from(range.contentBase64, 'base64');
             hash.update(bytes);
@@ -103,9 +144,10 @@ export class WorkspaceFileService {
             if (range.nextOffset !== offset)
                 throw new Error('DIRECT_FILE_REVISION_CHANGED');
         }
-        if (size === undefined || offset !== size)
+        if (size === undefined || revision === undefined || offset !== size)
             throw new Error('DIRECT_FILE_REVISION_CHANGED');
-        return { size, sha256: hash.digest('hex') };
+        const sha256 = hash.digest('hex');
+        return { size, sha256, revision };
     }
     async write(workspace, input) {
         if (typeof input.path !== 'string' ||

package/dist/service/workspace-workbench-service.js

@@ -235,6 +235,8 @@ export class WorkspaceWorkbenchService {
         };
     }
     async directDownload(descriptor) {
+        if (descriptor.direction !== 'DOWNLOAD')
+            throw new Error('DIRECT_RESOURCE_UNSUPPORTED');
         const workspace = this.options.requireWorkspace(descriptor.resource.workspaceId);
         if (descriptor.resource.kind === 'WORKSPACE_FILE') {
             const input = {
@@ -245,41 +247,51 @@ export class WorkspaceWorkbenchService {
                     : { worktreePath: descriptor.resource.worktreePath })
             };
             return {
-                offset: descriptor.resumeOffset ?? 0,
+                offset: descriptor.range?.offset ?? 0,
                 chunks: this.options.files.readDirect(workspace, {
                     path: descriptor.resource.path,
                     size: descriptor.size,
-                    sha256: descriptor.sha256
+                    sha256: descriptor.sha256,
+                    revision: descriptor.revision,
+                    ...(descriptor.range === undefined ? {} : { range: descriptor.range })
                 }, await this.fileRepository(workspace, input))
             };
         }
+        const resource = descriptor.resource;
         const input = {
             workspaceId: workspace.id,
-            path: descriptor.resource.path,
-            commit: descriptor.resource.commit,
-            ...(descriptor.resource.repositoryPath === undefined
-                ? {}
-                : { repositoryPath: descriptor.resource.repositoryPath }),
-            ...(descriptor.resource.worktreePath === undefined
-                ? {}
-                : { worktreePath: descriptor.resource.worktreePath })
+            path: resource.path,
+            commit: resource.commit,
+            ...(resource.repositoryPath === undefined ? {} : { repositoryPath: resource.repositoryPath }),
+            ...(resource.worktreePath === undefined ? {} : { worktreePath: resource.worktreePath })
         };
         const repository = await this.gitRepository(input);
-        const content = await openGitHistoryFileContent(repository, descriptor.resource.commit, descriptor.resource.path, this.refs(input));
-        if (content.size !== descriptor.size)
+        if (descriptor.revision !== gitResourceRevision(resource.commit, resource.path))
             throw new Error('DIRECT_FILE_REVISION_CHANGED');
+        const refs = this.refs(input);
         return {
-            offset: descriptor.resumeOffset ?? 0,
+            offset: descriptor.range?.offset ?? 0,
             chunks: (async function* () {
                 const hash = createHash('sha256');
-                let offset = 0;
-                for await (const bytes of content.chunks) {
+                let offset = descriptor.range?.offset ?? 0;
+                const rangeStart = descriptor.range?.offset ?? 0;
+                const rangeEnd = rangeStart + (descriptor.range?.length ?? descriptor.size);
+                while (offset < rangeEnd) {
+                    const range = await readGitHistoryFileContentRange(repository, resource.commit, resource.path, offset, Math.min(512 * 1024, rangeEnd - offset), refs);
+                    if (range.size !== descriptor.size)
+                        throw new Error('DIRECT_FILE_REVISION_CHANGED');
+                    const bytes = Buffer.from(range.contentBase64, 'base64');
                     hash.update(bytes);
                     offset += bytes.length;
                     if (bytes.length > 0)
                         yield bytes;
+                    if (offset === rangeEnd)
+                        break;
+                    if (range.nextOffset !== offset)
+                        throw new Error('DIRECT_FILE_REVISION_CHANGED');
                 }
-                if (offset !== descriptor.size || hash.digest('hex') !== descriptor.sha256)
+                const expectedHash = descriptor.range?.sha256 ?? descriptor.sha256;
+                if (offset !== rangeEnd || hash.digest('hex') !== expectedHash)
                     throw new Error('DIRECT_FILE_REVISION_CHANGED');
             })()
         };
@@ -288,6 +300,43 @@ export class WorkspaceWorkbenchService {
         const repository = await this.gitRepository(input);
         if (typeof input.commit !== 'string' || typeof input.path !== 'string')
             throw new Error('GIT_HISTORY_COMMIT_INVALID');
+        const revision = gitResourceRevision(input.commit, input.path);
+        if (input.offset !== undefined ||
+            input.length !== undefined ||
+            input.size !== undefined ||
+            input.sha256 !== undefined ||
+            input.revision !== undefined) {
+            if (!Number.isSafeInteger(input.offset) ||
+                input.offset < 0 ||
+                !Number.isSafeInteger(input.length) ||
+                input.length < 1 ||
+                input.length > 512 * 1024 ||
+                !Number.isSafeInteger(input.size) ||
+                input.size < 0 ||
+                typeof input.sha256 !== 'string' ||
+                !/^[a-f0-9]{64}$/u.test(input.sha256) ||
+                input.revision !== revision)
+                throw new Error('FILE_RANGE_INVALID');
+            const offset = input.offset;
+            const length = input.length;
+            const size = input.size;
+            if (offset + length > size)
+                throw new Error('FILE_RANGE_INVALID');
+            const range = await readGitHistoryFileContentRange(repository, input.commit, input.path, offset, length, this.refs(input));
+            const bytes = Buffer.from(range.contentBase64, 'base64');
+            if (range.size !== size || bytes.length !== length)
+                throw new Error('DIRECT_FILE_REVISION_CHANGED');
+            return {
+                size,
+                sha256: input.sha256,
+                revision,
+                range: {
+                    offset,
+                    length,
+                    sha256: createHash('sha256').update(bytes).digest('hex')
+                }
+            };
+        }
         const content = await openGitHistoryFileContent(repository, input.commit, input.path, this.refs(input));
         const hash = createHash('sha256');
         let offset = 0;
@@ -297,7 +346,7 @@ export class WorkspaceWorkbenchService {
         }
         if (offset !== content.size)
             throw new Error('DIRECT_FILE_REVISION_CHANGED');
-        return { size: content.size, sha256: hash.digest('hex') };
+        return { size: content.size, sha256: hash.digest('hex'), revision };
     }
     async diff(input) {
         if (typeof input.workspaceId !== 'string' ||
@@ -314,6 +363,9 @@ export class WorkspaceWorkbenchService {
         return workspace;
     }
 }
+function gitResourceRevision(commit, path) {
+    return createHash('sha256').update(commit).update('\0').update(path).digest('hex');
+}
 function record(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value)
         ? value

package/dist/workspace.js

@@ -672,6 +672,7 @@ export async function readWorkspaceFileContentRange(workspaceRoot, requestedPath
         return {
             path: relative(root, file).split(sep).join('/'),
             size: metadata.size,
+            sourceRevision: fileSourceRevision(metadata),
             offset,
             contentBase64: source.subarray(0, bytesRead).toString('base64'),
             nextOffset: end < metadata.size ? end : null
@@ -701,6 +702,7 @@ export async function readAllowedFileContentRange(requestedPath, allowedRoots, o
         return {
             path: file,
             size: metadata.size,
+            sourceRevision: fileSourceRevision(metadata),
             offset,
             contentBase64: source.subarray(0, bytesRead).toString('base64'),
             nextOffset: end < metadata.size ? end : null
@@ -710,6 +712,11 @@ export async function readAllowedFileContentRange(requestedPath, allowedRoots, o
         await handle.close();
     }
 }
+function fileSourceRevision(metadata) {
+    return createHash('sha256')
+        .update([metadata.dev, metadata.ino, metadata.size, metadata.mtimeMs, metadata.ctimeMs].join(':'))
+        .digest('hex');
+}
 /** Reads one absolute file only when the resolved target remains within a preview root. */
 export async function readAllowedTextFile(requestedPath, allowedRoots, offset = 0, limit = FILE_READ_LIMIT) {
     const { file, metadata } = await resolveAllowedFile(requestedPath, allowedRoots);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.9.68",
+  "version": "0.9.70",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,8 +28,8 @@
     "node-pty": "1.1.0",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.9.68",
-    "@myagentroam/protocol": "0.9.68"
+    "@myagentroam/agent": "0.9.70",
+    "@myagentroam/protocol": "0.9.70"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"