@myagentroam/marctl 0.11.2 → 0.11.4

package/src/scp.mjs

@@ -1,336 +1,7 @@
-import { spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
-import { gzipSync } from 'node:zlib';
-import { MarctlError } from './config.mjs';
-import { parseFrame, runTerminalSession } from './terminal.mjs';
-
-const CHUNK = 32 * 1024;
-const WINDOW = 8;
-const MAX_BUFFERED_BYTES = WINDOW * (CHUNK + 4) + 64;
-const script = gzipSync(readFileSync(new URL('./scp-worker.cjs', import.meta.url))).toString(
-  'base64'
-);
-const expression = `eval(require('zlib').gunzipSync(Buffer.from('${script}','base64')).toString())`;
-
-export function parseScpEndpoint(value) {
-  if (typeof value !== 'string' || !value || value.includes('\0'))
-    throw new MarctlError('Invalid copy endpoint.');
-  const explicit = value.indexOf('://');
-  const separator = explicit >= 0 ? explicit : value.indexOf(':');
-  if (separator < 0 || (separator === 1 && /^[A-Za-z]:[\\/]/u.test(value))) {
-    // Let the filesystem resolve dot components and symlink parents.
-    return { path: path.isAbsolute(value) ? value : `${process.cwd()}${path.sep}${value}` };
-  }
-  const host = value.slice(0, separator);
-  const file = value.slice(separator + (explicit >= 0 ? 3 : 1));
-  if (!host || !file || (!file.startsWith('/') && !/^[A-Za-z]:[\\/]/u.test(file)))
-    throw new MarctlError('Invalid Node file path.');
-  return { host, path: file };
-}
-
-export function scpSourceBasename(value) {
-  const windowsPath = /^[A-Za-z]:[\\/]/u.test(value) || value.startsWith('\\\\');
-  if (value.endsWith('/') || (windowsPath && value.endsWith('\\')))
-    throw new MarctlError('Invalid source filename.');
-  const sourcePath = windowsPath ? path.win32 : path.posix;
-  const basename = sourcePath.basename(value);
-  if (!basename || basename === '.' || basename === '..')
-    throw new MarctlError('Invalid source filename.');
-  return basename;
-}
-
-function workerArguments(mode, file, size, metadata, preserve, sourceBasename) {
-  const encoded = Buffer.from(file, 'utf8').toString('base64url');
-  return [
-    mode,
-    encoded,
-    ...(size === undefined
-      ? []
-      : [
-          String(size),
-          metadata.toString('base64url'),
-          preserve ? '1' : '0',
-          Buffer.from(sourceBasename, 'utf8').toString('base64url')
-        ])
-  ];
-}
-
-function workerCommand(mode, file, size, metadata, preserve, sourceBasename) {
-  return `node -e "${expression}" ${workerArguments(mode, file, size, metadata, preserve, sourceBasename).join(' ')}`;
-}
-
-class ByteChannel {
-  #buffer = Buffer.alloc(0);
-  #waiting = [];
-  #sending = new Map();
-  #ended;
-  #failure;
-  #controller;
-
-  constructor(send, controller) {
-    this.#controller = controller;
-    const signal = controller.signal;
-    this.send = (bytes) => {
-      if (this.#failure) throw this.#failure;
-      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(signal.reason);
-      else
-        signal.addEventListener('abort', () => this.fail(signal.reason), {
-          once: true
-        });
-    }
-  }
-
-  feed(bytes) {
-    if (this.#failure) return;
-    this.#buffer = Buffer.concat([this.#buffer, bytes]);
-    if (this.#buffer.length > MAX_BUFFERED_BYTES)
-      return this.fail(new MarctlError('Copy output exceeded the bounded window.'));
-    this.#wake();
-  }
-
-  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) {
-    if (this.#failure !== undefined) return;
-    this.#failure = error;
-    for (const reject of this.#sending.keys()) reject(this.#failure);
-    this.#sending.clear();
-    this.#wake();
-    // Any endpoint failure must wake reads and writes across the entire copy.
-    this.#controller.abort(error);
-  }
-
-  #wake() {
-    for (const resolve of this.#waiting.splice(0)) resolve();
-  }
-
-  async read(length) {
-    if (this.#failure) throw this.#failure;
-    while (this.#buffer.length < length) {
-      if (this.#failure) throw this.#failure;
-      if (this.#ended !== undefined) throw new MarctlError('Copy stream ended unexpectedly.');
-      await new Promise((resolve) => this.#waiting.push(resolve));
-    }
-    const bytes = this.#buffer.subarray(0, length);
-    this.#buffer = this.#buffer.subarray(length);
-    return bytes;
-  }
-
-  async done() {
-    if (this.#failure) throw this.#failure;
-    while (this.#ended === undefined && this.#failure === undefined)
-      await new Promise((resolve) => this.#waiting.push(resolve));
-    if (this.#failure) throw this.#failure;
-    if (this.#ended !== 0) throw new MarctlError('Remote copy command failed.');
-  }
-}
-
-async function copyBytes(source, destination) {
-  const sizeBytes = await source.read(8);
-  const size = sizeBytes.readBigUInt64BE();
-  if (size > BigInt(Number.MAX_SAFE_INTEGER)) throw new MarctlError('Copy source is too large.');
-  const metadata = await source.read(20);
-  await destination.open(Number(size), metadata, async (target) => {
-    if ((await target.read(1))[0] !== 1)
-      throw new MarctlError('Copy target did not accept the file.');
-    let remaining = Number(size);
-    let acknowledged = Promise.resolve();
-    const pending = [];
-    for (;;) {
-      const header = await source.read(4);
-      const length = header.readUInt32BE();
-      if (length > CHUNK || length > remaining)
-        throw new MarctlError('Copy source sent an invalid chunk.');
-      await target.send(header);
-      if (length === 0) {
-        await acknowledged;
-        await target.send(await source.read(32));
-        if (remaining !== 0 || (await target.read(1))[0] !== 2)
-          throw new MarctlError('Copy target did not verify the file.');
-        break;
-      }
-      await target.send(await source.read(length));
-      // Keep one ordered ACK reader while sending up to a bounded window ahead.
-      acknowledged = acknowledged.then(async () => {
-        if ((await target.read(1))[0] !== 1)
-          throw new MarctlError('Copy target rejected the chunk.');
-        await source.send(Buffer.from([1]));
-      });
-      acknowledged.catch((error) => {
-        // ACK failures use the same copy-wide cancellation as transport failures.
-        source.fail(error);
-      });
-      pending.push(acknowledged);
-      remaining -= length;
-      if (pending.length >= WINDOW) await pending.shift();
-    }
-    await target.done();
-  });
-  await source.done();
-}
-
-async function withLocalWorker(
-  mode,
-  file,
-  size,
-  metadata,
-  preserve,
-  sourceBasename,
-  use,
-  controller
-) {
-  const child = spawn(
-    process.execPath,
-    ['-e', expression, ...workerArguments(mode, file, size, metadata, preserve, sourceBasename)],
-    {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true
-    }
-  );
-  child.stdin.on('error', () => undefined);
-  child.stderr.resume();
-  const channel = new ByteChannel(
-    (bytes) =>
-      new Promise((resolve, reject) => {
-        child.stdin.write(bytes, (error) => (error ? reject(error) : resolve()));
-      }),
-    controller
-  );
-  child.stdout.on('data', (bytes) => channel.feed(bytes));
-  child.once('error', (error) => channel.fail(error));
-  child.once('close', (code) => channel.finish(code ?? 1));
-  try {
-    return await use(channel);
-  } finally {
-    if (child.exitCode === null) child.kill();
-  }
-}
-
-async function withRemoteWorker(
-  {
-    client,
-    WebSocketClass,
-    nodeId,
-    file,
-    mode,
-    size,
-    metadata,
-    preserve,
-    sourceBasename,
-    translate,
-    controller
-  },
-  use
-) {
-  return runTerminalSession({
-    client,
-    WebSocketClass,
-    nodeId,
-    command: workerCommand(mode, file, size, metadata, preserve, sourceBasename),
-    binary: true,
-    raceConnections: true,
-    translate,
-    attached: async ({ transport, terminalId }) => {
-      const channel = new ByteChannel(
-        (bytes) =>
-          transport.send(
-            JSON.stringify({ type: 'input', terminalId, data: bytes.toString('base64') })
-          ),
-        controller
-      );
-      let sequence = 0;
-      const onMessage = (raw, isBinary) => {
-        try {
-          const frame = parseFrame(raw, isBinary, terminalId, translate);
-          if (frame.type === 'output') {
-            if (frame.sequence !== sequence + 1)
-              throw new MarctlError('Copy output sequence is invalid.');
-            sequence = frame.sequence;
-            const bytes = Buffer.from(frame.data, 'base64');
-            if (bytes.toString('base64') !== frame.data)
-              throw new MarctlError('Copy output is not valid base64.');
-            channel.feed(bytes);
-          } else if (frame.type === 'exit') channel.finish(frame.exitCode ?? 1);
-          else if (frame.type === 'error')
-            channel.fail(new MarctlError(translate('errors.terminalRemoteError')));
-          else throw new MarctlError(translate('errors.terminalUnexpectedFrame'));
-        } catch (error) {
-          channel.fail(error);
-        }
-      };
-      const onError = () =>
-        channel.connectionEnded(new MarctlError(translate('errors.terminalConnectionFailed')));
-      const onClose = () =>
-        channel.connectionEnded(new MarctlError(translate('errors.terminalConnectionLost')));
-      transport.on('message', onMessage);
-      transport.on('error', onError);
-      transport.on('close', onClose);
-      try {
-        transport.activate?.();
-        return await use(channel);
-      } finally {
-        transport.removeListener?.('message', onMessage);
-        transport.removeListener?.('error', onError);
-        transport.removeListener?.('close', onClose);
-      }
-    }
-  });
-}
-
-async function withWorker(endpoint, mode, size, metadata, context, use) {
-  if (endpoint.nodeId === undefined)
-    return withLocalWorker(
-      mode,
-      endpoint.path,
-      size,
-      metadata,
-      context.preserve,
-      context.sourceBasename,
-      use,
-      context.controller
-    );
-  return withRemoteWorker(
-    {
-      ...context,
-      nodeId: endpoint.nodeId,
-      file: endpoint.path,
-      mode,
-      size,
-      metadata
-    },
-    use
-  );
-}
+import { MarctlError } from './errors.mjs';
+import { parseScpEndpoint, scpSourceBasename } from './scp-endpoint.mjs';
+import { copyBytes } from './scp-copy.mjs';
+import { withWorker } from './scp-workers.mjs';
 
 export async function runScp({
   source,
@@ -340,23 +11,33 @@ export async function runScp({
   WebSocketClass,
   resolveNodeId,
   translate,
-  signals = process
+  signal
 }) {
   const from = parseScpEndpoint(source);
   const to = parseScpEndpoint(destination);
   const sourceBasename = scpSourceBasename(from.path);
   if (!from.host && !to.host) throw new MarctlError('At least one copy endpoint must be a Node.');
   const references = [...new Set([from.host, to.host].filter(Boolean))];
-  const ids = await Promise.all(references.map((host) => resolveNodeId(host)));
-  const resolved = (endpoint) => ({
-    path: endpoint.path,
-    ...(endpoint.host ? { nodeId: ids[references.indexOf(endpoint.host)] } : {})
-  });
   const controller = new AbortController();
-  const interrupt = () => controller.abort(new MarctlError('Copy was interrupted.'));
-  signals.on?.('SIGINT', interrupt);
-  signals.on?.('SIGTERM', interrupt);
+  let rejectResolution;
+  const interrupt = () => {
+    controller.abort(new MarctlError('Copy was interrupted.'));
+    rejectResolution?.(controller.signal.reason);
+  };
+  signal?.addEventListener('abort', interrupt, { once: true });
+  if (signal?.aborted) interrupt();
   try {
+    controller.signal.throwIfAborted();
+    const ids = await new Promise((resolve, reject) => {
+      rejectResolution = reject;
+      Promise.all(references.map((host) => resolveNodeId(host))).then(resolve, reject);
+    });
+    rejectResolution = undefined;
+    controller.signal.throwIfAborted();
+    const resolved = (endpoint) => ({
+      path: endpoint.path,
+      ...(endpoint.host ? { nodeId: ids[references.indexOf(endpoint.host)] } : {})
+    });
     const context = {
       client,
       WebSocketClass,
@@ -371,12 +52,13 @@ export async function runScp({
           withWorker(resolved(to), 'write', size, metadata, context, use)
       })
     );
+    controller.signal.throwIfAborted();
     return 0;
   } catch (error) {
     controller.abort(error);
     throw error;
   } finally {
-    signals.removeListener?.('SIGINT', interrupt);
-    signals.removeListener?.('SIGTERM', interrupt);
+    rejectResolution = undefined;
+    signal?.removeEventListener('abort', interrupt);
   }
 }

package/src/session-args.mjs

@@ -0,0 +1,176 @@
+import { MarctlError } from './errors.mjs';
+import { createTranslator } from './i18n/index.mjs';
+import { sessionTarget } from './session-target.mjs';
+
+const commands = {
+  current: [],
+  list: ['cursor', 'limit', 'query', 'parent'],
+  graph: ['limit'],
+  show: [],
+  history: ['cursor', 'limit'],
+  start: [
+    'runner',
+    'model',
+    'effort',
+    'title',
+    'message',
+    'message-file',
+    'image',
+    'client-message-id'
+  ],
+  config: ['model', 'effort'],
+  rename: ['title'],
+  'prompt.get': [],
+  'prompt.set': ['message', 'message-file'],
+  'prompt.clear': [],
+  'approval.decide': ['run', 'approval', 'decision'],
+  'schedule.list': ['cursor', 'limit'],
+  'schedule.get': [],
+  'schedule.create': ['cron', 'message', 'message-file'],
+  'schedule.update': ['cron', 'message', 'message-file', 'expected-revision'],
+  send: ['message', 'message-file', 'image', 'steer', 'queue', 'client-message-id'],
+  stop: ['run'],
+  'goal.get': [],
+  'goal.set': ['message', 'message-file'],
+  'goal.clear': [],
+  wait: ['run', 'timeout', 'until']
+};
+const fieldNames = {
+  parent: 'parentSessionId',
+  'expected-revision': 'expectedRevision',
+  'message-file': 'messageFile',
+  'client-message-id': 'clientMessageId',
+  run: 'runId',
+  approval: 'approvalId',
+  timeout: 'timeoutMs',
+  image: 'images'
+};
+
+export function parseSessionArgs(argv, translate = createTranslator()) {
+  const invalid = (key = 'errors.invalidArguments', details) =>
+    new MarctlError(translate(key), {
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      details:
+        details ??
+        (argv[0] === 'prompt'
+          ? 'Use prompt get|clear [session-id], or prompt set [session-id] with exactly one of -m/--message or --message-file.'
+          : argv[0] === 'approval'
+            ? 'Use approval decide <session-id> --run <run-id> --approval <approval-id> --decision approve|reject.'
+            : undefined)
+    });
+  if (
+    argv.length === 0 ||
+    argv.some(
+      (value, index) =>
+        (value === '--help' || value === '-h') && !['-m', '--message'].includes(argv[index - 1])
+    )
+  )
+    return { command: 'sessions', help: true };
+  const input = [...argv];
+  let action = input.shift();
+  if (['goal', 'schedule', 'prompt', 'approval'].includes(action)) action += '.' + input.shift();
+  if (!Object.hasOwn(commands, action)) throw invalid();
+  const args = { command: 'sessions', action };
+  if (sessionTarget[action] !== 'workspace') {
+    if (
+      (input[0] === undefined || input[0].startsWith('-')) &&
+      sessionTarget[action] === 'explicit'
+    )
+      throw invalid();
+    if (input[0] !== undefined && !input[0].startsWith('-')) {
+      const sessionId = input.shift();
+      if (!sessionId || sessionId.length > 512) throw invalid();
+      args.sessionId = sessionId;
+    }
+  }
+  while (input.length > 0) {
+    const rawFlag = input.shift();
+    const flag = rawFlag === '-m' ? '--message' : rawFlag;
+    if (flag === '--json' && args.json === undefined) {
+      args.json = true;
+      continue;
+    }
+    if (action === 'send' && (flag === '--steer' || flag === '--queue')) {
+      const key = flag.slice(2);
+      if (Object.hasOwn(args, key)) throw invalid();
+      args[key] = true;
+      continue;
+    }
+    const name = flag.startsWith('--') ? flag.slice(2) : '';
+    const key = fieldNames[name] ?? name;
+    if (!commands[action].includes(name) || (name !== 'image' && Object.hasOwn(args, key)))
+      throw invalid();
+    const value = input.shift();
+    if (
+      value === undefined ||
+      (value === '' && name !== 'effort') ||
+      (name !== 'message' && value.startsWith('--'))
+    )
+      throw invalid();
+    if (name === 'image') {
+      (args.images ??= []).push(value);
+      if (args.images.length > 5) throw invalid();
+    } else if (name === 'limit' || name === 'expected-revision') {
+      if (
+        !/^[1-9][0-9]*$/u.test(value) ||
+        !Number.isSafeInteger(Number(value)) ||
+        (name === 'limit' && Number(value) > 100)
+      )
+        throw invalid();
+      args[key] = Number(value);
+    } else if (name === 'timeout') {
+      const match = /^([1-9][0-9]*)(ms|s|m)$/u.exec(value);
+      const ms = match === null ? 0 : Number(match[1]) * { ms: 1, s: 1000, m: 60000 }[match[2]];
+      if (!Number.isSafeInteger(ms) || ms < 1 || ms > 3600000) throw invalid();
+      args[key] = ms;
+    } else args[key] = value;
+  }
+  if (action === 'send' && (args.steer === true) === (args.queue === true))
+    throw invalid('errors.sessionDeliveryRequired');
+  if (args.message !== undefined && args.messageFile !== undefined) throw invalid();
+  if (
+    ['start', 'send', 'goal.set', 'schedule.create', 'prompt.set'].includes(action) &&
+    args.messageFile === undefined &&
+    args.message === undefined &&
+    !args.images?.length
+  )
+    throw invalid();
+  if (
+    action === 'start' &&
+    !['mar-agent', 'codex', 'claude-code', 'opencode'].includes(args.runner)
+  )
+    throw invalid();
+  if (action === 'wait' && (args.runId === undefined || args.timeoutMs === undefined))
+    throw invalid();
+  if (args.until !== undefined && args.until !== 'approval')
+    throw invalid(undefined, '--until: expected approval.');
+  if (
+    action === 'approval.decide' &&
+    (!args.runId || !args.approvalId || !['approve', 'reject'].includes(args.decision))
+  )
+    throw invalid(
+      undefined,
+      'Approval decisions require --run, --approval and --decision approve|reject.'
+    );
+  if (action === 'rename' && args.title !== undefined) args.title = args.title.trim();
+  if (args.title !== undefined && args.title.length > 160) throw invalid();
+  if (args.model !== undefined && (args.model.trim().length === 0 || args.model.length > 120))
+    throw invalid();
+  if (args.effort !== undefined && args.effort.length > 120) throw invalid();
+  if (action === 'config' && args.model === undefined && args.effort === undefined) throw invalid();
+  if (action === 'rename') {
+    if (args.title === undefined || args.title.trim().length === 0) throw invalid();
+  }
+  if (action === 'schedule.create' && args.cron === undefined) throw invalid();
+  if (args.cron !== undefined && (args.cron.trim().length === 0 || args.cron.length > 512))
+    throw invalid();
+  if (
+    action === 'schedule.update' &&
+    (args.expectedRevision === undefined ||
+      (args.cron === undefined && args.message === undefined && args.messageFile === undefined))
+  )
+    throw invalid();
+  if (args.query !== undefined && args.query.length > 160) throw invalid();
+  if (args.parentSessionId !== undefined && args.parentSessionId.length > 512) throw invalid();
+  return args;
+}

package/src/session-input.mjs

@@ -0,0 +1,88 @@
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { MarctlError } from './errors.mjs';
+
+export async function messageContent(
+  { message, messageFile: path },
+  stdin,
+  limit,
+  translate,
+  diagnostic = false
+) {
+  let file;
+  try {
+    let content = message;
+    if (content === undefined) {
+      const input =
+        path === '-'
+          ? stdin
+          : (file = await open(path, 'r')).createReadStream({ autoClose: false });
+      const parts = [];
+      let bytes = 0;
+      for await (const part of input) {
+        const chunk = Buffer.from(part);
+        bytes += chunk.length;
+        if (bytes > limit * 4) throw new Error('MESSAGE_TOO_LONG');
+        parts.push(chunk);
+      }
+      content = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
+    }
+    if (content.trim().length === 0 || content.length > limit) throw new Error('MESSAGE_INVALID');
+    return content;
+  } catch (error) {
+    throw new MarctlError(translate('errors.sessionMessageInvalid'), {
+      code: 'MARCTL_SESSION_INPUT_INVALID',
+      ...(diagnostic
+        ? {
+            details: `${path === undefined ? 'message' : path === '-' ? 'stdin' : 'message-file'}: provide non-blank UTF-8 text of at most ${limit} characters.${typeof error.code === 'string' && /^[A-Z_]+$/u.test(error.code) ? ' File error: ' + error.code + '.' : ''}`
+          }
+        : {})
+    });
+  } finally {
+    await file?.close();
+  }
+}
+
+export async function imageAttachments(paths, translate) {
+  const attachments = [];
+  let total = 0;
+  for (const path of paths) {
+    let file;
+    try {
+      file = await open(path, 'r');
+      const info = await file.stat();
+      if (!info.isFile() || info.size === 0 || info.size > 5 * 1024 * 1024)
+        throw new Error('IMAGE_INVALID');
+      const parts = [];
+      let size = 0;
+      for await (const part of file.createReadStream({ autoClose: false })) {
+        size += part.length;
+        total += part.length;
+        if (size > 5 * 1024 * 1024 || total > 10 * 1024 * 1024) throw new Error('IMAGE_TOO_LARGE');
+        parts.push(part);
+      }
+      const data = Buffer.concat(parts);
+      const mime = imageMime(data);
+      if (mime === undefined) throw new Error('IMAGE_INVALID');
+      attachments.push({ name: basename(path), mime, dataBase64: data.toString('base64') });
+    } catch {
+      throw new MarctlError(translate('errors.sessionImageInvalid'), {
+        code: 'MARCTL_SESSION_INPUT_INVALID'
+      });
+    } finally {
+      await file?.close();
+    }
+  }
+  return attachments;
+}
+
+function imageMime(data) {
+  if (data.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) return 'image/png';
+  if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) return 'image/jpeg';
+  if (['GIF87a', 'GIF89a'].includes(data.subarray(0, 6).toString('ascii'))) return 'image/gif';
+  if (
+    data.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    data.subarray(8, 12).toString('ascii') === 'WEBP'
+  )
+    return 'image/webp';
+}