@outerlayer/cli 0.2.0 → 0.4.1

package/dist/chunk-USO2DKBD.js

@@ -0,0 +1,421 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { revokeTokenOnDashboard } from './chunk-N6LURUEF.js';
+import { C } from './chunk-YRYMNBGQ.js';
+import { readCloudConfig, writeCloudConfig, cloudConfigPath } from './chunk-EABW6AJQ.js';
+import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import { generateKeyPairSync, privateDecrypt, constants, createPrivateKey } from 'crypto';
+import { spawn } from 'child_process';
+import { fstatSync, existsSync, readdirSync, readFileSync, rmSync, mkdirSync, chmodSync, writeFileSync } from 'fs';
+import { hostname } from 'os';
+import { join } from 'path';
+
+createRequire(import.meta.url);
+
+// src/login-cmd.ts
+var LoginError = class extends Error {
+};
+function runLogin(opts) {
+  const apiKey = opts.apiKey.trim();
+  if (apiKey.length === 0) throw new LoginError("no API key given \u2014 pipe it on stdin, or run outerlayer login with no key on stdin to sign in by browser");
+  if (/\s/.test(apiKey)) throw new LoginError("the API key must be a single token with no spaces or line breaks");
+  const url = opts.url?.trim() || void 0;
+  const appId = opts.appId?.trim() || void 0;
+  const home = opts.home ?? homeFromEnv();
+  writeCloudConfig(
+    {
+      apiKey,
+      ...url ? { url } : {},
+      ...appId ? { appId } : {}
+    },
+    home
+  );
+  const saved = readCloudConfig(home);
+  return { path: cloudConfigPath(home), url: saved.url, appId: saved.appId };
+}
+
+// src/login-browser.ts
+var DEFAULT_DASHBOARD = "https://app.outerlayer.ai";
+var EXIT_WAITING = 75;
+var EXIT_USAGE = 2;
+var PIPED_KEY_NOTICE_MS = 1e3;
+var PIPED_KEY_GIVE_UP_MS = 3e4;
+var REQUEST_TIMEOUT_MS = 15e3;
+var MAX_POLL_FAILURES = 5;
+var DEFAULT_POLL_INTERVAL_S = 3;
+var MACHINE_NAME_MAX = 255;
+function realLoginDeps() {
+  return {
+    fetchImpl: fetch,
+    now: () => /* @__PURE__ */ new Date(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    openBrowser: openInBrowser,
+    stdin: process.stdin,
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+    stdout: process.stdout,
+    stderr: process.stderr,
+    hostname: hostname
+  };
+}
+function openInBrowser(url) {
+  return new Promise((resolve) => {
+    const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+      const child = spawn(command, args, { stdio: "ignore", detached: true });
+      child.on("error", () => resolve());
+      child.unref();
+      resolve();
+    } catch {
+      resolve();
+    }
+  });
+}
+function sanitizeMachineName(raw) {
+  const cleaned = raw.replace(/[^\w\s\-().]/g, "").trim();
+  return (cleaned.length > 0 ? cleaned : "machine").slice(0, MACHINE_NAME_MAX);
+}
+function stdinKind(stdin) {
+  if (stdin.isTTY) return "terminal";
+  const fd = stdin.fd;
+  if (typeof fd !== "number") return "pipe";
+  try {
+    const stat = fstatSync(fd);
+    return stat.isFile() || stat.isCharacterDevice() ? "file" : "pipe";
+  } catch {
+    return "pipe";
+  }
+}
+function readPipedKey(stdin, opts = {}) {
+  const kind = opts.kind ?? stdinKind(stdin);
+  if (kind === "terminal") return Promise.resolve(null);
+  const noticeMs = opts.noticeMs ?? PIPED_KEY_NOTICE_MS;
+  const giveUpMs = opts.giveUpMs ?? PIPED_KEY_GIVE_UP_MS;
+  return new Promise((resolve) => {
+    const chunks = [];
+    let noticeTimer;
+    let giveUpTimer;
+    const stopTimers = () => {
+      clearTimeout(noticeTimer);
+      clearTimeout(giveUpTimer);
+    };
+    const finish = (value) => {
+      stopTimers();
+      stdin.off("data", onData);
+      stdin.off("end", onEnd);
+      stdin.off("error", onEnd);
+      stdin.off("close", onEnd);
+      if (value === null) stdin.pause();
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      stopTimers();
+      chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    };
+    const onEnd = () => {
+      const text = Buffer.concat(chunks).toString("utf8").trim();
+      finish(text.length > 0 ? text : null);
+    };
+    if (kind === "pipe") {
+      noticeTimer = setTimeout(() => opts.onWaiting?.(), noticeMs);
+      giveUpTimer = setTimeout(() => finish(null), giveUpMs);
+    }
+    stdin.on("data", onData);
+    stdin.once("end", onEnd);
+    stdin.once("error", onEnd);
+    stdin.once("close", onEnd);
+  });
+}
+function pendingDir(home) {
+  return join(home, ".outerlayer", "login-pending");
+}
+function isPlainId(id) {
+  return /^[\w-]{1,80}$/.test(id);
+}
+function pendingPath(home, id) {
+  return join(pendingDir(home), `${id}.json`);
+}
+function writePending(home, pending) {
+  const dir = pendingDir(home);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  chmodSync(dir, 448);
+  writeFileSync(pendingPath(home, pending.id), JSON.stringify(pending, null, 2) + "\n", { mode: 384 });
+  chmodSync(pendingPath(home, pending.id), 384);
+}
+function readPending(home, id) {
+  if (!isPlainId(id)) return null;
+  try {
+    return JSON.parse(readFileSync(pendingPath(home, id), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function deletePending(home, id) {
+  if (isPlainId(id)) rmSync(pendingPath(home, id), { force: true });
+}
+function purgeExpiredPending(home, now, keepId) {
+  const dir = pendingDir(home);
+  if (!existsSync(dir)) return;
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".json") || name === `${keepId}.json`) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(join(dir, name), "utf8"));
+      if (typeof parsed.expires_at === "string" && Date.parse(parsed.expires_at) <= now.getTime()) {
+        rmSync(join(dir, name), { force: true });
+      }
+    } catch {
+    }
+  }
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : {};
+}
+async function startLogin(deps, dashboard, publicKey, machineName) {
+  let res;
+  try {
+    res = await deps.fetchImpl(`${dashboard}/api/cli/login`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ public_key: publicKey, machine_name: machineName, kind: "account" }),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+  } catch (err) {
+    throw new LoginError(`could not reach ${dashboard}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (res.status === 429) {
+    const wait = Number(res.headers.get("retry-after"));
+    throw new LoginError(
+      `${dashboard} is limiting logins from this address` + (wait > 0 ? `; try again in ${wait} seconds` : "; try again shortly")
+    );
+  }
+  const body = asRecord(await res.json().catch(() => null));
+  if (!res.ok) {
+    const reason = typeof body.message === "string" ? `: ${body.message}` : "";
+    throw new LoginError(`${dashboard} refused to start a login (HTTP ${res.status})${reason}`);
+  }
+  if (typeof body.id !== "string" || typeof body.code !== "string" || typeof body.expires_at !== "string") {
+    throw new LoginError(`${dashboard} answered with something that is not a login; is --dashboard the dashboard's address?`);
+  }
+  const interval = typeof body.interval === "number" && body.interval > 0 ? body.interval : DEFAULT_POLL_INTERVAL_S;
+  return { id: body.id, code: body.code, interval, expiresAt: body.expires_at };
+}
+async function pollLogin(deps, dashboard, id) {
+  let res;
+  try {
+    res = await deps.fetchImpl(`${dashboard}/api/cli/login/${encodeURIComponent(id)}`, {
+      method: "GET",
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+  } catch (err) {
+    return { kind: "unavailable", message: err instanceof Error ? err.message : String(err) };
+  }
+  if (res.status === 410) return { kind: "expired" };
+  if (res.status === 429) return { kind: "slow", retryAfterS: Math.max(1, Number(res.headers.get("retry-after")) || DEFAULT_POLL_INTERVAL_S) };
+  if (res.status === 202) return { kind: "pending" };
+  if (res.status >= 500) return { kind: "unavailable", message: `HTTP ${res.status}` };
+  if (!res.ok) return { kind: "error", message: `HTTP ${res.status}` };
+  const body = asRecord(await res.json().catch(() => null));
+  if (body.status === "pending") return { kind: "pending" };
+  if (body.status === "denied") return { kind: "denied" };
+  if (body.status === "approved" && typeof body.encrypted_token === "string" && typeof body.gateway_url === "string" && typeof body.email === "string") {
+    return { kind: "approved", encryptedToken: body.encrypted_token, gatewayUrl: body.gateway_url, email: body.email };
+  }
+  return { kind: "error", message: "unexpected answer" };
+}
+function decryptToken(privateKeyPem, encryptedToken) {
+  try {
+    return privateDecrypt(
+      { key: createPrivateKey(privateKeyPem), oaepHash: "sha256", padding: constants.RSA_PKCS1_OAEP_PADDING },
+      Buffer.from(encryptedToken, "base64")
+    ).toString("utf8");
+  } catch {
+    throw new LoginError("could not decrypt the token the dashboard sent; run outerlayer login again");
+  }
+}
+function normalizeDashboard(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new LoginError(`--dashboard must be an address such as ${DEFAULT_DASHBOARD}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new LoginError("--dashboard must start with http:// or https://");
+  return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+function approveLink(dashboard, code) {
+  return `${dashboard}/cli/login?code=${encodeURIComponent(code)}`;
+}
+function waitingDocument(link, code, id) {
+  return JSON.stringify({ status: "waiting", url: link, code, check: `outerlayer login --check ${id}` }) + "\n";
+}
+async function finishApproved(flags, deps, home, dashboard, approved, privateKeyPem) {
+  const accountToken = decryptToken(privateKeyPem, approved.encryptedToken);
+  const before = readCloudConfig(home);
+  try {
+    writeCloudConfig({ accountToken, url: approved.gatewayUrl, dashboard }, home);
+  } catch (err) {
+    const revoked = await revokeTokenOnDashboard(deps.fetchImpl, dashboard, accountToken);
+    return fail(
+      deps,
+      `could not save the login: ${err instanceof Error ? err.message : String(err)}. ` + (revoked === "revoked" ? "The token was revoked; run outerlayer login again." : "The token could not be revoked; revoke it on the CLI logins list at /profile/security.")
+    );
+  }
+  if (before.accountToken && before.accountToken !== accountToken) {
+    await revokeTokenOnDashboard(deps.fetchImpl, before.dashboard ?? dashboard, before.accountToken);
+  }
+  const path = cloudConfigPath(home);
+  if (flags.json) {
+    deps.stdout.write(JSON.stringify({ path, url: approved.gatewayUrl, email: approved.email }) + "\n");
+    return 0;
+  }
+  deps.stdout.write(
+    `${C.green}\u2713${C.reset} Logged in as ${approved.email}. Saved the login to ${path}
+Next: run \`outerlayer connect\` to choose a factory.
+`
+  );
+  if (before.apiKey) {
+    deps.stdout.write("A factory key is also saved on this machine, so commands here keep using the key, not this login.\n");
+  }
+  return 0;
+}
+function fail(deps, message) {
+  deps.stderr.write(`${C.red}\u2717${C.reset} ${message}
+`);
+  return 1;
+}
+async function runPastedKey(flags, deps, key, home) {
+  const result = runLogin({ apiKey: key, url: flags.url, appId: flags.appId, home });
+  if (flags.json) {
+    deps.stdout.write(JSON.stringify(result) + "\n");
+    return 0;
+  }
+  deps.stdout.write(
+    `${C.green}\u2713${C.reset} Saved credentials to ${result.path}` + (result.url ? ` for ${result.url}` : "") + (result.appId ? ` (app ${result.appId})` : "") + "\n"
+  );
+  return 0;
+}
+async function runCheck(flags, deps, home, id) {
+  const pending = readPending(home, id);
+  if (!pending) return fail(deps, `no pending login ${id}; run outerlayer login to start one`);
+  if (Date.parse(pending.expires_at) <= deps.now().getTime()) {
+    deletePending(home, id);
+    return fail(deps, "the login link expired; run outerlayer login again");
+  }
+  const result = await pollLogin(deps, pending.dashboard, pending.id);
+  switch (result.kind) {
+    case "pending":
+    case "slow":
+      deps.stdout.write(waitingDocument(pending.url, pending.code, pending.id));
+      return EXIT_WAITING;
+    case "denied":
+      deletePending(home, id);
+      return fail(deps, "the login was denied");
+    case "expired":
+      deletePending(home, id);
+      return fail(deps, "the login link expired; run outerlayer login again");
+    case "unavailable":
+      deps.stderr.write(`could not check the login yet: ${result.message}
+`);
+      deps.stdout.write(waitingDocument(pending.url, pending.code, pending.id));
+      return EXIT_WAITING;
+    case "error":
+      return fail(deps, `could not check the login: ${result.message}`);
+    case "approved": {
+      try {
+        return await finishApproved(flags, deps, home, pending.dashboard, result, pending.private_key);
+      } finally {
+        deletePending(home, id);
+      }
+    }
+  }
+}
+async function runBrowserLogin(flags, deps, home) {
+  const dashboard = normalizeDashboard(flags.dashboard ?? DEFAULT_DASHBOARD);
+  const { publicKey, privateKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    publicKeyEncoding: { type: "spki", format: "der" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" }
+  });
+  const started = await startLogin(deps, dashboard, publicKey.toString("base64"), sanitizeMachineName(deps.hostname()));
+  const link = approveLink(dashboard, started.code);
+  if (!deps.stdoutIsTTY) {
+    writePending(home, {
+      id: started.id,
+      dashboard,
+      url: link,
+      code: started.code,
+      expires_at: started.expiresAt,
+      private_key: privateKey
+    });
+    deps.stdout.write(waitingDocument(link, started.code, started.id));
+    return EXIT_WAITING;
+  }
+  deps.stderr.write(
+    `
+Open this link to sign in:
+  ${link}
+
+Check that the code it shows is ${started.code}.
+Waiting for approval...
+`
+  );
+  if (flags.browser) await deps.openBrowser(link);
+  const expiresAt = Date.parse(started.expiresAt);
+  let failures = 0;
+  for (; ; ) {
+    const result = await pollLogin(deps, dashboard, started.id);
+    let waitS = started.interval;
+    switch (result.kind) {
+      case "approved":
+        return await finishApproved(flags, deps, home, dashboard, result, privateKey);
+      case "denied":
+        return fail(deps, "the login was denied");
+      case "expired":
+        return fail(deps, "the login link expired; run outerlayer login again");
+      case "unavailable":
+      case "error":
+        failures += 1;
+        if (failures >= MAX_POLL_FAILURES) return fail(deps, `could not reach ${dashboard}: ${result.message}`);
+        break;
+      case "slow":
+        failures = 0;
+        waitS = result.retryAfterS;
+        break;
+      case "pending":
+        failures = 0;
+        break;
+    }
+    const untilExpiryMs = Math.max(0, expiresAt - deps.now().getTime());
+    await deps.sleep(Math.min(waitS * 1e3, untilExpiryMs));
+    if (deps.now().getTime() >= expiresAt) return fail(deps, "the login link expired; run outerlayer login again");
+  }
+}
+async function runLoginCommand(flags, deps) {
+  const home = deps.home ?? homeFromEnv();
+  try {
+    if (flags.check !== void 0) {
+      purgeExpiredPending(home, deps.now(), flags.check);
+      return await runCheck(flags, deps, home, flags.check);
+    }
+    const piped = await readPipedKey(deps.stdin, {
+      onWaiting: () => deps.stderr.write("login is waiting for an API key on stdin; close stdin or pass nothing to sign in by browser instead\n")
+    });
+    if (piped !== null) return await runPastedKey(flags, deps, piped, home);
+    if (flags.url !== void 0 || flags.appId !== void 0) {
+      deps.stderr.write(
+        `${C.red}\u2717${C.reset} --url and --app-id apply only to a piped key; browser login takes its gateway from the dashboard, and --dashboard <address> picks the dashboard
+`
+      );
+      return EXIT_USAGE;
+    }
+    if (flags.noInput) {
+      return fail(deps, 'no API key on stdin and --no-input forbids prompting \u2014 pipe the key: echo "$KEY" | outerlayer login');
+    }
+    purgeExpiredPending(home, deps.now());
+    return await runBrowserLogin(flags, deps, home);
+  } catch (err) {
+    if (err instanceof LoginError) return fail(deps, err.message);
+    throw err;
+  }
+}
+
+export { DEFAULT_DASHBOARD, readPipedKey, realLoginDeps, runLoginCommand, sanitizeMachineName, stdinKind };

package/dist/chunk-W4SQCOZU.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import { createRequire } from 'node:module';
+import { EXEC_PORT } from './chunk-B2G7JHHB.js';
+import { createConnection } from 'net';
+
+createRequire(import.meta.url);
+
+// src/runner/microvm/exec-protocol.ts
+var FRAME = { request: 1, stdin: 2, stdout: 3, stderr: 4, exit: 5, kill: 6 };
+var MAX_PAYLOAD = 16 * 1024 * 1024;
+var CHUNK_BYTES = 64 * 1024;
+var ProtocolError = class extends Error {
+};
+var TYPES = new Set(Object.values(FRAME));
+var HEADER_BYTES = 5;
+function encodeFrame(type, payload) {
+  const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+  if (body.length > MAX_PAYLOAD) throw new ProtocolError(`a frame's payload is ${body.length} bytes, past the ${MAX_PAYLOAD} limit`);
+  const header = Buffer.alloc(HEADER_BYTES);
+  header.writeUInt8(type, 0);
+  header.writeUInt32BE(body.length, 1);
+  return Buffer.concat([header, body]);
+}
+var FrameDecoder = class {
+  constructor() {
+    this.pending = Buffer.alloc(0);
+  }
+  push(chunk) {
+    this.pending = this.pending.length === 0 ? chunk : Buffer.concat([this.pending, chunk]);
+    const frames = [];
+    while (this.pending.length >= HEADER_BYTES) {
+      const type = this.pending.readUInt8(0);
+      const length = this.pending.readUInt32BE(1);
+      if (!TYPES.has(type)) throw new ProtocolError(`a frame has type ${type}, which no side sends`);
+      if (length > MAX_PAYLOAD) throw new ProtocolError(`a frame announces ${length} bytes, past the ${MAX_PAYLOAD} limit`);
+      if (this.pending.length < HEADER_BYTES + length) break;
+      frames.push({ type, payload: Buffer.from(this.pending.subarray(HEADER_BYTES, HEADER_BYTES + length)) });
+      this.pending = this.pending.subarray(HEADER_BYTES + length);
+    }
+    return frames;
+  }
+};
+function encodeRequest(request) {
+  const { argv, user, cwd, env } = request;
+  return Buffer.from(JSON.stringify({ argv, user, cwd, env }), "utf8");
+}
+function decodeExit(payload) {
+  if (payload.length !== 4) throw new ProtocolError(`an exit frame holds ${payload.length} bytes, not 4`);
+  return payload.readInt32BE(0);
+}
+
+// src/runner/microvm/exec-client.ts
+var ExecConnectionError = class extends Error {
+};
+var HANDSHAKE_LIMIT = 256;
+var HANDSHAKE_TIMEOUT_MS = 3e4;
+var CAPTURE_LIMIT_BYTES = 8 * 1024 * 1024;
+function runExec(socketPath, request, io = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(socketPath);
+    const decoder = new FrameDecoder();
+    let greeted = false;
+    let greeting = Buffer.alloc(0);
+    let settled = false;
+    let killed = false;
+    let stdinIterator;
+    const handshakeTimer = setTimeout(() => finish(new ExecConnectionError("the exec agent did not answer the connection in time")), HANDSHAKE_TIMEOUT_MS);
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(handshakeTimer);
+      io.signal?.removeEventListener("abort", kill);
+      void stdinIterator?.return?.();
+      socket.destroy();
+      if (outcome instanceof Error) reject(outcome);
+      else resolve(outcome);
+    };
+    const send = (type, payload) => socket.destroyed ? true : socket.write(encodeFrame(type, payload));
+    function kill() {
+      if (killed || !greeted) return;
+      killed = true;
+      send(FRAME.kill, Buffer.alloc(0));
+    }
+    const pumpStdin = async () => {
+      const stdin = io.stdin;
+      const chunks = (buffer) => Array.from({ length: Math.ceil(buffer.length / CHUNK_BYTES) }, (_unused, i) => buffer.subarray(i * CHUNK_BYTES, (i + 1) * CHUNK_BYTES));
+      try {
+        if (stdin === void 0) {
+        } else if (typeof stdin === "string" || Buffer.isBuffer(stdin)) {
+          for (const chunk of chunks(Buffer.from(stdin))) send(FRAME.stdin, chunk);
+        } else {
+          stdinIterator = stdin.iterator({ destroyOnReturn: false });
+          for (; ; ) {
+            const next = await stdinIterator.next();
+            if (next.done === true || settled) break;
+            for (const chunk of chunks(Buffer.from(next.value))) {
+              if (!send(FRAME.stdin, chunk)) await new Promise((done) => socket.once("drain", () => done()));
+            }
+          }
+        }
+      } catch {
+      }
+      send(FRAME.stdin, Buffer.alloc(0));
+    };
+    const onFrames = (chunk) => {
+      let frames;
+      try {
+        frames = decoder.push(chunk);
+      } catch (err) {
+        finish(new ExecConnectionError(`the guest's exec agent sent a bad frame: ${err instanceof Error ? err.message : String(err)}`));
+        return;
+      }
+      for (const frame of frames) {
+        if (frame.type === FRAME.stdout) io.onStdout?.(frame.payload);
+        else if (frame.type === FRAME.stderr) io.onStderr?.(frame.payload);
+        else if (frame.type === FRAME.exit) {
+          try {
+            finish({ status: decodeExit(frame.payload) });
+          } catch (err) {
+            finish(new ExecConnectionError(`the guest's exec agent sent a bad exit frame: ${err instanceof Error ? err.message : String(err)}`));
+          }
+          return;
+        }
+      }
+    };
+    socket.on("connect", () => socket.write(`CONNECT ${EXEC_PORT}
+`));
+    socket.on("data", (chunk) => {
+      if (greeted) {
+        onFrames(chunk);
+        return;
+      }
+      greeting = Buffer.concat([greeting, chunk]);
+      const newline = greeting.indexOf(10);
+      if (newline === -1) {
+        if (greeting.length > HANDSHAKE_LIMIT) finish(new ExecConnectionError("the vsock device's answer to CONNECT was not a line"));
+        return;
+      }
+      const line = greeting.subarray(0, newline).toString("utf8");
+      if (!/^OK\b/.test(line)) {
+        finish(new ExecConnectionError(`the vsock device refused the connection to the exec agent: ${line}`));
+        return;
+      }
+      greeted = true;
+      clearTimeout(handshakeTimer);
+      send(FRAME.request, encodeRequest(request));
+      if (io.signal?.aborted === true) kill();
+      void pumpStdin();
+      const rest = greeting.subarray(newline + 1);
+      if (rest.length > 0) onFrames(rest);
+    });
+    socket.on("error", (err) => finish(new ExecConnectionError(`the exec agent at ${socketPath} could not be reached: ${err.message}`)));
+    socket.on("close", () => finish(new ExecConnectionError("the connection to the exec agent ended before the command did")));
+    io.signal?.addEventListener("abort", kill, { once: true });
+  });
+}
+async function execCapture(socketPath, request, io = {}) {
+  const stdout = [];
+  const stderr = [];
+  const sizes = { stdout: 0, stderr: 0 };
+  const keep = (into, stream, chunk) => {
+    const room = CAPTURE_LIMIT_BYTES - sizes[stream];
+    if (room <= 0) return;
+    const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+    sizes[stream] += kept.length;
+    into.push(kept);
+  };
+  const { status } = await runExec(socketPath, request, { ...io, onStdout: (chunk) => keep(stdout, "stdout", chunk), onStderr: (chunk) => keep(stderr, "stderr", chunk) });
+  return { status, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8") };
+}
+async function waitForAgent(socketPath, options) {
+  for (let attempt = 0; attempt < options.attempts; attempt++) {
+    try {
+      await execCapture(socketPath, { argv: ["true"], user: "root", cwd: "/", env: {} });
+      return true;
+    } catch {
+      await options.sleep(options.delayMs);
+    }
+  }
+  return false;
+}
+function vmExecArgs(options) {
+  return [
+    "--socket",
+    options.socket,
+    "--user",
+    options.user,
+    "--cwd",
+    options.cwd,
+    ...Object.keys(options.env).sort().flatMap((name) => ["--env", `${name}=${options.env[name]}`]),
+    ...[...options.pass].sort().flatMap((name) => ["--pass", name]),
+    "--",
+    ...options.argv
+  ];
+}
+async function runVmExec(options, io) {
+  const env = { ...options.env };
+  for (const name of options.pass) {
+    const value = io.env[name];
+    if (value !== void 0) env[name] = value;
+  }
+  const { status } = await runExec(options.socket, { argv: options.argv, user: options.user, cwd: options.cwd, env }, { stdin: io.stdin, onStdout: io.stdout, onStderr: io.stderr, signal: io.signal });
+  return status;
+}
+
+export { CAPTURE_LIMIT_BYTES, ExecConnectionError, HANDSHAKE_TIMEOUT_MS, execCapture, runExec, runVmExec, vmExecArgs, waitForAgent };