@myagentroam/marmgr 0.9.112 → 0.9.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/marmgr",
-  "version": "0.9.112",
+  "version": "0.9.113",
   "description": "MyAgentRoam Node terminal manager CLI.",
   "license": "Apache-2.0",
   "type": "module",

package/src/cli.mjs

@@ -46,6 +46,7 @@ export async function main(
       nodeId: args.nodeId,
       command: args.remoteCommand,
       forcePty: args.forcePty,
+      raceConnections: true,
       stdout,
       stderr,
       translate

package/src/client.mjs

@@ -76,7 +76,9 @@ export class MarmgrClient {
       !isNonEmptyString(payload.manifest.nodeGeneration)
     )
       throw new MarmgrError(this.#translate('errors.serverInvalidManifest'));
-    return payload.manifest;
+    return payload.deferredRelay === true
+      ? { ...payload.manifest, deferredRelay: true }
+      : payload.manifest;
   }
 
   async createAttachTicket({ nodeId, terminalId, afterSequence }) {
@@ -105,7 +107,7 @@ export class MarmgrClient {
     });
   }
 
-  openTerminalWebSocket(WebSocketClass, { terminalId, ticket }) {
+  openTerminalWebSocket(WebSocketClass, { terminalId, ticket, deferred = false }) {
     validateTerminalId(terminalId, this.#translate);
     if (!isNonEmptyString(ticket))
       throw new MarmgrError(this.#translate('errors.terminalTicketInvalid'));
@@ -115,6 +117,7 @@ export class MarmgrClient {
       `${this.#serverUrl}/`
     );
     url.searchParams.set('ticket', ticket);
+    if (deferred) url.searchParams.set('deferred', '1');
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
 
     try {

package/src/direct.mjs

@@ -3,6 +3,7 @@ import { EventEmitter } from 'node:events';
 
 export const DIRECT_PREPARE_TIMEOUT_MS = 5000;
 export const DIRECT_SETUP_TIMEOUT_MS = 15000;
+export const DIRECT_ICE_TIMEOUT_MS = 3000;
 export const DIRECT_HEARTBEAT_MS = 10000;
 
 export class DirectFallbackError extends Error {
@@ -29,7 +30,9 @@ export async function openDirectTerminal({
   afterSequence = 0,
   timeoutMs = DIRECT_SETUP_TIMEOUT_MS,
   heartbeatMs = DIRECT_HEARTBEAT_MS,
-  peerConnectionFactory
+  peerConnectionFactory,
+  onTransportReady,
+  signal
 }) {
   if (typeof client.getTerminalManifest !== 'function')
     throw new DirectFallbackError('DIRECT_MANIFEST_UNAVAILABLE');
@@ -183,13 +186,19 @@ export async function openDirectTerminal({
       }
     });
     try {
-      await withTimeout(transportReady, timeoutMs, 'DIRECT_SETUP_TIMEOUT');
+      await withTimeout(
+        transportReady,
+        Math.min(timeoutMs, DIRECT_ICE_TIMEOUT_MS),
+        'DIRECT_SETUP_TIMEOUT',
+        signal
+      );
     } finally {
       transportNegotiationActive = false;
       transportControlCleanup?.();
       transportControlCleanup = undefined;
     }
     bootstrapChannel?.close?.();
+    if (onTransportReady) await onTransportReady();
 
     const terminalPrepared = await live.request(
       {
@@ -665,14 +674,27 @@ async function cancelSession(live, type, directSessionId) {
   await closed.catch(() => undefined);
 }
 
-function withTimeout(promise, timeoutMs, code) {
+function withTimeout(promise, timeoutMs, code, signal) {
   let timer;
+  let onAbort;
   return Promise.race([
     promise,
     new Promise((_, reject) => {
       timer = setTimeout(() => reject(new DirectFallbackError(code)), timeoutMs);
-    })
-  ]).finally(() => clearTimeout(timer));
+    }),
+    ...(signal
+      ? [
+          new Promise((_, reject) => {
+            onAbort = () => reject(new DirectFallbackError('DIRECT_RACE_CANCELLED'));
+            if (signal.aborted) onAbort();
+            else signal.addEventListener('abort', onAbort, { once: true });
+          })
+        ]
+      : [])
+  ]).finally(() => {
+    clearTimeout(timer);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  });
 }
 
 function requestId() {

package/src/terminal.mjs

@@ -17,7 +17,8 @@ export async function runTerminalSession({
   signals = process,
   translate = createTranslator(),
   connectionTimeoutMs = DEFAULT_CONNECTION_TIMEOUT_MS,
-  openDirectTerminal: openDirectTerminalImpl
+  openDirectTerminal: openDirectTerminalImpl,
+  raceConnections = false
 }) {
   const dimensions = getDimensions(stdout);
   let terminalId;
@@ -34,14 +35,29 @@ export async function runTerminalSession({
     try {
       const openDirectTerminal =
         openDirectTerminalImpl ?? (await import('./direct.mjs')).openDirectTerminal;
-      transport = await openDirectTerminal({
+      const directOptions = {
         client,
         WebSocketClass,
         nodeId,
         terminalId,
         afterSequence: 0,
         timeoutMs: connectionTimeoutMs
-      });
+      };
+      const canRace =
+        raceConnections &&
+        (await client.getTerminalManifest(nodeId).catch(() => undefined))?.deferredRelay === true;
+      transport = canRace
+        ? await raceTerminalConnections({
+            openDirectTerminal,
+            directOptions,
+            client,
+            WebSocketClass,
+            nodeId,
+            terminalId,
+            translate,
+            connectionTimeoutMs
+          })
+        : await openDirectTerminal(directOptions);
       result = await runAttachedTerminal({
         transport,
         terminalId,
@@ -91,6 +107,74 @@ export async function runTerminalSession({
   return result;
 }
 
+async function raceTerminalConnections({
+  openDirectTerminal,
+  directOptions,
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs
+}) {
+  const abort = new AbortController();
+  const relayAbort = new AbortController();
+  let selected;
+  let announce;
+  const first = new Promise((resolve) => {
+    announce = resolve;
+  });
+  const select = (candidate) => {
+    if (selected) return false;
+    selected = candidate;
+    announce(candidate);
+    if (candidate === 'relay') abort.abort();
+    else relayAbort.abort();
+    return true;
+  };
+  const direct = openDirectTerminal({
+    ...directOptions,
+    signal: abort.signal,
+    onTransportReady: () => {
+      if (!select('direct')) throw new Error('DIRECT_RACE_CANCELLED');
+    }
+  }).then(
+    (value) => ({ value }),
+    (error) => ({ error })
+  );
+  const relay = prepareRelayTransport({
+    client,
+    WebSocketClass,
+    nodeId,
+    terminalId,
+    translate,
+    connectionTimeoutMs,
+    signal: relayAbort.signal
+  }).then(
+    (value) => {
+      if (!select('relay')) value.close();
+      return { value };
+    },
+    (error) => ({ error })
+  );
+  const winner = await Promise.race([
+    first,
+    Promise.all([direct, relay]).then(() => selected ?? 'none')
+  ]);
+  if (winner === 'direct') {
+    const result = await direct;
+    if (result.error) throw result.error;
+    return result.value;
+  }
+  if (winner === 'relay') {
+    const result = await relay;
+    if (result.error) throw result.error;
+    return result.value.activate();
+  }
+  const [directResult, relayResult] = await Promise.all([direct, relay]);
+  throw relayResult.error ?? directResult.error;
+}
+
 export function splitInput(text, maxBytes = MAX_INPUT_BYTES) {
   const value = Buffer.isBuffer(text) ? text.toString('utf8') : String(text);
   const chunks = [];
@@ -144,6 +228,87 @@ async function openRelayTransport({
   }
 }
 
+async function prepareRelayTransport({
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs,
+  signal
+}) {
+  const ticket = await client.createAttachTicket({ nodeId, terminalId });
+  if (signal?.aborted) throw new MarmgrError(translate('errors.terminalAttachConnection'));
+  const socket = client.openTerminalWebSocket(WebSocketClass, {
+    terminalId,
+    ticket,
+    deferred: true
+  });
+  // Keep an error listener after readiness until the socket is discarded.
+  socket.on('error', () => {});
+  let activated = false;
+  const ready = new Promise((resolve, reject) => {
+    const timer = setTimeout(() => fail(), connectionTimeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      socket.removeListener?.('message', onMessage);
+      socket.removeListener?.('error', fail);
+      socket.removeListener?.('close', fail);
+      signal?.removeEventListener('abort', fail);
+    };
+    const fail = () => {
+      cleanup();
+      try {
+        socket.close();
+      } catch {
+        /* Connection not yet established. */
+      }
+      reject(new MarmgrError(translate('errors.terminalAttachConnection')));
+    };
+    const onMessage = (raw) => {
+      let frame;
+      try {
+        frame = JSON.parse(String(raw));
+      } catch {
+        return fail();
+      }
+      if (frame?.type !== 'ready' || frame.terminalId !== terminalId) return fail();
+      cleanup();
+      resolve();
+    };
+    socket.on('message', onMessage);
+    socket.on('error', fail);
+    socket.on('close', fail);
+    signal?.addEventListener('abort', fail, { once: true });
+    if (signal?.aborted) fail();
+  });
+  await ready;
+  return {
+    async activate() {
+      if (activated || socket.readyState !== 1)
+        throw new MarmgrError(translate('errors.terminalAttachConnection'));
+      activated = true;
+      const transport = new BufferedRelayTransport({
+        socket,
+        terminalId,
+        translate,
+        connectionTimeoutMs
+      });
+      try {
+        socket.send(JSON.stringify({ type: 'activate', terminalId }));
+        await transport.waitForAttachment();
+        return transport;
+      } catch (error) {
+        transport.close();
+        throw error;
+      }
+    },
+    close() {
+      socket.close();
+    }
+  };
+}
+
 class BufferedRelayTransport extends EventEmitter {
   #socket;
   #terminalId;