@myagentroam/node 0.12.0 → 0.12.2

package/dist/marctl/src/client.mjs

@@ -0,0 +1,291 @@
+import { MarctlError } from './errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+
+export class MarctlClient {
+  #serverUrl;
+  #key;
+  #fetch;
+  #translate;
+  #requestTimeoutMs;
+
+  constructor({
+    serverUrl,
+    key,
+    fetchImpl = globalThis.fetch,
+    translate = createTranslator(),
+    requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS
+  }) {
+    this.#serverUrl = serverUrl;
+    this.#key = key;
+    this.#fetch = fetchImpl;
+    this.#translate = translate;
+    this.#requestTimeoutMs = requestTimeoutMs;
+    if (typeof this.#fetch !== 'function')
+      throw new MarctlError(this.#translate('errors.fetchUnavailable'));
+  }
+
+  async listNodes() {
+    const payload = await this.#requestJson('/api/marctl/nodes');
+    if (!isRecord(payload) || !Array.isArray(payload.nodes))
+      throw new MarctlError(this.#translate('errors.serverInvalidNodes'));
+
+    return payload.nodes.map((node) => {
+      if (
+        !isRecord(node) ||
+        !isNonEmptyString(node.id) ||
+        typeof node.connected !== 'boolean' ||
+        (node.displayName !== undefined && typeof node.displayName !== 'string') ||
+        (node.platform !== undefined && typeof node.platform !== 'string')
+      )
+        throw new MarctlError(this.#translate('errors.serverInvalidNodes'));
+      return {
+        id: node.id,
+        ...(node.displayName === undefined ? {} : { displayName: node.displayName }),
+        connected: node.connected,
+        ...(node.platform === undefined ? {} : { platform: node.platform })
+      };
+    });
+  }
+
+  async sessionCommand(body, { timeoutMs, signal } = {}) {
+    const result = await this.#requestJson('/api/marctl/sessions', {
+      method: 'POST',
+      body,
+      preserveError: true,
+      ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      ...(signal === undefined ? {} : { signal })
+    });
+    if (!isRecord(result))
+      throw new MarctlError(this.#translate('errors.serverInvalidJson'), {
+        code: 'MARCTL_RESPONSE_INVALID'
+      });
+    return result;
+  }
+
+  async createTerminal({ nodeId, rows, cols, command, binary = false }) {
+    validateNodeId(nodeId, this.#translate);
+    validateDimensions(rows, cols, this.#translate);
+    if (command !== undefined && typeof command !== 'string')
+      throw new MarctlError(this.#translate('errors.terminalCommandInvalid'));
+    const body = { nodeId, rows, cols };
+    if (command !== undefined) body.command = command;
+    if (binary) body.binary = true;
+    const payload = await this.#requestJson('/api/marctl/terminals', {
+      method: 'POST',
+      body
+    });
+    if (!isRecord(payload) || !isNonEmptyString(payload.terminalId))
+      throw new MarctlError(this.#translate('errors.serverInvalidTerminalId'));
+    return binary
+      ? { terminalId: payload.terminalId, binary: payload.binary === true }
+      : payload.terminalId;
+  }
+
+  async getTerminalManifest(nodeId) {
+    validateNodeId(nodeId, this.#translate);
+    const payload = await this.#requestJson(
+      `/api/marctl/nodes/${encodeURIComponent(nodeId)}/manifest`
+    );
+    if (
+      !isRecord(payload) ||
+      !isRecord(payload.manifest) ||
+      !isNonEmptyString(payload.manifest.nodeGeneration)
+    )
+      throw new MarctlError(this.#translate('errors.serverInvalidManifest'));
+    return {
+      ...payload.manifest,
+      ...(payload.deferredRelay === true ? { deferredRelay: true } : {}),
+      ...(payload.binaryTerminal === true ? { binaryTerminal: true } : {})
+    };
+  }
+
+  async openDirectTerminal(options) {
+    const { openDirectTerminalProcess } = await import('./direct-process.mjs');
+    return openDirectTerminalProcess({
+      ...options,
+      connection: { serverUrl: this.#serverUrl, key: this.#key }
+    });
+  }
+
+  async createAttachTicket({ nodeId, terminalId, afterSequence }) {
+    validateNodeId(nodeId, this.#translate);
+    validateTerminalId(terminalId, this.#translate);
+    if (afterSequence !== undefined && (!Number.isSafeInteger(afterSequence) || afterSequence < 0))
+      throw new MarctlError(this.#translate('errors.terminalSequenceInvalid'));
+
+    const body = { nodeId };
+    if (afterSequence !== undefined) body.afterSequence = afterSequence;
+    const payload = await this.#requestJson(
+      `/api/marctl/terminals/${encodeURIComponent(terminalId)}/attach-ticket`,
+      { method: 'POST', body }
+    );
+    if (!isRecord(payload) || !isNonEmptyString(payload.ticket))
+      throw new MarctlError(this.#translate('errors.serverInvalidTicket'));
+    return payload.ticket;
+  }
+
+  async deleteTerminal({ nodeId, terminalId }) {
+    validateNodeId(nodeId, this.#translate);
+    validateTerminalId(terminalId, this.#translate);
+    await this.#request('/api/marctl/terminals/' + encodeURIComponent(terminalId), {
+      method: 'DELETE',
+      body: { nodeId }
+    });
+  }
+
+  openTerminalWebSocket(WebSocketClass, { terminalId, ticket, deferred = false }) {
+    validateTerminalId(terminalId, this.#translate);
+    if (!isNonEmptyString(ticket))
+      throw new MarctlError(this.#translate('errors.terminalTicketInvalid'));
+
+    const url = new URL(
+      `/api/marctl/terminals/${encodeURIComponent(terminalId)}/connect`,
+      `${this.#serverUrl}/`
+    );
+    url.searchParams.set('ticket', ticket);
+    if (deferred) url.searchParams.set('deferred', '1');
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+
+    try {
+      return new WebSocketClass(url.toString(), {
+        headers: { Authorization: `Bearer ${this.#key}` }
+      });
+    } catch {
+      throw new MarctlError(this.#translate('errors.terminalConnectionStart'));
+    }
+  }
+
+  openWorkbenchWebSocket(WebSocketClass) {
+    const url = new URL('/api/marctl/live', `${this.#serverUrl}/`);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    try {
+      return new WebSocketClass(url.toString(), {
+        headers: { Authorization: `Bearer ${this.#key}` }
+      });
+    } catch {
+      throw new MarctlError(this.#translate('errors.workbenchConnectionStart'));
+    }
+  }
+
+  async #requestJson(pathname, options = {}) {
+    return this.#request(pathname, { ...options, json: true });
+  }
+
+  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: 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(), timeoutMs);
+    try {
+      const response = await this.#fetch(new URL(pathname, `${this.#serverUrl}/`), request);
+      if (!response?.ok) {
+        if (preserveError) {
+          const payload = await response?.json().catch(() => undefined);
+          const failure = payload?.error;
+          if (
+            isRecord(failure) &&
+            typeof failure.code === 'string' &&
+            /^[A-Za-z][A-Za-z0-9_]{0,127}$/u.test(failure.code) &&
+            typeof failure.message === 'string'
+          ) {
+            throw new MarctlError(failure.message.slice(0, 2000), {
+              code: failure.code,
+              statusCode: response.status,
+              requestId:
+                typeof failure.requestId === 'string' ? failure.requestId.slice(0, 160) : undefined,
+              upstreamRequestId:
+                typeof failure.upstreamRequestId === 'string'
+                  ? failure.upstreamRequestId.slice(0, 160)
+                  : undefined,
+              details:
+                typeof failure.details === 'string' ? failure.details.slice(0, 4000) : undefined
+            });
+          }
+        }
+        throw new MarctlError(this.#translate('errors.serverRejected'), {
+          code: 'MARCTL_SERVER_REJECTED',
+          statusCode: response?.status
+        });
+      }
+      if (!json) return response;
+      try {
+        return await response.json();
+      } catch {
+        throw new MarctlError(
+          this.#translate(
+            controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverInvalidJson'
+          ),
+          { code: controller.signal.aborted ? 'MARCTL_REQUEST_TIMEOUT' : 'MARCTL_RESPONSE_INVALID' }
+        );
+      }
+    } 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(
+          controller.signal.aborted ? 'errors.serverTimeout' : 'errors.serverUnreachable'
+        ),
+        { code: controller.signal.aborted ? 'MARCTL_REQUEST_TIMEOUT' : 'MARCTL_SERVER_UNREACHABLE' }
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+function validateNodeId(nodeId, translate) {
+  if (!isNonEmptyString(nodeId) || nodeId.length > 128)
+    throw new MarctlError(translate('errors.nodeIdInvalid'));
+}
+
+function validateTerminalId(terminalId, translate) {
+  if (!isNonEmptyString(terminalId) || terminalId.length > 128)
+    throw new MarctlError(translate('errors.terminalIdInvalid'));
+}
+
+function validateDimensions(rows, cols, translate) {
+  if (
+    !Number.isSafeInteger(rows) ||
+    !Number.isSafeInteger(cols) ||
+    rows < 1 ||
+    cols < 1 ||
+    rows > 1000 ||
+    cols > 1000
+  )
+    throw new MarctlError(translate('errors.terminalSizeInvalid'));
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}

package/dist/marctl/src/config.mjs

@@ -0,0 +1,46 @@
+import { createTranslator } from './i18n/index.mjs';
+
+import { MarctlError } from './errors.mjs';
+
+export async function loadConfig({ env = process.env, translate = createTranslator(env) } = {}) {
+  const serverUrl = nonEmptyString(env.MAR_CTL_SERVER_URL);
+  const token = nonEmptyString(env.MAR_CTL_USER_TOKEN);
+  if (
+    env.MAR_CTL_CONTEXT_REQUIRED !== '1' ||
+    serverUrl === undefined ||
+    token === undefined ||
+    token.length > 16_384 ||
+    !/^marctl_user_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{43}$/u.test(token)
+  )
+    throw new MarctlError(translate('errors.userContextUnavailable'), {
+      code: 'UNAUTHENTICATED',
+      statusCode: 401
+    });
+  return Object.freeze({ serverUrl: validateServerUrl(serverUrl, translate), key: token });
+}
+
+export function validateServerUrl(value, translate = createTranslator()) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new MarctlError(translate('errors.serverUrlInvalid'));
+  }
+
+  const isLoopbackHttp =
+    url.protocol === 'http:' &&
+    (url.hostname === 'localhost' ||
+      url.hostname === '127.0.0.1' ||
+      url.hostname === '::1' ||
+      url.hostname === '[::1]');
+  if (url.protocol !== 'https:' && !isLoopbackHttp)
+    throw new MarctlError(translate('errors.serverUrlTransport'));
+  if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+    throw new MarctlError(translate('errors.serverUrlOrigin'));
+
+  return url.origin;
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}

package/dist/marctl/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/dist/marctl/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);
+}