@myagentroam/marmgr 0.9.112

package/src/i18n/en-US.mjs

@@ -0,0 +1,72 @@
+export default Object.freeze({
+  help: `Usage:
+  marmgr [--env-file PATH] nodes
+  marmgr [--env-file PATH] ssh [-t] <node-id> [command [arg...]]
+
+Remote command arguments are joined with spaces like SSH. Quote commands containing spaces.
+Use -- before remote command flags. Only -t is supported; network and identity SSH options are rejected.
+Default config: ~/.marmgr/default.env. On Windows, use %HOME%\\.marmgr\\default.env when HOME is set;
+otherwise marmgr uses the system home directory.
+Connection setup has a bounded timeout. Remote commands have no total or idle timeout.
+If the relay disconnects, marmgr fails without retrying or re-running the command.`,
+  connected: 'connected',
+  disconnected: 'disconnected',
+  errors: Object.freeze({
+    configServerUrlMissing: 'MAR_MGR_SERVER_URL is not configured.',
+    configKeyMissing: 'MAR_MGR_KEY is not configured.',
+    configKeyInvalid: 'MAR_MGR_KEY contains invalid characters.',
+    serverUrlInvalid: 'MAR_MGR_SERVER_URL is invalid.',
+    serverUrlTransport: 'MAR_MGR_SERVER_URL must use HTTPS or loopback HTTP.',
+    serverUrlOrigin: 'MAR_MGR_SERVER_URL must be an origin without credentials or query data.',
+    envFileMissing: 'The requested environment file was not found.',
+    envFileRead: 'The environment file could not be read.',
+    envFileSymlink: 'The environment file must not be a symbolic link. Use chmod 600.',
+    envFileType: 'The environment file must be a regular file. Use chmod 600.',
+    envFilePermissions:
+      'The environment file must be owned by the current user and have mode 0600 or 0400. Use chmod 600.',
+    envFileEntry: 'Invalid environment entry.',
+    envFileUnsupported: 'Unsupported environment variable.',
+    envFileQuoted: 'Invalid quoted environment value.',
+    fetchUnavailable: 'Fetch is unavailable in this Node.js runtime.',
+    serverInvalidNodes: 'The server returned an invalid node list.',
+    serverInvalidManifest: 'The server returned an invalid node manifest.',
+    terminalCommandInvalid: 'The terminal command is invalid.',
+    terminalSequenceInvalid: 'The terminal sequence is invalid.',
+    terminalTicketInvalid: 'The terminal ticket is invalid.',
+    terminalIdInvalid: 'The terminal identifier is invalid.',
+    nodeIdInvalid: 'The node identifier is invalid.',
+    terminalSizeInvalid: 'The terminal size is invalid.',
+    serverInvalidTerminalId: 'The server returned an invalid terminal identifier.',
+    serverInvalidTicket: 'The server returned an invalid terminal ticket.',
+    serverInvalidJson: 'The server returned invalid JSON.',
+    serverTimeout: 'The marmgr server did not respond before the control request timeout.',
+    serverUnreachable: 'The marmgr server could not be reached.',
+    serverRejected: 'The marmgr server rejected the request.',
+    terminalConnectionStart: 'The terminal connection could not be started.',
+    terminalConnectionOpen: 'The terminal connection could not be opened.',
+    terminalAttachTimeout: 'The terminal did not attach before the connection setup timeout.',
+    terminalAttachConnection: 'The terminal connection failed during attachment.',
+    terminalAttachLost: 'The terminal connection was lost during attachment.',
+    terminalRemoteError: 'The remote terminal reported an error.',
+    terminalClosedBeforeAttach: 'The remote terminal closed before attachment.',
+    terminalFrameInvalid: 'The terminal frame was invalid.',
+    terminalInvalidJson: 'The terminal sent invalid JSON.',
+    terminalBinaryFrame: 'The terminal sent an invalid binary frame.',
+    terminalConnectionFailed: 'The terminal connection failed.',
+    terminalConnectionLost: 'The terminal connection was lost.',
+    terminalUnexpectedFrame: 'The remote terminal sent an unexpected frame.',
+    terminalInputFailed: 'The terminal input could not be sent.',
+    terminalResizeFailed: 'The terminal resize could not be sent.',
+    terminalInteractiveRequired: 'An interactive terminal is required.',
+    terminalInteractiveInit: 'The interactive terminal could not be initialized.',
+    terminalCloseFailed: 'The remote terminal could not be closed.',
+    terminalSessionFailed: 'The terminal session failed.',
+    terminalDirectUnsafeFallback:
+      'Direct terminal setup could not be safely canceled after OPEN; relay fallback was skipped.',
+    invalidArguments: 'Invalid command arguments.',
+    envFileValueRequired: 'A value is required for --env-file.',
+    sshTUnsupported: 'SSH option -T is not supported; marmgr always uses a PTY.',
+    sshOnlyT: 'Only SSH option -t is supported; network and identity options are unavailable.',
+    commandFailed: 'The command failed.'
+  })
+});

package/src/i18n/index.mjs

@@ -0,0 +1,20 @@
+import enUS from './en-US.mjs';
+import zhCN from './zh-CN.mjs';
+
+export function localeFromEnv(env = process.env) {
+  const value = String(env.LC_ALL || env.LANG || '').toLowerCase();
+  return value.startsWith('zh_') || value.startsWith('zh-') || value === 'zh' ? 'zh-CN' : 'en-US';
+}
+
+export function createTranslator(env = process.env) {
+  const locale = localeFromEnv(env);
+  const resource = locale === 'zh-CN' ? zhCN : enUS;
+  const translate = (key, params = {}) => {
+    const value = key.split('.').reduce((current, part) => current?.[part], resource);
+    if (typeof value === 'function') return value(params);
+    if (typeof value !== 'string') return key;
+    return value.replace(/\{(\w+)\}/gu, (_match, name) => String(params[name] ?? ''));
+  };
+  translate.locale = locale;
+  return translate;
+}

package/src/i18n/zh-CN.mjs

@@ -0,0 +1,70 @@
+export default Object.freeze({
+  help: `用法：
+  marmgr [--env-file PATH] nodes
+  marmgr [--env-file PATH] ssh [-t] <node-id> [command [arg...]]
+
+远程命令参数会按 SSH 方式用空格连接。包含空格的命令请按 SSH 方式引用。
+远程命令含有 flags 时请使用 --。仅支持 -t；不支持网络和身份 SSH 参数。
+默认配置为 ~/.marmgr/default.env。Windows 在 HOME 有值时使用 %HOME%\\.marmgr\\default.env，
+否则使用系统主目录。
+连接建立阶段有明确超时；远程命令没有总时长或空闲超时。
+relay 断开时 marmgr 会失败，不会重试或重新执行命令。`,
+  connected: '在线',
+  disconnected: '离线',
+  errors: Object.freeze({
+    configServerUrlMissing: '未配置 MAR_MGR_SERVER_URL。',
+    configKeyMissing: '未配置 MAR_MGR_KEY。',
+    configKeyInvalid: 'MAR_MGR_KEY 包含无效字符。',
+    serverUrlInvalid: 'MAR_MGR_SERVER_URL 无效。',
+    serverUrlTransport: 'MAR_MGR_SERVER_URL 必须使用 HTTPS 或回环 HTTP。',
+    serverUrlOrigin: 'MAR_MGR_SERVER_URL 必须是不含凭据或查询参数的 Origin。',
+    envFileMissing: '指定的环境文件不存在。',
+    envFileRead: '无法读取环境文件。',
+    envFileSymlink: '环境文件不能是符号链接。请使用 chmod 600。',
+    envFileType: '环境文件必须是普通文件。请使用 chmod 600。',
+    envFilePermissions: '环境文件必须归当前用户所有，权限必须为 0600 或 0400。请使用 chmod 600。',
+    envFileEntry: '环境文件条目无效。',
+    envFileUnsupported: '环境变量不受支持。',
+    envFileQuoted: '带引号的环境变量值无效。',
+    fetchUnavailable: '当前 Node.js 运行时没有 Fetch。',
+    serverInvalidNodes: 'Server 返回的节点列表无效。',
+    serverInvalidManifest: 'Server 返回的节点清单无效。',
+    terminalCommandInvalid: '终端命令无效。',
+    terminalSequenceInvalid: '终端序列无效。',
+    terminalTicketInvalid: '终端票据无效。',
+    terminalIdInvalid: '终端标识无效。',
+    nodeIdInvalid: '节点标识无效。',
+    terminalSizeInvalid: '终端尺寸无效。',
+    serverInvalidTerminalId: 'Server 返回的终端标识无效。',
+    serverInvalidTicket: 'Server 返回的终端票据无效。',
+    serverInvalidJson: 'Server 返回的 JSON 无效。',
+    serverTimeout: 'marmgr Server 未能在控制面请求超时前响应。',
+    serverUnreachable: '无法连接 marmgr Server。',
+    serverRejected: 'marmgr Server 拒绝了请求。',
+    terminalConnectionStart: '无法启动终端连接。',
+    terminalConnectionOpen: '无法打开终端连接。',
+    terminalAttachTimeout: '终端未能在连接建立超时前完成附着。',
+    terminalAttachConnection: '终端附着期间连接失败。',
+    terminalAttachLost: '终端附着期间连接断开。',
+    terminalRemoteError: '远程终端返回错误。',
+    terminalClosedBeforeAttach: '远程终端在附着前关闭。',
+    terminalFrameInvalid: '终端帧无效。',
+    terminalInvalidJson: '终端返回了无效 JSON。',
+    terminalBinaryFrame: '终端返回了无效二进制帧。',
+    terminalConnectionFailed: '终端连接失败。',
+    terminalConnectionLost: '终端连接断开。',
+    terminalUnexpectedFrame: '远程终端返回了意外帧。',
+    terminalInputFailed: '无法发送终端输入。',
+    terminalResizeFailed: '无法发送终端尺寸。',
+    terminalInteractiveRequired: '需要交互式终端。',
+    terminalInteractiveInit: '无法初始化交互式终端。',
+    terminalCloseFailed: '无法关闭远程终端。',
+    terminalSessionFailed: '终端会话失败。',
+    terminalDirectUnsafeFallback: 'OPEN 后无法安全取消直连终端，已跳过 relay 回退。',
+    invalidArguments: '命令参数无效。',
+    envFileValueRequired: '--env-file 必须提供值。',
+    sshTUnsupported: '不支持 SSH 选项 -T；marmgr 始终使用 PTY。',
+    sshOnlyT: '仅支持 SSH 选项 -t；不支持网络和身份参数。',
+    commandFailed: '命令执行失败。'
+  })
+});

package/src/terminal.mjs

@@ -0,0 +1,479 @@
+import { EventEmitter } from 'node:events';
+import { MarmgrError } from './config.mjs';
+import { createTranslator } from './i18n/index.mjs';
+
+const MAX_INPUT_BYTES = 65536;
+const DEFAULT_ROWS = 24;
+const DEFAULT_COLS = 80;
+const DEFAULT_CONNECTION_TIMEOUT_MS = 15000;
+
+export async function runTerminalSession({
+  client,
+  WebSocketClass,
+  nodeId,
+  command,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  signals = process,
+  translate = createTranslator(),
+  connectionTimeoutMs = DEFAULT_CONNECTION_TIMEOUT_MS,
+  openDirectTerminal: openDirectTerminalImpl
+}) {
+  const dimensions = getDimensions(stdout);
+  let terminalId;
+  let transport;
+  let result;
+  let primaryError;
+
+  try {
+    terminalId = await client.createTerminal({
+      nodeId,
+      ...dimensions,
+      ...(command === undefined ? {} : { command })
+    });
+    try {
+      const openDirectTerminal =
+        openDirectTerminalImpl ?? (await import('./direct.mjs')).openDirectTerminal;
+      transport = await openDirectTerminal({
+        client,
+        WebSocketClass,
+        nodeId,
+        terminalId,
+        afterSequence: 0,
+        timeoutMs: connectionTimeoutMs
+      });
+      result = await runAttachedTerminal({
+        transport,
+        terminalId,
+        commandMode: command !== undefined,
+        stdin,
+        stdout,
+        signals,
+        translate
+      });
+    } catch (error) {
+      if (error?.name === 'DirectUnsafeError')
+        throw new MarmgrError(translate('errors.terminalDirectUnsafeFallback'));
+      if (error?.name !== 'DirectFallbackError') throw error;
+      transport = await openRelayTransport({
+        client,
+        WebSocketClass,
+        nodeId,
+        terminalId,
+        translate,
+        connectionTimeoutMs
+      });
+      result = await runAttachedTerminal({
+        transport,
+        terminalId,
+        commandMode: command !== undefined,
+        stdin,
+        stdout,
+        signals,
+        translate
+      });
+    }
+  } catch (error) {
+    primaryError = toMarmgrError(error, translate);
+  } finally {
+    transport?.close?.();
+    if (terminalId !== undefined) {
+      try {
+        await client.deleteTerminal({ nodeId, terminalId });
+      } catch {
+        if (primaryError === undefined && result === undefined)
+          primaryError = new MarmgrError(translate('errors.terminalCloseFailed'));
+      }
+    }
+  }
+
+  if (primaryError !== undefined) throw primaryError;
+  return result;
+}
+
+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;
+}
+
+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) };
+}
+
+async function openRelayTransport({
+  client,
+  WebSocketClass,
+  nodeId,
+  terminalId,
+  translate,
+  connectionTimeoutMs
+}) {
+  const ticket = await client.createAttachTicket({ nodeId, terminalId });
+  const socket = client.openTerminalWebSocket(WebSocketClass, { terminalId, ticket });
+  const transport = new BufferedRelayTransport({
+    socket,
+    terminalId,
+    translate,
+    connectionTimeoutMs
+  });
+  try {
+    await transport.waitForAttachment();
+    return transport;
+  } catch (error) {
+    transport.close();
+    throw error;
+  }
+}
+
+class BufferedRelayTransport extends EventEmitter {
+  #socket;
+  #terminalId;
+  #translate;
+  #attached = false;
+  #active = false;
+  #pendingEvents = [];
+  #attachmentResolve;
+  #attachmentReject;
+  #openTimer;
+  #attachTimer;
+  #closed = false;
+  #onOpen;
+  #onMessage;
+  #onError;
+  #onClose;
+
+  constructor({ socket, terminalId, translate, connectionTimeoutMs }) {
+    super();
+    this.#socket = socket;
+    this.#terminalId = terminalId;
+    this.#translate = translate;
+    this.#onOpen = () => {
+      clearTimeout(this.#openTimer);
+      this.#armAttachTimer(connectionTimeoutMs);
+    };
+    this.#onMessage = (raw, isBinary) => {
+      try {
+        const frame = parseFrame(raw, isBinary, this.#terminalId, this.#translate);
+        if (!this.#attached) {
+          if (frame.type === 'attach') {
+            this.#attached = true;
+            clearTimeout(this.#attachTimer);
+            this.#attachmentResolve?.();
+            this.#attachmentResolve = undefined;
+            this.#attachmentReject = undefined;
+            return;
+          }
+          if (frame.type === 'error')
+            throw new MarmgrError(this.#translate('errors.terminalRemoteError'));
+          this.#queueOrEmit('message', raw, isBinary);
+          return;
+        }
+        this.#queueOrEmit('message', raw, isBinary);
+      } catch (error) {
+        this.#fail(
+          error instanceof MarmgrError
+            ? error
+            : new MarmgrError(this.#translate('errors.terminalFrameInvalid'))
+        );
+      }
+    };
+    this.#onError = () => {
+      const error = new MarmgrError(
+        this.#translate(
+          this.#attached ? 'errors.terminalConnectionFailed' : 'errors.terminalAttachConnection'
+        )
+      );
+      if (this.#attached) this.#queueOrEmit('error', error);
+      else this.#fail(error);
+    };
+    this.#onClose = () => {
+      const error = new MarmgrError(
+        this.#translate(
+          this.#attached ? 'errors.terminalConnectionLost' : 'errors.terminalAttachLost'
+        )
+      );
+      if (this.#attached) this.#queueOrEmit('close');
+      else this.#fail(error);
+    };
+
+    socket.on?.('open', this.#onOpen);
+    socket.on?.('message', this.#onMessage);
+    socket.on?.('error', this.#onError);
+    socket.on?.('close', this.#onClose);
+    if (socket.readyState === 1) this.#onOpen();
+    else
+      this.#openTimer = setTimeout(
+        () => this.#fail(new MarmgrError(this.#translate('errors.terminalConnectionOpen'))),
+        connectionTimeoutMs
+      );
+  }
+
+  waitForAttachment() {
+    return new Promise((resolve, reject) => {
+      if (this.#closed) {
+        reject(new MarmgrError(this.#translate('errors.terminalAttachLost')));
+        return;
+      }
+      this.#attachmentResolve = resolve;
+      this.#attachmentReject = reject;
+      if (this.#attached) {
+        this.#attachmentResolve = undefined;
+        this.#attachmentReject = undefined;
+        resolve();
+      }
+    });
+  }
+
+  activate() {
+    if (this.#active) return;
+    this.#active = true;
+    const pendingEvents = this.#pendingEvents;
+    this.#pendingEvents = [];
+    for (const { type, args } of pendingEvents) this.emit(type, ...args);
+  }
+
+  get readyState() {
+    return this.#socket.readyState;
+  }
+
+  send(value) {
+    if (this.#closed) throw new Error('TERMINAL_CONNECTION_LOST');
+    this.#socket.send(value);
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    clearTimeout(this.#openTimer);
+    clearTimeout(this.#attachTimer);
+    this.#socket.removeListener?.('open', this.#onOpen);
+    this.#socket.removeListener?.('message', this.#onMessage);
+    this.#socket.removeListener?.('error', this.#onError);
+    this.#socket.removeListener?.('close', this.#onClose);
+    try {
+      this.#socket.close();
+    } catch {
+      // The connection is already unavailable.
+    }
+  }
+
+  #armAttachTimer(connectionTimeoutMs) {
+    if (this.#attached) return;
+    this.#attachTimer = setTimeout(
+      () => this.#fail(new MarmgrError(this.#translate('errors.terminalAttachTimeout'))),
+      connectionTimeoutMs
+    );
+  }
+
+  #fail(error) {
+    if (this.#closed) return;
+    clearTimeout(this.#openTimer);
+    clearTimeout(this.#attachTimer);
+    this.#attachmentResolve = undefined;
+    const reject = this.#attachmentReject;
+    this.#attachmentReject = undefined;
+    if (!this.#attached) reject?.(error);
+    else this.#queueOrEmit('error', error);
+  }
+
+  #queueOrEmit(type, ...args) {
+    if (this.#active) {
+      if (type !== 'error' || this.listenerCount('error') > 0) this.emit(type, ...args);
+      return;
+    }
+    this.#pendingEvents.push({ type, args });
+  }
+}
+
+function runAttachedTerminal({
+  transport,
+  terminalId,
+  commandMode,
+  stdin,
+  stdout,
+  signals,
+  translate
+}) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let inputEnabled = false;
+    let rawModeEnabled = false;
+
+    const cleanup = () => {
+      transport.removeListener?.('message', onMessage);
+      transport.removeListener?.('error', onError);
+      transport.removeListener?.('close', onClose);
+      stdin.removeListener?.('data', onInput);
+      stdout.removeListener?.('resize', onResize);
+      signals.removeListener?.('SIGINT', onSigint);
+      signals.removeListener?.('SIGTERM', onSigterm);
+      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 MarmgrError(translate(key)));
+    const send = (frame) => {
+      transport.send(JSON.stringify(frame));
+    };
+    const onInput = (data) => {
+      try {
+        for (const chunk of splitInput(data)) send({ type: 'input', terminalId, data: chunk });
+      } catch {
+        fail('errors.terminalInputFailed');
+      }
+    };
+    const onResize = () => {
+      try {
+        const { rows, cols } = getDimensions(stdout);
+        send({ type: 'resize', terminalId, rows, cols });
+      } 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 MarmgrError
+            ? error
+            : new MarmgrError(translate('errors.terminalFrameInvalid'))
+        );
+      }
+    };
+    const onError = () => finish(new MarmgrError(translate('errors.terminalConnectionFailed')));
+    const onClose = () => finish(new MarmgrError(translate('errors.terminalConnectionLost')));
+    const onSigint = () => finish(undefined, 130);
+    const onSigterm = () => finish(undefined, 143);
+    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);
+    signals.on?.('SIGINT', onSigint);
+    signals.on?.('SIGTERM', onSigterm);
+    transport.activate?.();
+    startInput();
+  });
+}
+
+function parseFrame(raw, isBinary, terminalId, translate) {
+  if (isBinary) throw new MarmgrError(translate('errors.terminalBinaryFrame'));
+  let frame;
+  try {
+    frame = JSON.parse(rawToString(raw));
+  } catch {
+    throw new MarmgrError(translate('errors.terminalInvalidJson'));
+  }
+  if (frame === null || typeof frame !== 'object' || frame.terminalId !== terminalId)
+    throw new MarmgrError(translate('errors.terminalFrameInvalid'));
+
+  if (frame.type === 'attach') {
+    if (!Number.isSafeInteger(frame.afterSequence) || frame.afterSequence < 0)
+      throw new MarmgrError(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 MarmgrError(translate('errors.terminalFrameInvalid'));
+    return frame;
+  }
+  if (frame.type === 'exit') {
+    if (frame.exitCode !== null && !Number.isSafeInteger(frame.exitCode))
+      throw new MarmgrError(translate('errors.terminalFrameInvalid'));
+    return frame;
+  }
+  if (frame.type === 'error' && typeof frame.code === 'string' && frame.code.length > 0)
+    return frame;
+  throw new MarmgrError(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);
+}
+
+function sendCloseFrame(socket, terminalId) {
+  if (!terminalId || !isSocketOpen(socket)) return;
+  try {
+    socket.send(JSON.stringify({ type: 'close', terminalId }));
+  } catch {
+    // The DELETE request below remains the authoritative cleanup path.
+  }
+}
+
+function isSocketOpen(socket) {
+  return socket.readyState === undefined || socket.readyState === 1;
+}
+
+function toMarmgrError(error, translate) {
+  return error instanceof MarmgrError
+    ? error
+    : new MarmgrError(translate('errors.terminalSessionFailed'));
+}