@myagentroam/marctl 0.11.3 → 0.11.5

package/package.json

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

package/src/cli.mjs

@@ -1,10 +1,26 @@
 import { readFile } from 'node:fs/promises';
 import { MarctlClient } from './client.mjs';
-import { MarctlError, loadConfig } from './config.mjs';
+import { loadConfig } from './config.mjs';
+import { MarctlError } from './errors.mjs';
 import { createTranslator } from './i18n/index.mjs';
 import { runTerminalSession } from './terminal.mjs';
 import { runScp } from './scp.mjs';
-import { parseSessionArgs, runSessionCommand, sessionExitCode } from './sessions.mjs';
+import { parseSessionArgs } from './session-args.mjs';
+import { runSessionCommand, sessionExitCode } from './sessions.mjs';
+
+async function withCommandSignals(run) {
+  const controller = new AbortController();
+  const onSigint = () => controller.abort('SIGINT');
+  const onSigterm = () => controller.abort('SIGTERM');
+  process.once('SIGINT', onSigint);
+  process.once('SIGTERM', onSigterm);
+  try {
+    return await run(controller.signal);
+  } finally {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+  }
+}
 
 export async function main(
   argv = process.argv.slice(2),
@@ -59,45 +75,54 @@ export async function main(
       }
       return 0;
     }
-    if (args.command === 'sessions') {
-      const result = await runSessionCommand({
-        args,
-        client: marctlClient,
-        env,
-        stdin,
-        WebSocketClass,
-        translate
-      });
+    if (args.command === 'agents') {
+      const execute = (signal) =>
+        runSessionCommand({
+          args,
+          client: marctlClient,
+          env,
+          stdin,
+          WebSocketClass,
+          translate,
+          signal
+        });
+      const result = args.action === 'wait' ? await withCommandSignals(execute) : await execute();
       writeLine(stdout, JSON.stringify(result, null, args.json ? undefined : 2));
       return 0;
     }
     if (args.command === 'scp') {
       const socketClass = WebSocketClass ?? (await import('ws')).default;
-      return await runScp({
-        source: args.source,
-        destination: args.destination,
-        preserve: args.preserve,
-        client: marctlClient,
-        WebSocketClass: socketClass,
-        resolveNodeId: (reference) => resolveNodeId(marctlClient, reference, translate),
-        translate
-      });
+      return await withCommandSignals((signal) =>
+        runScp({
+          source: args.source,
+          destination: args.destination,
+          preserve: args.preserve,
+          client: marctlClient,
+          WebSocketClass: socketClass,
+          resolveNodeId: (reference) => resolveNodeId(marctlClient, reference, translate),
+          translate,
+          signal
+        })
+      );
     }
 
     const nodeId = await resolveNodeId(marctlClient, args.nodeId, translate);
     const socketClass = WebSocketClass ?? (await import('ws')).default;
-    return await runTerminalSession({
-      client: marctlClient,
-      WebSocketClass: socketClass,
-      nodeId,
-      command: args.remoteCommand,
-      raceConnections: true,
-      stdout,
-      stderr,
-      translate
-    });
+    return await withCommandSignals((signal) =>
+      runTerminalSession({
+        client: marctlClient,
+        WebSocketClass: socketClass,
+        nodeId,
+        command: args.remoteCommand,
+        raceConnections: true,
+        stdout,
+        stderr,
+        translate,
+        signal
+      })
+    );
   } catch (error) {
-    if (argv[0] === 'sessions') {
+    if (argv[0] === 'agents') {
       const failure = {
         code: error.code ?? 'MARCTL_COMMAND_FAILED',
         message: error instanceof MarctlError ? error.message : translate('errors.commandFailed'),
@@ -151,7 +176,7 @@ export function executableArgs(executable, args) {
 }
 
 export function parseArgs(argv, translate = createTranslator()) {
-  if (argv[0] === 'sessions') return parseSessionArgs(argv.slice(1), translate);
+  if (argv[0] === 'agents') return parseSessionArgs(argv.slice(1), translate);
   let command;
   let nodeId;
   const remoteArgs = [];
@@ -183,7 +208,7 @@ export function parseArgs(argv, translate = createTranslator()) {
         argument !== 'nodes' &&
         argument !== 'ssh' &&
         argument !== 'scp' &&
-        argument !== 'sessions' &&
+        argument !== 'agents' &&
         argument !== 'version'
       )
         throw unsupportedSshOption(argument, translate);

package/src/client.mjs

@@ -1,4 +1,4 @@
-import { MarctlError } from './config.mjs';
+import { MarctlError } from './errors.mjs';
 import { createTranslator } from './i18n/index.mjs';
 
 const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
@@ -49,11 +49,13 @@ export class MarctlClient {
     });
   }
 
-  async sessionCommand(body) {
+  async sessionCommand(body, { timeoutMs, signal } = {}) {
     const result = await this.#requestJson('/api/marctl/sessions', {
       method: 'POST',
       body,
-      preserveError: true
+      preserveError: true,
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      ...(signal === undefined ? {} : { signal })
     });
     if (!isRecord(result))
       throw new MarctlError(this.#translate('errors.serverInvalidJson'), {
@@ -171,19 +173,33 @@ export class MarctlClient {
     return this.#request(pathname, { ...options, json: true });
   }
 
-  async #request(pathname, { method = 'GET', body, json = false, preserveError = false } = {}) {
+  async #request(
+    pathname,
+    {
+      method = 'GET',
+      body,
+      json = false,
+      preserveError = false,
+      timeoutMs = this.#requestTimeoutMs,
+      signal
+    } = {}
+  ) {
     const headers = {
       Accept: 'application/json',
       Authorization: `Bearer ${this.#key}`
     };
     const controller = new AbortController();
-    const request = { method, headers, signal: controller.signal };
+    const request = {
+      method,
+      headers,
+      signal: signal ? AbortSignal.any([controller.signal, signal]) : controller.signal
+    };
     if (body !== undefined) {
       headers['Content-Type'] = 'application/json';
       request.body = JSON.stringify(body);
     }
 
-    const timer = setTimeout(() => controller.abort(), this.#requestTimeoutMs);
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
       const response = await this.#fetch(new URL(pathname, `${this.#serverUrl}/`), request);
       if (!response?.ok) {
@@ -227,6 +243,10 @@ export class MarctlClient {
         );
       }
     } catch (error) {
+      if (signal?.aborted)
+        throw new MarctlError(this.#translate('errors.sessionWaitCancelled'), {
+          code: 'MARCTL_WAIT_CANCELLED'
+        });
       if (error instanceof MarctlError) throw error;
       throw new MarctlError(
         this.#translate(

package/src/config.mjs

@@ -1,16 +1,6 @@
 import { createTranslator } from './i18n/index.mjs';
 
-export class MarctlError extends Error {
-  constructor(message, options = {}) {
-    super(message, options);
-    this.name = 'MarctlError';
-    this.code = options.code;
-    this.requestId = options.requestId;
-    this.upstreamRequestId = options.upstreamRequestId;
-    this.details = options.details;
-    this.statusCode = options.statusCode;
-  }
-}
+import { MarctlError } from './errors.mjs';
 
 export async function loadConfig({ env = process.env, translate = createTranslator(env) } = {}) {
   const serverUrl = nonEmptyString(env.MAR_CTL_SERVER_URL);

package/src/direct-control.mjs

@@ -0,0 +1,225 @@
+import { DirectFallbackError, directControlError } from './direct-errors.mjs';
+
+export class LiveControl {
+  #socket;
+  #timeoutMs;
+  #ready = false;
+  #closed = false;
+  #waiters = new Set();
+  #listeners = new Set();
+  #onMessage;
+  #onError;
+  #onClose;
+
+  constructor(socket, timeoutMs) {
+    this.#socket = socket;
+    this.#timeoutMs = timeoutMs;
+    this.#onMessage = (raw, isBinary) => {
+      if (isBinary) return;
+      let message;
+      try {
+        message = JSON.parse(rawToString(raw));
+      } catch {
+        return;
+      }
+      if (!isRecord(message) || typeof message.type !== 'string') return;
+      for (const listener of this.#listeners) listener(message);
+      for (const waiter of [...this.#waiters]) {
+        if (
+          ((waiter.request?.type === 'terminal.direct.prepare' &&
+            message.type === 'terminal.direct.error') ||
+            (waiter.request?.type === 'direct.prepare' && message.type === 'direct.error')) &&
+          message.requestId === waiter.request.requestId
+        ) {
+          this.#waiters.delete(waiter);
+          clearTimeout(waiter.timer);
+          waiter.reject(directControlError(message.code));
+          continue;
+        }
+        if (!waiter.predicate(message, waiter.request)) continue;
+        this.#waiters.delete(waiter);
+        clearTimeout(waiter.timer);
+        waiter.resolve(message);
+      }
+    };
+    this.#onError = () => this.#fail(new DirectFallbackError('DIRECT_CONTROL_UNAVAILABLE'));
+    this.#onClose = () => this.#fail(new DirectFallbackError('DIRECT_CONTROL_CLOSED'));
+    socket.on?.('message', this.#onMessage);
+    socket.on?.('error', this.#onError);
+    socket.on?.('close', this.#onClose);
+  }
+
+  async openAndResume() {
+    await this.#waitForSocket('open', 'DIRECT_CONTROL_TIMEOUT');
+    const ready = this.waitFor(
+      (message) =>
+        message.type === 'workbench.ready' && typeof message.workbenchConnectionId === 'string',
+      undefined,
+      'DIRECT_RESUME_TIMEOUT'
+    );
+    if (!this.send({ type: 'resume' })) {
+      ready.catch(() => undefined);
+      throw new DirectFallbackError('DIRECT_CONTROL_UNAVAILABLE');
+    }
+    await ready;
+    this.#ready = true;
+  }
+
+  request(message, predicate, fallbackCode) {
+    if (!this.#ready) throw new DirectFallbackError('DIRECT_CONTROL_UNAVAILABLE');
+    const response = this.waitFor(predicate, message, fallbackCode);
+    if (!this.send(message)) {
+      response.catch(() => undefined);
+      throw new DirectFallbackError('DIRECT_CONTROL_UNAVAILABLE');
+    }
+    return response;
+  }
+
+  waitFor(predicate, request, fallbackCode, timeoutMs = this.#timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (this.#closed) {
+        reject(new DirectFallbackError('DIRECT_CONTROL_CLOSED'));
+        return;
+      }
+      const waiter = {
+        predicate,
+        request,
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.#waiters.delete(waiter);
+          reject(new DirectFallbackError(fallbackCode ?? 'DIRECT_SETUP_TIMEOUT'));
+        }, timeoutMs)
+      };
+      this.#waiters.add(waiter);
+    });
+  }
+
+  onControl(listener) {
+    if (this.#closed) return () => {};
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  send(message) {
+    if (this.#closed || (this.#socket.readyState !== undefined && this.#socket.readyState !== 1))
+      return false;
+    try {
+      this.#socket.send(JSON.stringify(message));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#fail(new DirectFallbackError('DIRECT_CONTROL_CLOSED'));
+    this.#listeners.clear();
+    this.#socket.removeListener?.('message', this.#onMessage);
+    this.#socket.removeListener?.('error', this.#onError);
+    this.#socket.removeListener?.('close', this.#onClose);
+    try {
+      this.#socket.close();
+    } catch {
+      // The control socket is already closed.
+    }
+  }
+
+  #waitForSocket(event, code) {
+    if (this.#socket.readyState === 1) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const onEvent = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = () => {
+        cleanup();
+        reject(new DirectFallbackError(code));
+      };
+      const onClose = () => {
+        cleanup();
+        reject(new DirectFallbackError(code));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new DirectFallbackError(code));
+      }, this.#timeoutMs);
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.#socket.removeListener?.(event, onEvent);
+        this.#socket.removeListener?.('error', onError);
+        this.#socket.removeListener?.('close', onClose);
+      };
+      this.#socket.once?.(event, onEvent);
+      this.#socket.once?.('error', onError);
+      this.#socket.once?.('close', onClose);
+    });
+  }
+
+  #fail(error) {
+    if (this.#closed && this.#waiters.size === 0) return;
+    for (const waiter of [...this.#waiters]) {
+      this.#waiters.delete(waiter);
+      clearTimeout(waiter.timer);
+      waiter.reject(error);
+    }
+  }
+}
+
+export async function cancelSession(live, type, directSessionId) {
+  if (live === undefined) return;
+  const closed = live.waitFor(
+    (message) =>
+      message.type === `${type.replace('.cancel', '.closed')}` &&
+      message.directSessionId === directSessionId,
+    undefined,
+    'DIRECT_CANCEL_TIMEOUT',
+    1000
+  );
+  live.send({
+    type,
+    directSessionId,
+    ...(type === 'direct.cancel' ? { reason: 'CLI_FALLBACK' } : {})
+  });
+  await closed.catch(() => undefined);
+}
+
+export function withTimeout(promise, timeoutMs, code, signal) {
+  let timer;
+  let onAbort;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new DirectFallbackError(code)), timeoutMs);
+    }),
+    ...(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);
+  });
+}
+
+export function rawToString(raw) {
+  if (typeof raw === 'string') return raw;
+  if (Buffer.isBuffer(raw)) return raw.toString('utf8');
+  if (raw instanceof ArrayBuffer) return Buffer.from(raw).toString('utf8');
+  if (ArrayBuffer.isView(raw))
+    return Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength).toString('utf8');
+  return String(raw);
+}
+
+export function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/src/direct-errors.mjs

@@ -0,0 +1,48 @@
+export class DirectFallbackError extends Error {
+  constructor(code = 'DIRECT_UNAVAILABLE') {
+    super(code);
+    this.name = 'DirectFallbackError';
+    this.code = code;
+  }
+}
+
+export class DirectUnsafeError extends Error {
+  constructor(code = 'DIRECT_CANCEL_UNCONFIRMED') {
+    super(code);
+    this.name = 'DirectUnsafeError';
+    this.code = code;
+  }
+}
+
+const directRejections = new Set([
+  'DIRECT_TRANSFER_NOT_AUTHORIZED',
+  'DIRECT_SESSION_LIMIT_REACHED',
+  'DIRECT_NODE_GENERATION_MISMATCH',
+  'DIRECT_TRANSFER_SESSION_CONFLICT',
+  'TERMINAL_NOT_AUTHORIZED',
+  'TERMINAL_DIRECT_LEASE_EXPIRED',
+  'TERMINAL_NOT_FOUND',
+  'TERMINAL_CLOSED',
+  'TERMINAL_WORKSPACE_MISMATCH',
+  'TERMINAL_GIT_OWNER_REQUIRED',
+  'TERMINAL_ATTACH_CONFLICT',
+  'TERMINAL_RELAY_LIMIT_REACHED'
+]);
+
+export class DirectRejectedError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = 'DirectRejectedError';
+    this.code = code;
+  }
+}
+
+export function directControlError(code) {
+  const safeCode =
+    typeof code === 'string' && /^[A-Z][A-Z0-9_]{0,127}$/u.test(code)
+      ? code
+      : 'TERMINAL_DIRECT_UNAVAILABLE';
+  return directRejections.has(safeCode)
+    ? new DirectRejectedError(safeCode)
+    : new DirectFallbackError(safeCode);
+}

package/src/direct-process.mjs

@@ -1,7 +1,12 @@
 import { fork } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { fileURLToPath } from 'node:url';
-import { DirectFallbackError, DirectUnsafeError } from './direct.mjs';
+import {
+  DirectFallbackError,
+  DirectUnsafeError,
+  DirectRejectedError,
+  directControlError
+} from './direct-errors.mjs';
 
 const CLEANUP_TIMEOUT_MS = 1000;
 const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
@@ -113,11 +118,16 @@ export function openDirectTerminalProcess({
         resolve(transport);
       } else if (message.type === 'failure') {
         const error = settled
-          ? new Error(message.code ?? 'TERMINAL_CONNECTION_LOST')
-          : message.name === 'DirectUnsafeError' ||
-              (opening && message.name !== 'DirectFallbackError')
-            ? new DirectUnsafeError(message.code)
-            : new DirectFallbackError(message.code);
+          ? message.name === 'DirectRejectedError' ||
+            directControlError(message.code) instanceof DirectRejectedError
+            ? directControlError(message.code)
+            : new Error(message.code ?? 'TERMINAL_CONNECTION_LOST')
+          : message.name === 'DirectRejectedError'
+            ? directControlError(message.code)
+            : message.name === 'DirectUnsafeError' ||
+                (opening && message.name !== 'DirectFallbackError')
+              ? new DirectUnsafeError(message.code)
+              : new DirectFallbackError(message.code);
         fail(error);
       } else if (message.type === 'frame') {
         transport.frame(message.frame, message.isBinary);
@@ -216,11 +226,13 @@ class IsolatedDirectTransport extends EventEmitter {
     if (this.#closed) return;
     this.#emit(
       'error',
-      new Error(
-        error instanceof DirectFallbackError || error instanceof DirectUnsafeError
-          ? 'TERMINAL_CONNECTION_LOST'
-          : error.message
-      )
+      error instanceof DirectRejectedError
+        ? error
+        : new Error(
+            error instanceof DirectFallbackError || error instanceof DirectUnsafeError
+              ? 'TERMINAL_CONNECTION_LOST'
+              : error.message
+          )
     );
     this.close();
   }
@@ -298,6 +310,7 @@ function runChild() {
         sendIpc(process, { type: 'send.result', id: message.id, code: 'TERMINAL_INPUT_FAILED' });
       }
     } else if (message.type === 'start') {
+      let rejectionSent = false;
       try {
         const { MarctlClient } = await import('./client.mjs');
         const { openDirectTerminal } = await import('./direct.mjs');
@@ -312,6 +325,10 @@ function runChild() {
           peerConnectionFactory: (name, config) => new native.PeerConnection(name, config),
           cleanupNative: cleanup,
           signal: controller.signal,
+          onRejected: (error) => {
+            rejectionSent = true;
+            sendIpc(process, { type: 'failure', name: 'DirectRejectedError', code: error.code });
+          },
           onPrepared: () => callback('prepared'),
           onIceConnected: () => {
             iceSelection = callback('ice');
@@ -328,7 +345,7 @@ function runChild() {
           sendIpc(process, { type: 'frame', frame: String(frame), isBinary }, abort)
         );
         transport.on('error', (error) => {
-          sendIpc(process, { type: 'failure', code: error.message });
+          sendIpc(process, { type: 'failure', code: error.code ?? error.message });
           abort();
         });
         transport.on('close', () => {
@@ -337,11 +354,17 @@ function runChild() {
         });
         transport.activate();
       } catch (error) {
-        sendIpc(process, {
-          type: 'failure',
-          name: error instanceof DirectUnsafeError ? 'DirectUnsafeError' : 'DirectFallbackError',
-          code: error.code ?? 'DIRECT_UNAVAILABLE'
-        });
+        if (!rejectionSent)
+          sendIpc(process, {
+            type: 'failure',
+            name:
+              error instanceof DirectRejectedError
+                ? 'DirectRejectedError'
+                : error instanceof DirectUnsafeError
+                  ? 'DirectUnsafeError'
+                  : 'DirectFallbackError',
+            code: error.code ?? 'DIRECT_UNAVAILABLE'
+          });
         cleanup();
       }
     }