@myagentroam/node 0.12.0 → 0.12.1

package/dist/marctl/src/sessions.mjs

@@ -0,0 +1,93 @@
+import { MarctlError } from './errors.mjs';
+import { sessionTarget } from './session-target.mjs';
+import {
+  isAgentNetworkAction,
+  prepareAgentNetworkRequest,
+  prepareSessionRequest
+} from './session-prepare.mjs';
+import { waitForSessionRun } from './session-wait.mjs';
+
+export async function runSessionCommand({
+  args,
+  client,
+  env,
+  stdin,
+  WebSocketClass,
+  translate,
+  signal
+}) {
+  args = { ...args, ...(args.images === undefined ? {} : { images: [...args.images] }) };
+  const targeted = sessionTarget[args.action] !== 'workspace';
+  const sessionId =
+    args.sessionId ??
+    (sessionTarget[args.action] === 'current' ? env.MAR_CTL_SESSION_ID : undefined);
+  if (targeted && !sessionId && sessionTarget[args.action] !== 'optional')
+    throw new MarctlError(translate('errors.sessionContextRequired'), {
+      code: 'MARCTL_SESSION_CONTEXT_REQUIRED'
+    });
+  if (args.action === 'wait' && args.runId !== undefined)
+    return waitForSessionRun({
+      client,
+      sessionId,
+      runId: args.runId,
+      timeoutMs: args.timeoutMs ?? 30000,
+      until: args.until,
+      WebSocketClass,
+      translate,
+      signal
+    });
+  const network = isAgentNetworkAction(args.action);
+  const body = network
+    ? await prepareAgentNetworkRequest({ args, stdin, translate, sessionId })
+    : await prepareSessionRequest({ args, env, stdin, translate, sessionId, targeted });
+  const clientMessageId = network ? body.command.input.clientMessageId : body.clientMessageId;
+  try {
+    const requestedWait = args.timeoutMs ?? 30000;
+    const effectiveWait = requestedWait === 0 ? 0 : Math.max(10000, requestedWait);
+    const result = await client.sessionCommand(
+      body,
+      args.action === 'wait' ? { timeoutMs: effectiveWait + 10000, signal } : undefined
+    );
+    return {
+      ...result,
+      ...(typeof result?.session?.id === 'string' ? { sessionId: result.session.id } : {}),
+      ...(typeof result?.run?.id === 'string' ? { runId: result.run.id } : {}),
+      ...(clientMessageId === undefined ? {} : { clientMessageId })
+    };
+  } catch (error) {
+    if (clientMessageId !== undefined) error.clientMessageId = clientMessageId;
+    if (
+      [
+        'start',
+        'send',
+        'config',
+        'rename',
+        'prompt.set',
+        'prompt.clear',
+        'approval.decide',
+        'schedule.create',
+        'schedule.update',
+        'stop',
+        'goal.set',
+        'goal.clear'
+      ].includes(args.action) &&
+      ['MARCTL_REQUEST_TIMEOUT', 'MARCTL_SERVER_UNREACHABLE', 'MARCTL_RESPONSE_INVALID'].includes(
+        error.code
+      )
+    ) {
+      error.code = 'MARCTL_OUTCOME_UNKNOWN';
+      error.message = translate('errors.sessionOutcomeUnknown');
+    }
+    throw error;
+  }
+}
+
+export function sessionExitCode(error) {
+  if (error.code === 'MARCTL_SESSION_INPUT_INVALID') return 2;
+  if ([401, 403].includes(error.statusCode)) return 3;
+  if (error.code?.includes('UNSUPPORTED')) return 4;
+  if (error.code === 'MARCTL_WAIT_TIMEOUT' || error.code === 'MARCTL_REQUEST_TIMEOUT') return 5;
+  if (['MARCTL_OUTCOME_UNKNOWN', 'MARCTL_WAIT_UNKNOWN'].includes(error.code)) return 6;
+  if (error.code === 'MARCTL_WAIT_CANCELLED') return 130;
+  return 1;
+}

package/dist/marctl/src/terminal-frame.mjs

@@ -0,0 +1,48 @@
+import { MarctlError } from './errors.mjs';
+
+const MAX_INPUT_BYTES = 65536;
+
+export function parseFrame(raw, isBinary, terminalId, translate) {
+  if (isBinary) throw new MarctlError(translate('errors.terminalBinaryFrame'));
+  let frame;
+  try {
+    frame = JSON.parse(rawToString(raw));
+  } catch {
+    throw new MarctlError(translate('errors.terminalInvalidJson'));
+  }
+  if (frame === null || typeof frame !== 'object' || frame.terminalId !== terminalId)
+    throw new MarctlError(translate('errors.terminalFrameInvalid'));
+
+  if (frame.type === 'attach') {
+    if (!Number.isSafeInteger(frame.afterSequence) || frame.afterSequence < 0)
+      throw new MarctlError(translate('errors.terminalFrameInvalid'));
+    return frame;
+  }
+  if (frame.type === 'output') {
+    if (
+      !Number.isSafeInteger(frame.sequence) ||
+      frame.sequence < 1 ||
+      typeof frame.data !== 'string' ||
+      Buffer.byteLength(frame.data) > MAX_INPUT_BYTES
+    )
+      throw new MarctlError(translate('errors.terminalFrameInvalid'));
+    return frame;
+  }
+  if (frame.type === 'exit') {
+    if (frame.exitCode !== null && !Number.isSafeInteger(frame.exitCode))
+      throw new MarctlError(translate('errors.terminalFrameInvalid'));
+    return frame;
+  }
+  if (frame.type === 'error' && typeof frame.code === 'string' && frame.code.length > 0)
+    return frame;
+  throw new MarctlError(translate('errors.terminalFrameInvalid'));
+}
+
+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);
+}

package/dist/marctl/src/terminal-interaction.mjs

@@ -0,0 +1,177 @@
+import { MarctlError } from './errors.mjs';
+import { DirectRejectedError } from './direct-errors.mjs';
+import { parseFrame } from './terminal-frame.mjs';
+
+const MAX_INPUT_BYTES = 65536;
+const DEFAULT_ROWS = 24;
+const DEFAULT_COLS = 80;
+
+export function splitInput(text, maxBytes = MAX_INPUT_BYTES) {
+  const value = Buffer.isBuffer(text) ? text.toString('utf8') : String(text);
+  const chunks = [];
+  let chunk = '';
+  let chunkBytes = 0;
+
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character);
+    if (chunk !== '' && chunkBytes + characterBytes > maxBytes) {
+      chunks.push(chunk);
+      chunk = '';
+      chunkBytes = 0;
+    }
+    if (characterBytes > maxBytes) continue;
+    chunk += character;
+    chunkBytes += characterBytes;
+  }
+  if (chunk !== '') chunks.push(chunk);
+  return chunks;
+}
+
+export function runAttachedTerminal({
+  transport,
+  terminalId,
+  commandMode,
+  stdin,
+  stdout,
+  signal,
+  translate
+}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let inputEnabled = false;
+    let rawModeEnabled = false;
+    let inputTasks = 0;
+
+    const cleanup = () => {
+      transport.removeListener?.('message', onMessage);
+      transport.removeListener?.('error', onError);
+      transport.removeListener?.('close', onClose);
+      stdin.removeListener?.('data', onInput);
+      stdout.removeListener?.('resize', onResize);
+      signal?.removeEventListener('abort', onAbort);
+      if (rawModeEnabled) {
+        try {
+          stdin.setRawMode(false);
+        } catch {
+          // The terminal may already be gone.
+        }
+      }
+      stdin.pause?.();
+    };
+
+    const finish = (error, exitCode) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      sendCloseFrame(transport, terminalId);
+      transport.close?.();
+      if (error === undefined) resolve(exitCode);
+      else reject(error);
+    };
+    const fail = (key) => finish(new MarctlError(translate(key)));
+    const send = (frame) => {
+      return transport.send(JSON.stringify(frame));
+    };
+    const onInput = async (data) => {
+      inputTasks += 1;
+      stdin.pause?.();
+      try {
+        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 = () => {
+      try {
+        const { rows, cols } = getDimensions(stdout);
+        Promise.resolve(send({ type: 'resize', terminalId, rows, cols })).catch(() =>
+          fail('errors.terminalResizeFailed')
+        );
+      } catch {
+        fail('errors.terminalResizeFailed');
+      }
+    };
+    const onMessage = (raw, isBinary) => {
+      try {
+        const frame = parseFrame(raw, isBinary, terminalId, translate);
+        if (frame.type === 'output') stdout.write(frame.data);
+        else if (frame.type === 'exit') {
+          finish(undefined, frame.exitCode === null ? 1 : frame.exitCode);
+        } else if (frame.type === 'error') fail('errors.terminalRemoteError');
+        else fail('errors.terminalUnexpectedFrame');
+      } catch (error) {
+        finish(
+          error instanceof MarctlError
+            ? error
+            : new MarctlError(translate('errors.terminalFrameInvalid'))
+        );
+      }
+    };
+    const onError = (error) =>
+      finish(
+        error instanceof DirectRejectedError
+          ? new MarctlError(`${translate('errors.terminalConnectionFailed')} [${error.code}]`, {
+              code: error.code
+            })
+          : new MarctlError(translate('errors.terminalConnectionFailed'))
+      );
+    const onClose = () => finish(new MarctlError(translate('errors.terminalConnectionLost')));
+    const onAbort = () => finish(undefined, signal.reason === 'SIGTERM' ? 143 : 130);
+    const startInput = () => {
+      if (settled || inputEnabled) return;
+      inputEnabled = true;
+      try {
+        if (!commandMode) {
+          if (typeof stdin.setRawMode !== 'function') {
+            fail('errors.terminalInteractiveRequired');
+            return;
+          }
+          stdin.setRawMode(true);
+          rawModeEnabled = true;
+        }
+        stdin.resume?.();
+        stdin.on?.('data', onInput);
+        stdout.on?.('resize', onResize);
+        onResize();
+      } catch {
+        fail(commandMode ? 'errors.terminalSessionFailed' : 'errors.terminalInteractiveInit');
+      }
+    };
+    transport.on?.('message', onMessage);
+    transport.on?.('error', onError);
+    transport.on?.('close', onClose);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) {
+      onAbort();
+      return;
+    }
+    transport.activate?.();
+    startInput();
+  });
+}
+
+function sendCloseFrame(socket, terminalId) {
+  if (!terminalId || !isSocketOpen(socket)) return;
+  try {
+    Promise.resolve(socket.send(JSON.stringify({ type: 'close', terminalId }))).catch(() => {});
+  } catch {
+    // The DELETE request below remains the authoritative cleanup path.
+  }
+}
+
+function isSocketOpen(socket) {
+  return socket.readyState === undefined || socket.readyState === 1;
+}
+
+export function getDimensions(stdout) {
+  const rows = Number.isSafeInteger(stdout.rows) && stdout.rows > 0 ? stdout.rows : DEFAULT_ROWS;
+  const cols =
+    Number.isSafeInteger(stdout.columns) && stdout.columns > 0 ? stdout.columns : DEFAULT_COLS;
+  return { rows: Math.min(rows, 1000), cols: Math.min(cols, 1000) };
+}

package/dist/marctl/src/terminal-race.mjs

@@ -0,0 +1,117 @@
+import { prepareRelayTransport } from './terminal-relay.mjs';
+import { DirectFallbackError, DirectRejectedError } from './direct-errors.mjs';
+
+export async function raceTerminalConnections({
+  openDirectTerminal,
+  directOptions,
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs,
+  signal
+}) {
+  if (signal?.aborted) throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+  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) => {
+    announce = resolve;
+  });
+  const select = (candidate) => {
+    if (selected) return false;
+    selected = candidate;
+    announce(candidate);
+    if (candidate === 'relay') abort.abort();
+    else relayAbort.abort();
+    return true;
+  };
+  const cancel = () => {
+    abort.abort();
+    relayAbort.abort();
+    if (selected) return;
+    selected = 'cancel';
+    start();
+    announce('cancel');
+  };
+  signal?.addEventListener('abort', cancel, { once: true });
+  const direct = openDirectTerminal({
+    ...directOptions,
+    signal: abort.signal,
+    onPrepared: () => prepared('direct'),
+    onRejected: () => select('direct'),
+    onIceConnected: () => {
+      if (!select('direct')) throw new Error('DIRECT_RACE_CANCELLED');
+    },
+    onTransportReady: () => {
+      if (selected !== 'direct') throw new Error('DIRECT_RACE_CANCELLED');
+    }
+  }).then(
+    (value) => {
+      if (selected === 'cancel' || signal?.aborted) value.close();
+      return { value };
+    },
+    (error) => {
+      prepared('direct');
+      if (error instanceof DirectRejectedError) select('direct');
+      return { error };
+    }
+  );
+  const relay = prepareRelayTransport({
+    client,
+    WebSocketClass,
+    nodeId,
+    terminalId,
+    translate,
+    connectionTimeoutMs,
+    signal: relayAbort.signal,
+    onPrepared: () => prepared('relay')
+  }).then(
+    (value) => {
+      if (!select('relay')) value.close();
+      return { value };
+    },
+    (error) => {
+      prepared('relay');
+      return { error };
+    }
+  );
+  const winner = await Promise.race([
+    first,
+    Promise.all([direct, relay]).then(() => selected ?? 'none')
+  ]);
+  if (winner === 'cancel' || signal?.aborted) {
+    signal?.removeEventListener('abort', cancel);
+    abort.abort();
+    relayAbort.abort();
+    throw new DirectFallbackError('DIRECT_RACE_CANCELLED');
+  }
+  if (winner === 'direct') {
+    const result = await direct;
+    signal?.removeEventListener('abort', cancel);
+    if (result.error) throw result.error;
+    return result.value;
+  }
+  if (winner === 'relay') {
+    const result = await relay;
+    signal?.removeEventListener('abort', cancel);
+    if (result.error) throw result.error;
+    return result.value.activate(signal);
+  }
+  const [directResult, relayResult] = await Promise.all([direct, relay]);
+  signal?.removeEventListener('abort', cancel);
+  if (directResult.error instanceof DirectRejectedError) throw directResult.error;
+  throw relayResult.error ?? directResult.error;
+}

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