agent-dev-env 0.1.0-canary.2.fbbd044

package/dist/lib/qemu.js

@@ -0,0 +1,373 @@
+// lib/qemu.ts — the QEMU/Windows backend's host-side helpers (Phase 6):
+// the working-VM state paths (COW overlay + persistent TPM + EFI NVRAM
+// under <data>/windows-qemu/<image>/working/), the backing-image identity
+// marker (a rebuild replaces the qcow2 at the same path — path alone
+// would silently stack the old overlay on a different base), the exact
+// `launch_qemu` args builder (same wiring the image was built with:
+// qemu-with-tpm.sh, minus the install media) and the swtpm/qemu process
+// management (pidfiles, stale-process kills, the pgrep fallback). Port of
+// run-windows-qemu-sandbox.sh §step 2/3/4 helpers + the stop script.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { commandExists, isAlive, readPidFile, run, sleep, spawnDetached } from './exec.js';
+import { logger } from './logger.js';
+import { imageRootDir, paths } from './paths.js';
+/** The platform id the qemu state paths are bound to. */
+const PLATFORM = 'windows-qemu';
+/** The address the guest reaches the host at (QEMU user-mode networking
+ *  NAT gateway — the host bridges bind 127.0.0.1 instead).
+ */
+export const QEMU_HOST_ALIAS = '10.0.2.2';
+/** Homebrew's qemu UEFI firmware (the efi_code in launch_qemu). */
+export const QEMU_EFI_CODE = '/opt/homebrew/share/qemu/edk2-aarch64-code.fd';
+/** Homebrew's qemu EFI vars template (seeded when the build output ships
+ *  no efivars.fd). */
+export const QEMU_EFI_VARS_TEMPLATE = '/opt/homebrew/share/qemu/edk2-arm-vars.fd';
+// --- state paths -------------------------------------------------------------
+/** <data>/windows-qemu/<image> — the per-image state root.
+ * @param image - The image name.
+ * @returns The state root.
+ */
+export function qemuStateDir(image) {
+    return imageRootDir(PLATFORM, image);
+}
+/** <data>/windows-qemu/<image>/image/<image>.qcow2 — the pristine disk
+ *  (or the local pull cache).
+ * @param image - The image name.
+ * @returns The pristine qcow2 path.
+ */
+export function qemuImagePath(image) {
+    return join(qemuStateDir(image), 'image', `${image}.qcow2`);
+}
+/** <data>/windows-qemu/<image>/working — the working VM state dir
+ *  (overlay, efivars.fd, tpm/, pidfiles, sockets).
+ * @param image - The image name.
+ * @returns The working dir.
+ */
+export function qemuWorkingDir(image) {
+    return join(qemuStateDir(image), 'working');
+}
+/** <data>/windows-qemu/<image>/working/<image>.qcow2 — the COW overlay
+ *  the running VM writes to.
+ * @param image - The image name.
+ * @returns The overlay path.
+ */
+export function qemuOverlayPath(image) {
+    return join(qemuWorkingDir(image), `${image}.qcow2`);
+}
+/** The backing-image identity marker (path|size|mtime of the pristine
+ *  disk the overlay was created from).
+ * @param image - The image name.
+ * @returns The marker path.
+ */
+export function qemuBackingMarker(image) {
+    return join(qemuWorkingDir(image), 'backing-image.txt');
+}
+/** The working VM's persistent EFI NVRAM store.
+ * @param image - The image name.
+ * @returns The efivars.fd path.
+ */
+export function qemuEfivarsPath(image) {
+    return join(qemuWorkingDir(image), 'efivars.fd');
+}
+/** The working VM's TPM state dir (Windows 11 needs TPM 2.0 and its
+ *  credentials must survive reboots).
+ * @param image - The image name.
+ * @returns The tpm dir.
+ */
+export function qemuTpmDir(image) {
+    return join(qemuWorkingDir(image), 'tpm');
+}
+/** The qemu pidfile the runner writes.
+ * @param image - The image name.
+ * @returns The qemu.pid path.
+ */
+export function qemuPidFile(image) {
+    return join(qemuWorkingDir(image), 'qemu.pid');
+}
+/** The swtpm pidfile (swtpm --pid writes it after daemonizing).
+ *
+ * @internal — test-only export; production callers go through
+ * startSwtpm/stopSwtpm, which read this pidfile themselves.
+ * @param image - The image name.
+ * @returns The swtpm.pid path.
+ */
+export function swtpmPidFile(image) {
+    return join(qemuWorkingDir(image), 'swtpm.pid');
+}
+/** The swtpm control socket qemu connects its chardev to.
+ * @param image - The image name.
+ * @returns The swtpm.sock path.
+ */
+export function swtpmSockPath(image) {
+    return join(qemuWorkingDir(image), 'swtpm.sock');
+}
+/** The swtpm log (level=20), next to the socket.
+ * @param image - The image name.
+ * @returns The swtpm.log path.
+ */
+function swtpmLogPath(image) {
+    return join(qemuWorkingDir(image), 'swtpm.log');
+}
+/** The qemu log (the running VM's stdout/stderr).
+ * @returns The log path under the CLI's log dir.
+ */
+export function qemuLogPath() {
+    return join(paths.logs, 'qemu-windows-11.log');
+}
+/** The pristine-disk identity (path|size|mtime; the same scheme as
+ *  vmware-image's archive marker — a rebuild packs the new image at the
+ *  SAME path, so the path alone misses it).
+ *
+ * @param path - The disk path.
+ * @param size - File size in bytes.
+ * @param mtimeMs - File mtime (ms since epoch).
+ * @returns The identity string.
+ */
+export function backingIdentity(path, size, mtimeMs) {
+    return `${path}|${size}|${Math.floor(mtimeMs / 1000)}`;
+}
+/** Builds the exact `launch_qemu` arg list (same wiring the image was
+ *  built with, minus the install media): virt machine, HVF, AAVMF UEFI,
+ *  swtpm TPM 2.0 (ppi=off avoids a QEMU 11.1 HVF regression), xhci +
+ *  keyboard + tablet, user-mode networking with the port forwards and
+ *  virtio-gpu-pci (the image's driver store resolves viogpudo, so
+ *  resizing the window changes the guest resolution).
+ *
+ * @param input - The resolved wiring.
+ * @returns The qemu-system-aarch64 arguments.
+ */
+export function buildQemuArgs(input) {
+    const hostfwd = [
+        `hostfwd=tcp:127.0.0.1:${input.sshPort}-:22`,
+        `hostfwd=tcp:127.0.0.1:${input.rdpPort}-:3389`,
+        `hostfwd=tcp:127.0.0.1:${input.openchamberPort}-:${input.openchamberPort}`,
+        `hostfwd=tcp:127.0.0.1:${input.winrmPort}-:5985`,
+    ].join(',');
+    return [
+        '-machine',
+        'virt,gic-version=max',
+        '-accel',
+        'hvf',
+        '-cpu',
+        'host',
+        '-smp',
+        String(input.cpuCount),
+        '-m',
+        String(input.memoryMb),
+        '-drive',
+        `if=pflash,format=raw,readonly=on,file=${input.efiCode}`,
+        '-drive',
+        `if=pflash,format=raw,file=${input.efivars}`,
+        '-drive',
+        `file=${input.overlay},if=virtio,format=qcow2`,
+        '-device',
+        'virtio-net-pci,netdev=net0',
+        '-netdev',
+        `user,id=net0,${hostfwd}`,
+        '-chardev',
+        `socket,id=chrtpm,path=${input.tpmSock}`,
+        '-tpmdev',
+        'emulator,id=tpm0,chardev=chrtpm',
+        '-device',
+        'tpm-tis-device,tpmdev=tpm0,ppi=off',
+        '-device',
+        'virtio-gpu-pci',
+        '-device',
+        'qemu-xhci,id=usb',
+        '-device',
+        'usb-kbd,bus=usb.0',
+        '-device',
+        'usb-tablet,bus=usb.0',
+        ...(input.headless ? ['-display', 'none'] : ['-display', 'cocoa,zoom-to-fit=on']),
+    ];
+}
+// --- prereq ------------------------------------------------------------------
+/** The qemu/swtpm prereq (same message as doctor).
+ */
+export function requireQemu() {
+    if (!commandExists('qemu-system-aarch64')) {
+        logger.die("qemu-system-aarch64 is not installed — run 'brew install qemu' first.");
+    }
+    if (!commandExists('qemu-img')) {
+        logger.die("qemu-img is not installed — run 'brew install qemu' first.");
+    }
+    if (!commandExists('swtpm')) {
+        logger.die("swtpm is not installed — run 'brew install swtpm' first.");
+    }
+}
+// --- process helpers ---------------------------------------------------------
+/** @internal — SIGTERM + poll up to 30 s (the stop script's kill_wait).
+ * @param label - The process label (qemu / swtpm).
+ * @param pid - The pid to stop.
+ * @returns True when the process is gone.
+ */
+async function killWait(label, pid) {
+    if (!isAlive(pid)) {
+        logger.info(`${label} is already stopped (pid ${pid} is not running).`);
+        return true;
+    }
+    logger.cmd(`kill ${pid}`);
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        // already gone
+    }
+    process.stdout.write(`    Waiting for ${label} to stop`);
+    for (let n = 0; n < 30; n += 1) {
+        if (!isAlive(pid)) {
+            process.stdout.write(` ${logger.color('green')}stopped${logger.reset()}\n`);
+            return true;
+        }
+        await sleep(1000);
+    }
+    process.stdout.write(` ${logger.color('yellow')}failed${logger.reset()}\n`);
+    logger.warn(`${label} (pid ${pid}) did not stop after 30 s — kill it manually with: kill -9 ${pid}`);
+    return false;
+}
+/** Whether a runner-launched qemu is alive (pidfile first, then the
+ *  overlay-path pgrep fallback — the path is unique to this sandbox).
+ *
+ * @param image - The image name.
+ * @returns True when qemu is running.
+ */
+export function isQemuAlive(image) {
+    const pid = readPidFile(qemuPidFile(image));
+    if (pid !== undefined) {
+        return isAlive(pid);
+    }
+    return false;
+}
+/** @internal — runner-launched qemu pids by overlay path command line
+ *  (a pidfile-less qemu from a crashed run).
+ * @param image - The image name.
+ * @returns The pids, in pgrep order.
+ */
+async function findQemuPids(image) {
+    const res = await run('pgrep', ['-f', `qemu-system-aarch64.*${qemuStateDir(image)}`]);
+    if (res.code !== 0) {
+        return [];
+    }
+    return res.stdout
+        .split('\n')
+        .map((line) => Number.parseInt(line.trim(), 10))
+        .filter((pid) => Number.isInteger(pid) && pid > 0);
+}
+/** Stops the sandbox qemu (pidfile first, pgrep fallback) — the stop
+ *  script's stop_qemu. Idempotent.
+ *
+ * @param image - The image name.
+ */
+export async function stopQemu(image) {
+    const pidfile = qemuPidFile(image);
+    const pid = readPidFile(pidfile);
+    if (pid !== undefined) {
+        if (isAlive(pid)) {
+            await killWait('qemu', pid);
+            rmSync(pidfile, { force: true });
+            return;
+        }
+        logger.info(`qemu (pid ${pid}) is not running — removing the stale pidfile.`);
+        rmSync(pidfile, { force: true });
+    }
+    const pids = await findQemuPids(image);
+    if (pids.length === 0) {
+        logger.info('qemu is not running — nothing to stop.');
+        return;
+    }
+    logger.warn(`A sandbox qemu is running (pid(s): ${pids.join(', ')}) with no pidfile — stopping it.`);
+    for (const running of pids) {
+        await killWait('qemu', running);
+    }
+}
+/** Stops swtpm (it otherwise holds the TPM state lock and blocks the next
+ *  run) and removes the stale pidfile + socket. Idempotent.
+ *
+ * @param image - The image name.
+ */
+export async function stopSwtpm(image) {
+    const pidfile = swtpmPidFile(image);
+    const pid = readPidFile(pidfile);
+    if (pid !== undefined) {
+        if (isAlive(pid)) {
+            await killWait('swtpm', pid);
+        }
+        else {
+            logger.info(`swtpm (pid ${pid}) is not running — removing the stale pidfile.`);
+        }
+    }
+    else {
+        logger.info(`No swtpm pidfile (${pidfile}) — nothing to stop.`);
+    }
+    rmSync(pidfile, { force: true });
+    rmSync(swtpmSockPath(image), { force: true });
+}
+/** Starts swtpm (TPM 2.0; the state must persist for the credentials
+ *  inside the guest to keep working). A stale swtpm from a previous run
+ *  holds a lock on the TPM state dir — kill it first like the shell.
+ *
+ * @param image - The image name.
+ * @returns The daemonized swtpm pid.
+ */
+export async function startSwtpm(image) {
+    const sock = swtpmSockPath(image);
+    const pidfile = swtpmPidFile(image);
+    const tpm = qemuTpmDir(image);
+    const old = readPidFile(pidfile);
+    if (old !== undefined && isAlive(old)) {
+        logger.warn(`stale swtpm (pid ${old}) still running — stopping it.`);
+        try {
+            process.kill(old, 'SIGTERM');
+        }
+        catch {
+            // already gone
+        }
+        await sleep(1000);
+    }
+    rmSync(sock, { force: true });
+    rmSync(pidfile, { force: true });
+    mkdirSync(tpm, { recursive: true });
+    logger.cmd(`swtpm socket --tpm2 --tpmstate dir=${tpm} --ctrl type=unixio,path=${sock}`);
+    const res = await run('swtpm', [
+        'socket',
+        '--tpmstate',
+        `dir=${tpm}`,
+        '--ctrl',
+        `type=unixio,path=${sock}`,
+        '--log',
+        `file=${swtpmLogPath(image)},level=20`,
+        '--pid',
+        `file=${pidfile}`,
+        '--tpm2',
+        '--daemon',
+    ]);
+    if (res.code !== 0) {
+        logger.die(`swtpm failed to start:\n${res.stderr.trim()}`);
+    }
+    for (let n = 0; n < 10 && !existsSync(sock); n += 1) {
+        await sleep(1000);
+    }
+    if (!existsSync(sock)) {
+        logger.die(`swtpm socket ${sock} did not appear (see ${swtpmLogPath(image)}).`);
+    }
+    const pid = readPidFile(pidfile) ?? -1;
+    logger.ok(`swtpm is up (pid ${pid}).`);
+    return pid;
+}
+/** Launches qemu detached (the VM outlives the CLI by design; the log
+ *  gets stdout+stderr) and records the pidfile for stop/status.
+ *
+ * @param image - The image name.
+ * @param args - The qemu-system-aarch64 arguments (buildQemuArgs).
+ * @returns The qemu pid.
+ */
+export async function launchQemu(image, args) {
+    const logDir = dirname(qemuLogPath());
+    mkdirSync(logDir, { recursive: true });
+    logger.cmd(`qemu-system-aarch64 ${args.join(' ')}`);
+    logger.info(`Running the VM in the background (output: ${qemuLogPath()}).`);
+    const pid = spawnDetached('qemu-system-aarch64', args, { logFile: qemuLogPath() });
+    writeFileSync(qemuPidFile(image), `${pid}\n`);
+    return pid;
+}

package/dist/lib/regex.js

@@ -0,0 +1,9 @@
+// regex.ts — tiny shared helpers.
+/** Escapes a string so it matches literally in a RegExp.
+ *
+ * @param text - The string to escape.
+ * @returns The escaped pattern fragment.
+ */
+export function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/lib/ssh.js

@@ -0,0 +1,230 @@
+// lib/ssh.ts — the ssh2 transport: the unified replacement for the shell
+// runners' expect/perl/system-ssh glue (guest_sh, settings_ssh,
+// settings_scp and the BatchMode sshd probe). Password auth only (the
+// sandbox images' fixed user/password from the vars file), host-key
+// verification skipped (StrictHostKeyChecking=no + UserKnownHostsFile=
+// /dev/null parity), commands run pty-less so `sudo -S` reads the
+// password from stdin — the same semantics as the shell's expect sessions.
+//
+// The runner-facing surface is the SshSession interface (exec + sftpWrite
+// + end), implemented on top of a single ssh2 Client per session, so the
+// guest-side modules never touch ssh2 directly and can be unit-tested
+// with a fake session.
+import { Client } from 'ssh2';
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+/** @internal — classifies a connection-error message (exported for the
+ *  co-located unit tests; the transport keeps it internal).
+ *
+ * @param message - The Error message from ssh2's `error` event.
+ * @returns `up` when sshd answered (auth failed / handshake started),
+ *   `down` on connect-level failures, `unknown` otherwise.
+ */
+export function sshProbeOutcome(message) {
+    if (/authentication|permission denied|key exchange|protocol/i.test(message)) {
+        return 'up';
+    }
+    if (/ECONNREFUSED|ECONNRESET|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH/i.test(message)) {
+        return 'down';
+    }
+    return 'unknown';
+}
+/** Opens a password-authenticated session.
+ *
+ * @param credentials - Host/port/user/password.
+ * @param readyTimeoutMs - Connect handshake budget (default 15 s).
+ * @returns A connected session (throws when the handshake fails).
+ */
+export async function openSshSession(credentials, readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const client = new Client();
+        let settled = false;
+        client.on('error', (err) => {
+            if (settled) {
+                // Post-ready errors surface on the channels; a listener must stay
+                // attached or the event would crash the process.
+                return;
+            }
+            settled = true;
+            reject(err);
+        });
+        client.once('ready', () => {
+            settled = true;
+            resolve(createSession(client));
+        });
+        client.connect({
+            host: credentials.host,
+            port: credentials.port,
+            username: credentials.username,
+            password: credentials.password,
+            readyTimeout: readyTimeoutMs,
+            // StrictHostKeyChecking=no + UserKnownHostsFile=/dev/null parity.
+            hostVerifier: () => true,
+        });
+    });
+}
+function createSession(client) {
+    let ended = false;
+    return {
+        exec: (command, options = {}) => execOn(client, command, options),
+        sftpWrite: (remotePath, data) => sftpWrite(client, remotePath, data),
+        end: () => {
+            if (!ended) {
+                ended = true;
+                client.end();
+            }
+        },
+    };
+}
+/** One remote command via `client.exec` — the expect `spawn ssh … $cmd`
+ *  equivalent. Safe against the legacy hang edge cases: a watchdog
+ *  terminates the session when the remote never closes the channel, and a
+ *  sentinel ends the exec as soon as the remote command echoes it (the
+ *  Windows OpenSSH channel never closes on its own when guest background
+ *  relays hold the console handles — the shell's `echo $sentinel` trick).
+ *
+ * @param client - The connected ssh2 client.
+ * @param command - The remote shell command.
+ * @param options - stdin payload, a hard timeout and/or the completion
+ *   sentinel.
+ * @returns The remote exit code + collected output.
+ */
+function execOn(client, command, options) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let watchdog;
+        if (options.timeoutMs !== undefined) {
+            watchdog = setTimeout(() => {
+                if (!settled) {
+                    settled = true;
+                    resolve({
+                        code: -1,
+                        stdout: '',
+                        stderr: `remote command timed out (${options.timeoutMs} ms): ${command}`,
+                    });
+                    client.destroy();
+                }
+            }, options.timeoutMs);
+        }
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (watchdog !== undefined) {
+                clearTimeout(watchdog);
+            }
+            resolve(result);
+        };
+        client.exec(command, (err, stream) => {
+            if (err) {
+                finish({ code: -1, stdout: '', stderr: err.message });
+                return;
+            }
+            runChannel(stream, options.input, options.sentinel, finish);
+        });
+    });
+}
+/** Collects one exec channel: stdout/stderr until close, stdin payload
+ *  written and ended. When a sentinel is given, the exec finishes (and the
+ *  channel is destroyed) as soon as the sentinel shows up on stdout — the
+ *  completion marker the command echoed after its payload exited; the
+ *  leftover output after it belongs to the guest's background relays.
+ *
+ * @param stream - The ssh2 exec channel.
+ * @param input - Optional remote stdin payload.
+ * @param sentinel - Optional completion marker to look for on stdout.
+ * @param finish - The single-settle callback.
+ */
+function runChannel(stream, input, sentinel, finish) {
+    let stdout = '';
+    let stderr = '';
+    stream.on('data', (chunk) => {
+        stdout += chunk.toString();
+        if (sentinel && stdout.includes(sentinel)) {
+            finish({ code: 0, stdout, stderr });
+            // Under the guest's control now — killing the channel is exactly
+            // what the shell's `exec kill [exp_pid]` did: sshd cleans up the
+            // hung session instead of our client waiting for a close that never
+            // comes.
+            stream.destroy();
+        }
+    });
+    stream.stderr.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    stream.on('error', (streamErr) => {
+        finish({ code: -1, stdout, stderr: streamErr.message });
+    });
+    stream.on('close', (code) => {
+        finish({ code: code ?? -1, stdout, stderr });
+    });
+    if (input !== undefined) {
+        stream.write(input);
+    }
+    stream.end();
+}
+/** Uploads bytes to a remote file (SFTP writeFile; parent dirs must
+ *  exist — the callers mkdir first).
+ *
+ * @param client - The connected ssh2 client.
+ * @param remotePath - The destination path in the guest.
+ * @param data - The file content.
+ */
+function sftpWrite(client, remotePath, data) {
+    return new Promise((resolve, reject) => {
+        client.sftp((err, sftp) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            sftp.writeFile(remotePath, data, (writeErr) => {
+                sftp.end();
+                if (writeErr) {
+                    reject(writeErr);
+                    return;
+                }
+                resolve();
+            });
+        });
+    });
+}
+/** Probes whether sshd is up at a host — one connect attempt. An auth
+ *  error means the server answered (the legacy "Permission denied →
+ *  ready" semantics); anything else depends on the failure kind.
+ *  Exported for the QEMU backend's boot loop, which interleaves the
+ *  probe with a qemu-alive check (waitForSshd polls unattended).
+ *
+ * @param credentials - The probe target.
+ * @param readyTimeoutMs - Handshake budget (default 15 s).
+ * @returns The classified outcome.
+ */
+export async function probeSshd(credentials, readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS) {
+    try {
+        const session = await openSshSession(credentials, readyTimeoutMs);
+        session.end();
+        return 'up';
+    }
+    catch (err) {
+        return sshProbeOutcome(err.message);
+    }
+}
+/** Polls until sshd answers (the legacy wait_for_sshd, 150 x 4 s).
+ *
+ * @param credentials - The guest to probe.
+ * @param options - Poll count/delay + per-attempt budget.
+ * @returns True when sshd came up within the window.
+ */
+export async function waitForSshd(credentials, options = {}) {
+    const tries = options.tries ?? 150;
+    const delayMs = options.delayMs ?? 4000;
+    for (let attempt = 0; attempt < tries; attempt += 1) {
+        const outcome = await probeSshd(credentials, options.readyTimeoutMs);
+        if (outcome === 'up') {
+            return true;
+        }
+        if (attempt < tries - 1) {
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+    return false;
+}