@myagentroam/marctl 0.9.120 → 0.9.122

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/marctl",
-  "version": "0.9.120",
+  "version": "0.9.122",
   "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.mjs

@@ -61,13 +61,29 @@ function workerCommand(mode, file, size, metadata, preserve, sourceBasename) {
 class ByteChannel {
   #buffer = Buffer.alloc(0);
   #waiting = [];
+  #sending = new Map();
   #ended;
   #failure;
 
   constructor(send, signal) {
     this.send = (bytes) => {
       if (this.#failure) throw this.#failure;
-      return send(bytes);
+      if (this.#ended !== undefined) throw new MarctlError('Copy stream ended unexpectedly.');
+      return new Promise((resolve, reject) => {
+        this.#sending.set(reject, resolve);
+        const settle = (complete, value) => {
+          this.#sending.delete(reject);
+          complete(value);
+        };
+        try {
+          Promise.resolve(send(bytes)).then(
+            (value) => settle(resolve, value),
+            (error) => settle(reject, error)
+          );
+        } catch (error) {
+          settle(reject, error);
+        }
+      });
     };
     if (signal) {
       if (signal.aborted) this.fail(new MarctlError('Copy was interrupted.'));
@@ -92,11 +108,21 @@ class ByteChannel {
 
   finish(code) {
     this.#ended = code;
+    if (code !== 0) return this.fail(new MarctlError('Remote copy command failed.'));
+    // A successful exit confirms the worker consumed its final protocol input.
+    for (const resolve of this.#sending.values()) resolve();
+    this.#sending.clear();
     this.#wake();
   }
 
+  connectionEnded(error) {
+    if (this.#ended === undefined) this.fail(error);
+  }
+
   fail(error) {
     this.#failure ??= error;
+    for (const reject of this.#sending.keys()) reject(this.#failure);
+    this.#sending.clear();
     this.#wake();
   }
 
@@ -231,9 +257,9 @@ async function withRemoteWorker(
         }
       };
       const onError = () =>
-        channel.fail(new MarctlError(translate('errors.terminalConnectionFailed')));
+        channel.connectionEnded(new MarctlError(translate('errors.terminalConnectionFailed')));
       const onClose = () =>
-        channel.fail(new MarctlError(translate('errors.terminalConnectionLost')));
+        channel.connectionEnded(new MarctlError(translate('errors.terminalConnectionLost')));
       transport.on('message', onMessage);
       transport.on('error', onError);
       transport.on('close', onClose);

package/src/terminal-relay-sender.d.mts

@@ -0,0 +1,17 @@
+interface RelaySocket {
+  readonly readyState: number;
+  readonly bufferedAmount?: number;
+  send(value: string, callback: (error?: Error) => void): void;
+}
+
+export class TerminalRelaySender {
+  constructor(
+    socket: RelaySocket,
+    options?: {
+      readonly onPendingChange?: (keys: ReadonlySet<string>) => void;
+    }
+  );
+  send(value: string, key?: string): Promise<void>;
+  cancel(key: string): void;
+  close(error?: Error): void;
+}

package/src/terminal-relay-sender.mjs

@@ -0,0 +1,129 @@
+const MAX_PENDING_BYTES = 2 * 1024 * 1024;
+const MAX_SOCKET_BYTES = 256 * 1024;
+
+/** Shared sender for CLI input and the Node's aggregate Terminal relay output. */
+export class TerminalRelaySender {
+  #socket;
+  #onPendingChange;
+  #pending = [];
+  #pendingBytes = 0;
+  #inFlight;
+  #timer;
+  #immediate;
+  #closed = false;
+
+  constructor(socket, { onPendingChange = () => {} } = {}) {
+    this.#socket = socket;
+    this.#onPendingChange = onPendingChange;
+  }
+
+  send(value, key = '') {
+    if (this.#closed || this.#socket.readyState !== 1)
+      return Promise.reject(new Error('TERMINAL_CONNECTION_LOST'));
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (this.#pendingBytes + bytes > MAX_PENDING_BYTES)
+      return Promise.reject(
+        Object.assign(new Error('TERMINAL_RELAY_BUFFER_EXCEEDED'), {
+          code: 'TERMINAL_RELAY_BUFFER_EXCEEDED'
+        })
+      );
+    const result = new Promise((resolve, reject) => {
+      this.#pending.push({ value, key, bytes, resolve, reject });
+      this.#pendingBytes += bytes;
+    });
+    this.#pump();
+    this.#notify();
+    return result;
+  }
+
+  cancel(key) {
+    if (this.#inFlight?.key === key) {
+      this.#inFlight.cancelled = true;
+      this.#inFlight.reject(new Error('TERMINAL_ATTACH_INVALID'));
+    }
+    const kept = [];
+    for (const item of this.#pending) {
+      if (item.key !== key) kept.push(item);
+      else {
+        this.#pendingBytes -= item.bytes;
+        item.reject(new Error('TERMINAL_ATTACH_INVALID'));
+      }
+    }
+    this.#pending = kept;
+    if (kept.length === 0) this.#clearScheduled();
+    this.#notify();
+  }
+
+  close(error = new Error('TERMINAL_CONNECTION_LOST')) {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#clearScheduled();
+    this.#inFlight?.reject(error);
+    this.#inFlight = undefined;
+    for (const item of this.#pending) item.reject(error);
+    this.#pending = [];
+    this.#pendingBytes = 0;
+    this.#notify();
+  }
+
+  #pump() {
+    if (
+      this.#closed ||
+      this.#inFlight !== undefined ||
+      this.#timer !== undefined ||
+      this.#immediate !== undefined ||
+      this.#pending.length === 0
+    )
+      return;
+    if (this.#socket.readyState !== 1) {
+      this.close();
+      return;
+    }
+    const buffered = this.#socket.bufferedAmount ?? 0;
+    if (buffered > 0 && buffered + this.#pending[0].bytes > MAX_SOCKET_BYTES) {
+      // Poll only while the transport is congested; there is no throughput timer.
+      this.#timer = setTimeout(() => {
+        this.#timer = undefined;
+        this.#pump();
+        this.#notify();
+      }, 20);
+      return;
+    }
+    const item = this.#pending.shift();
+    this.#inFlight = item;
+    try {
+      this.#socket.send(item.value, (error) => {
+        if (this.#inFlight !== item) return;
+        if (error) {
+          this.close(error);
+          return;
+        }
+        this.#inFlight = undefined;
+        this.#pendingBytes -= item.bytes;
+        // Even a synchronous write callback must yield before the next frame.
+        this.#immediate = setImmediate(() => {
+          this.#immediate = undefined;
+          this.#pump();
+          this.#notify();
+        });
+        item.resolve();
+        this.#notify();
+      });
+    } catch (error) {
+      this.close(error);
+    }
+  }
+
+  #notify() {
+    const keys = new Set(this.#pending.map((item) => item.key));
+    if (this.#inFlight !== undefined && !this.#inFlight.cancelled) keys.add(this.#inFlight.key);
+    this.#onPendingChange(keys);
+  }
+
+  #clearScheduled() {
+    clearTimeout(this.#timer);
+    this.#timer = undefined;
+    clearImmediate(this.#immediate);
+    this.#immediate = undefined;
+  }
+}

package/src/terminal.mjs

@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events';
 import { MarctlError } from './config.mjs';
 import { createTranslator } from './i18n/index.mjs';
+import { TerminalRelaySender } from './terminal-relay-sender.mjs';
 
 const MAX_INPUT_BYTES = 65536;
 const DEFAULT_ROWS = 24;
@@ -27,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,
@@ -46,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,
@@ -136,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) => {
@@ -152,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,
@@ -166,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,
@@ -252,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,
@@ -328,6 +356,7 @@ async function prepareRelayTransport({
 
 class BufferedRelayTransport extends EventEmitter {
   #socket;
+  #sender;
   #terminalId;
   #translate;
   #attached = false;
@@ -346,6 +375,7 @@ class BufferedRelayTransport extends EventEmitter {
   constructor({ socket, terminalId, translate, connectionTimeoutMs }) {
     super();
     this.#socket = socket;
+    this.#sender = new TerminalRelaySender(socket);
     this.#terminalId = terminalId;
     this.#translate = translate;
     this.#onOpen = () => {
@@ -388,6 +418,7 @@ class BufferedRelayTransport extends EventEmitter {
       else this.#fail(error);
     };
     this.#onClose = () => {
+      this.#sender.close();
       const error = new MarctlError(
         this.#translate(
           this.#attached ? 'errors.terminalConnectionLost' : 'errors.terminalAttachLost'
@@ -439,12 +470,14 @@ class BufferedRelayTransport extends EventEmitter {
 
   send(value) {
     if (this.#closed) throw new Error('TERMINAL_CONNECTION_LOST');
+    if (JSON.parse(value).type === 'input') return this.#sender.send(value);
     this.#socket.send(value);
   }
 
   close() {
     if (this.#closed) return;
     this.#closed = true;
+    this.#sender.close();
     clearTimeout(this.#openTimer);
     clearTimeout(this.#attachTimer);
     this.#socket.removeListener?.('open', this.#onOpen);
@@ -499,6 +532,7 @@ function runAttachedTerminal({
     let settled = false;
     let inputEnabled = false;
     let rawModeEnabled = false;
+    let inputTasks = 0;
 
     const cleanup = () => {
       transport.removeListener?.('message', onMessage);
@@ -529,13 +563,21 @@ function runAttachedTerminal({
     };
     const fail = (key) => finish(new MarctlError(translate(key)));
     const send = (frame) => {
-      transport.send(JSON.stringify(frame));
+      return transport.send(JSON.stringify(frame));
     };
-    const onInput = (data) => {
+    const onInput = async (data) => {
+      inputTasks += 1;
+      stdin.pause?.();
       try {
-        for (const chunk of splitInput(data)) send({ type: 'input', terminalId, data: chunk });
+        for (const chunk of splitInput(data)) {
+          if (settled) return;
+          await send({ type: 'input', terminalId, data: chunk });
+        }
       } catch {
         fail('errors.terminalInputFailed');
+      } finally {
+        inputTasks -= 1;
+        if (!settled && inputTasks === 0) stdin.resume?.();
       }
     };
     const onResize = () => {