@myagentroam/marctl 0.11.2 → 0.11.4

package/src/i18n/en-US.mjs

@@ -121,9 +121,12 @@ Reading JSON:
 Delivery and waiting:
   Start/send return a clientMessageId.
   Send requires exactly one of --steer or --queue, even when idle.
-  --steer prioritizes time-sensitive updates affecting current work and may
-    switch the current execution. Node decides from actual state.
-  --queue does not interrupt active execution; during normal active work it
+  Prefer --steer for timely coordination: blockers, decisions, corrections,
+    and results the recipient is waiting for. It uses native delivery when
+    available, but may switch the current execution.
+    Node decides from actual state.
+  Use --queue only for deliberately deferred follow-up work.
+    It does not interrupt active execution; during normal active work it
     waits for that execution and earlier queued work. An active Goal can delay
     it until the Goal exits.
     Use --steer instead when the update is needed during current work.

package/src/i18n/zh-CN.mjs

@@ -118,9 +118,11 @@ ${configurationHelp}
 投递与等待：
   start/send 返回 clientMessageId。
   send 必须二选一：--steer 或 --queue，空闲时也需指定。
-  --steer 优先补充影响当前工作的及时信息，可能切换当前执行；
-    Node 按实际状态裁决。
-  --queue 不打断活动执行；正常运行时等待当前执行和前面的队列项；
+  及时协作优先使用 --steer：阻塞、决策请求、纠偏
+    和对方正在等待的结果。可用时优先原生投递，
+    否则可能切换当前执行；Node 按实际状态裁决。
+  仅明确要延后执行的后续工作使用 --queue。
+    它不打断活动执行；正常运行时等待当前执行和前面的队列项；
     有活动 Goal 时可能等待 Goal 退出才处理。
     当前工作需要及时获知的信息应使用 --steer。
     新输入自动恢复暂停的 FIFO，不打断活动执行；取消收敛后才恢复。

package/src/scp-channel.mjs

@@ -0,0 +1,99 @@
+import { MarctlError } from './errors.mjs';
+import { CHUNK, WINDOW } from './scp-protocol.mjs';
+
+const MAX_BUFFERED_BYTES = WINDOW * (CHUNK + 4) + 64;
+
+export 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.');
+  }
+}

package/src/scp-copy.mjs

@@ -0,0 +1,46 @@
+import { MarctlError } from './errors.mjs';
+import { CHUNK, WINDOW } from './scp-protocol.mjs';
+
+export 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();
+}

package/src/scp-endpoint.mjs

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { MarctlError } from './errors.mjs';
+
+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;
+}

package/src/scp-protocol.mjs

@@ -0,0 +1,2 @@
+export const CHUNK = 32 * 1024;
+export const WINDOW = 8;

package/src/scp-workers.mjs

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
+import { MarctlError } from './errors.mjs';
+import { DirectRejectedError } from './direct-errors.mjs';
+import { runTerminalSession } from './terminal.mjs';
+import { parseFrame } from './terminal-frame.mjs';
+import { ByteChannel } from './scp-channel.mjs';
+
+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())`;
+
+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(' ')}`;
+}
+
+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));
+  const closed = new Promise((resolve) => {
+    child.once('close', (code) => {
+      channel.finish(code ?? 1);
+      resolve();
+    });
+  });
+  try {
+    return await use(channel);
+  } finally {
+    if (child.exitCode === null) child.kill();
+    await closed;
+  }
+}
+
+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,
+    signal: controller.signal,
+    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 = (error) =>
+        channel.connectionEnded(
+          error instanceof DirectRejectedError
+            ? new MarctlError(`${translate('errors.terminalConnectionFailed')} [${error.code}]`, {
+                code: error.code
+              })
+            : 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);
+      }
+    }
+  });
+}
+
+export 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
+  );
+}