@myagentroam/marctl 0.9.121 → 0.9.123

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/marctl",
-  "version": "0.9.121",
+  "version": "0.9.123",
   "description": "MyAgentRoam command-line interface for authorized Node access.",
   "license": "Apache-2.0",
   "type": "module",

package/src/direct.mjs

@@ -27,14 +27,17 @@ export async function openDirectTerminal({
   WebSocketClass,
   nodeId,
   terminalId,
+  manifest,
   afterSequence = 0,
   timeoutMs = DIRECT_SETUP_TIMEOUT_MS,
   heartbeatMs = DIRECT_HEARTBEAT_MS,
   peerConnectionFactory,
+  onPrepared,
+  onIceConnected,
   onTransportReady,
   signal
 }) {
-  if (typeof client.getTerminalManifest !== 'function')
+  if (manifest === undefined && typeof client.getTerminalManifest !== 'function')
     throw new DirectFallbackError('DIRECT_MANIFEST_UNAVAILABLE');
 
   let live;
@@ -49,7 +52,7 @@ export async function openDirectTerminal({
   let transportNegotiationActive = true;
   let cleanupNative;
   try {
-    const manifest = await client.getTerminalManifest(nodeId);
+    manifest ??= await client.getTerminalManifest(nodeId);
     if (
       typeof manifest?.nodeGeneration !== 'string' ||
       manifest.nodeGeneration.length < 8 ||
@@ -84,7 +87,12 @@ export async function openDirectTerminal({
       peerConnectionFactory ?? ((name, options) => new native.PeerConnection(name, options));
     peer = createPeer(`marctl-${transportSessionId}`, { iceServers: [] });
 
+    // Start negotiation only after both paths finish their control-plane preparation.
+    if (onPrepared) await onPrepared();
+    if (signal?.aborted) throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+
     const transportReady = new Promise((resolve, reject) => {
+      let iceConnected = false;
       let connected = false;
       let serverOpened = false;
       let settled = false;
@@ -162,6 +170,17 @@ export async function openDirectTerminal({
         )
           finish(new DirectFallbackError('DIRECT_CONTROL_UNAVAILABLE'));
       });
+      peer.onIceStateChange((state) => {
+        if (!transportNegotiationActive || settled || iceConnected) return;
+        const normalizedState = String(state).toLowerCase();
+        if (normalizedState !== 'connected' && normalizedState !== 'completed') return;
+        iceConnected = true;
+        try {
+          onIceConnected?.();
+        } catch (error) {
+          finish(error);
+        }
+      });
       peer.onStateChange((state) => {
         if (!transportNegotiationActive || settled) return;
         const normalizedState = String(state).toLowerCase();

package/src/scp-worker.cjs

@@ -4,6 +4,8 @@ const { link, lstat, open, rename, unlink } = require('node:fs/promises');
 const path = require('node:path');
 
 const CHUNK = 32 * 1024;
+const WINDOW = 8;
+const MAX_BUFFERED_BYTES = WINDOW * (CHUNK + 4) + 64;
 const [mode, encodedPath, sizeArgument, encodedMetadata, preserveArgument, encodedSourceBasename] =
   process.argv.slice(1);
 const target = Buffer.from(encodedPath ?? '', 'base64url').toString('utf8');
@@ -16,7 +18,7 @@ async function readExact(length) {
     const next = await input.next();
     if (next.done) throw new Error('SCP_STREAM_TRUNCATED');
     pending = Buffer.concat([pending, next.value]);
-    if (pending.length > CHUNK * 4) throw new Error('SCP_INPUT_OVERFLOW');
+    if (pending.length > MAX_BUFFERED_BYTES) throw new Error('SCP_INPUT_OVERFLOW');
   }
   const data = pending.subarray(0, length);
   pending = pending.subarray(length);
@@ -111,6 +113,8 @@ async function source() {
     const hash = createHash('sha256');
     const buffer = Buffer.alloc(CHUNK);
     let offset = 0;
+    let acknowledged = Promise.resolve();
+    const pendingAcks = [];
     while (offset < current.size) {
       const { bytesRead } = await handle.read(
         buffer,
@@ -121,9 +125,16 @@ async function source() {
       if (bytesRead === 0) throw new Error('SCP_SOURCE_CHANGED');
       hash.update(buffer.subarray(0, bytesRead));
       await send(Buffer.concat([frameLength(bytesRead), buffer.subarray(0, bytesRead)]));
-      if ((await readExact(1))[0] !== 1) throw new Error('SCP_ACK_INVALID');
+      // Serialize ACK reads without making each file read wait for a round trip.
+      acknowledged = acknowledged.then(async () => {
+        if ((await readExact(1))[0] !== 1) throw new Error('SCP_ACK_INVALID');
+      });
+      acknowledged.catch(() => undefined);
+      pendingAcks.push(acknowledged);
       offset += bytesRead;
+      if (pendingAcks.length >= WINDOW) await pendingAcks.shift();
     }
+    await acknowledged;
     const after = await handle.stat();
     if (
       after.size !== current.size ||

package/src/scp.mjs

@@ -6,6 +6,8 @@ import { MarctlError } from './config.mjs';
 import { parseFrame, runTerminalSession } from './terminal.mjs';
 
 const CHUNK = 32 * 1024;
+const WINDOW = 8;
+const MAX_BUFFERED_BYTES = WINDOW * (CHUNK + 4) + 64;
 const script = gzipSync(readFileSync(new URL('./scp-worker.cjs', import.meta.url))).toString(
   'base64'
 );
@@ -64,8 +66,11 @@ class ByteChannel {
   #sending = new Map();
   #ended;
   #failure;
+  #controller;
 
-  constructor(send, signal) {
+  constructor(send, controller) {
+    this.#controller = controller;
+    const signal = controller.signal;
     this.send = (bytes) => {
       if (this.#failure) throw this.#failure;
       if (this.#ended !== undefined) throw new MarctlError('Copy stream ended unexpectedly.');
@@ -86,22 +91,18 @@ class ByteChannel {
       });
     };
     if (signal) {
-      if (signal.aborted) this.fail(new MarctlError('Copy was interrupted.'));
+      if (signal.aborted) this.fail(signal.reason);
       else
-        signal.addEventListener(
-          'abort',
-          () => this.fail(new MarctlError('Copy was interrupted.')),
-          {
-            once: true
-          }
-        );
+        signal.addEventListener('abort', () => this.fail(signal.reason), {
+          once: true
+        });
     }
   }
 
   feed(bytes) {
     if (this.#failure) return;
     this.#buffer = Buffer.concat([this.#buffer, bytes]);
-    if (this.#buffer.length > CHUNK * 4)
+    if (this.#buffer.length > MAX_BUFFERED_BYTES)
       return this.fail(new MarctlError('Copy output exceeded the bounded window.'));
     this.#wake();
   }
@@ -120,10 +121,13 @@ class ByteChannel {
   }
 
   fail(error) {
-    this.#failure ??= error;
+    if (this.#failure !== undefined) return;
+    this.#failure = error;
     for (const reject of this.#sending.keys()) reject(this.#failure);
     this.#sending.clear();
     this.#wake();
+    // Any endpoint failure must wake reads and writes across the entire copy.
+    this.#controller.abort(error);
   }
 
   #wake() {
@@ -160,6 +164,8 @@ async function copyBytes(source, destination) {
     if ((await target.read(1))[0] !== 1)
       throw new MarctlError('Copy target did not accept the file.');
     let remaining = Number(size);
+    let acknowledged = Promise.resolve();
+    const pending = [];
     for (;;) {
       const header = await source.read(4);
       const length = header.readUInt32BE();
@@ -167,22 +173,42 @@ async function copyBytes(source, destination) {
         throw new MarctlError('Copy source sent an invalid chunk.');
       await target.send(header);
       if (length === 0) {
+        await acknowledged;
         await target.send(await source.read(32));
         if (remaining !== 0 || (await target.read(1))[0] !== 2)
           throw new MarctlError('Copy target did not verify the file.');
         break;
       }
       await target.send(await source.read(length));
-      if ((await target.read(1))[0] !== 1) throw new MarctlError('Copy target rejected the chunk.');
-      await source.send(Buffer.from([1]));
+      // Keep one ordered ACK reader while sending up to a bounded window ahead.
+      acknowledged = acknowledged.then(async () => {
+        if ((await target.read(1))[0] !== 1)
+          throw new MarctlError('Copy target rejected the chunk.');
+        await source.send(Buffer.from([1]));
+      });
+      acknowledged.catch((error) => {
+        // ACK failures use the same copy-wide cancellation as transport failures.
+        source.fail(error);
+      });
+      pending.push(acknowledged);
       remaining -= length;
+      if (pending.length >= WINDOW) await pending.shift();
     }
     await target.done();
   });
   await source.done();
 }
 
-async function withLocalWorker(mode, file, size, metadata, preserve, sourceBasename, use, signal) {
+async function withLocalWorker(
+  mode,
+  file,
+  size,
+  metadata,
+  preserve,
+  sourceBasename,
+  use,
+  controller
+) {
   const child = spawn(
     process.execPath,
     ['-e', expression, ...workerArguments(mode, file, size, metadata, preserve, sourceBasename)],
@@ -193,7 +219,13 @@ async function withLocalWorker(mode, file, size, metadata, preserve, sourceBasen
   );
   child.stdin.on('error', () => undefined);
   child.stderr.resume();
-  const channel = new ByteChannel((bytes) => child.stdin.write(bytes), signal);
+  const channel = new ByteChannel(
+    (bytes) =>
+      new Promise((resolve, reject) => {
+        child.stdin.write(bytes, (error) => (error ? reject(error) : resolve()));
+      }),
+    controller
+  );
   child.stdout.on('data', (bytes) => channel.feed(bytes));
   child.once('error', (error) => channel.fail(error));
   child.once('close', (code) => channel.finish(code ?? 1));
@@ -216,7 +248,7 @@ async function withRemoteWorker(
     preserve,
     sourceBasename,
     translate,
-    signal
+    controller
   },
   use
 ) {
@@ -234,7 +266,7 @@ async function withRemoteWorker(
           transport.send(
             JSON.stringify({ type: 'input', terminalId, data: bytes.toString('base64') })
           ),
-        signal
+        controller
       );
       let sequence = 0;
       const onMessage = (raw, isBinary) => {
@@ -285,7 +317,7 @@ async function withWorker(endpoint, mode, size, metadata, context, use) {
       context.preserve,
       context.sourceBasename,
       use,
-      context.signal
+      context.controller
     );
   return withRemoteWorker(
     {
@@ -321,7 +353,7 @@ export async function runScp({
     ...(endpoint.host ? { nodeId: ids[references.indexOf(endpoint.host)] } : {})
   });
   const controller = new AbortController();
-  const interrupt = () => controller.abort();
+  const interrupt = () => controller.abort(new MarctlError('Copy was interrupted.'));
   signals.on?.('SIGINT', interrupt);
   signals.on?.('SIGTERM', interrupt);
   try {
@@ -329,7 +361,7 @@ export async function runScp({
       client,
       WebSocketClass,
       translate,
-      signal: controller.signal,
+      controller,
       preserve,
       sourceBasename
     };
@@ -340,6 +372,9 @@ export async function runScp({
       })
     );
     return 0;
+  } catch (error) {
+    controller.abort(error);
+    throw error;
   } finally {
     signals.removeListener?.('SIGINT', interrupt);
     signals.removeListener?.('SIGTERM', interrupt);

package/src/terminal.mjs

@@ -28,13 +28,16 @@ export async function runTerminalSession({
   let transport;
   let result;
   let primaryError;
+  let manifest;
 
   try {
-    if (
-      binary &&
-      (command === undefined || (await client.getTerminalManifest(nodeId))?.binaryTerminal !== true)
-    )
-      throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+    if (binary) {
+      if (command === undefined)
+        throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+      manifest = await client.getTerminalManifest(nodeId);
+      if (manifest?.binaryTerminal !== true)
+        throw new MarctlError(translate('errors.terminalBinaryUnavailable'));
+    }
     const created = await client.createTerminal({
       nodeId,
       ...dimensions,
@@ -47,17 +50,18 @@ export async function runTerminalSession({
     try {
       const openDirectTerminal =
         openDirectTerminalImpl ?? (await import('./direct.mjs')).openDirectTerminal;
+      if (raceConnections && manifest === undefined)
+        manifest = await client.getTerminalManifest(nodeId).catch(() => undefined);
       const directOptions = {
         client,
         WebSocketClass,
         nodeId,
         terminalId,
+        manifest,
         afterSequence: 0,
         timeoutMs: connectionTimeoutMs
       };
-      const canRace =
-        raceConnections &&
-        (await client.getTerminalManifest(nodeId).catch(() => undefined))?.deferredRelay === true;
+      const canRace = raceConnections && manifest?.deferredRelay === true;
       transport = canRace
         ? await raceTerminalConnections({
             openDirectTerminal,
@@ -137,6 +141,16 @@ async function raceTerminalConnections({
 }) {
   const abort = new AbortController();
   const relayAbort = new AbortController();
+  const preparing = new Set(['direct', 'relay']);
+  let start;
+  const preparation = new Promise((resolve) => {
+    start = resolve;
+  });
+  const prepared = (candidate) => {
+    preparing.delete(candidate);
+    if (preparing.size === 0) start();
+    return preparation;
+  };
   let selected;
   let announce;
   const first = new Promise((resolve) => {
@@ -153,12 +167,19 @@ async function raceTerminalConnections({
   const direct = openDirectTerminal({
     ...directOptions,
     signal: abort.signal,
-    onTransportReady: () => {
+    onPrepared: () => prepared('direct'),
+    onIceConnected: () => {
       if (!select('direct')) throw new Error('DIRECT_RACE_CANCELLED');
+    },
+    onTransportReady: () => {
+      if (selected !== 'direct') throw new Error('DIRECT_RACE_CANCELLED');
     }
   }).then(
     (value) => ({ value }),
-    (error) => ({ error })
+    (error) => {
+      prepared('direct');
+      return { error };
+    }
   );
   const relay = prepareRelayTransport({
     client,
@@ -167,13 +188,17 @@ async function raceTerminalConnections({
     terminalId,
     translate,
     connectionTimeoutMs,
-    signal: relayAbort.signal
+    signal: relayAbort.signal,
+    onPrepared: () => prepared('relay')
   }).then(
     (value) => {
       if (!select('relay')) value.close();
       return { value };
     },
-    (error) => ({ error })
+    (error) => {
+      prepared('relay');
+      return { error };
+    }
   );
   const winner = await Promise.race([
     first,
@@ -253,9 +278,11 @@ async function prepareRelayTransport({
   terminalId,
   translate,
   connectionTimeoutMs,
-  signal
+  signal,
+  onPrepared
 }) {
   const ticket = await client.createAttachTicket({ nodeId, terminalId });
+  if (onPrepared) await onPrepared();
   if (signal?.aborted) throw new MarctlError(translate('errors.terminalAttachConnection'));
   const socket = client.openTerminalWebSocket(WebSocketClass, {
     terminalId,