vmsan 0.1.0-alpha.15 → 0.1.0-alpha.16

package/dist/_chunks/agent.mjs

@@ -1,6 +1,196 @@
 import { createGzip } from "node:zlib";
 import { Readable } from "node:stream";
 import { pack } from "tar-stream";
+/**
+* Lightweight async iterable queue for pushing events and yielding them to consumers.
+*/
+var AsyncQueue = class {
+	_buffer = [];
+	_waiting = [];
+	_closed = false;
+	push(item) {
+		if (this._closed) return;
+		if (this._waiting.length > 0) this._waiting.shift()({
+			value: item,
+			done: false
+		});
+		else this._buffer.push(item);
+	}
+	close() {
+		this._closed = true;
+		for (const resolve of this._waiting) resolve({
+			value: void 0,
+			done: true
+		});
+		this._waiting.length = 0;
+	}
+	async *[Symbol.asyncIterator]() {
+		while (true) if (this._buffer.length > 0) yield this._buffer.shift();
+		else if (this._closed) return;
+		else {
+			const item = await new Promise((resolve) => {
+				this._waiting.push(resolve);
+			});
+			if (item.done) return;
+			yield item.value;
+		}
+	}
+};
+var CommandFinished = class {
+	cmdId;
+	exitCode;
+	stdout;
+	stderr;
+	output;
+	timedOut;
+	startedAt;
+	constructor(opts) {
+		this.cmdId = opts.cmdId;
+		this.exitCode = opts.exitCode;
+		this.stdout = opts.stdout;
+		this.stderr = opts.stderr;
+		this.output = opts.output;
+		this.timedOut = opts.timedOut;
+		this.startedAt = opts.startedAt;
+	}
+	get ok() {
+		return this.exitCode === 0;
+	}
+};
+const MAX_LOG_ENTRIES = 1e5;
+var Command = class {
+	cmdId;
+	_startedAt;
+	_exitCode = null;
+	_timedOut = false;
+	_logEntries = [];
+	_logTruncated = false;
+	_eventQueue = new AsyncQueue();
+	_completion;
+	_stdoutPromise = null;
+	_stderrPromise = null;
+	_outputPromise = null;
+	_agent;
+	constructor(init) {
+		const { agent, cmdId, startedAt, stream, signal, onStdout, onStderr } = init;
+		this._agent = agent;
+		this.cmdId = cmdId;
+		this._startedAt = startedAt;
+		let resolveCompletion;
+		let rejectCompletion;
+		this._completion = new Promise((resolve, reject) => {
+			resolveCompletion = resolve;
+			rejectCompletion = reject;
+		});
+		let onAbort;
+		if (signal) {
+			onAbort = () => {
+				this.kill().catch(() => {});
+			};
+			if (signal.aborted) this.kill().catch(() => {});
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+		(async () => {
+			try {
+				for await (const event of stream) {
+					this._eventQueue.push(event);
+					switch (event.type) {
+						case "stdout":
+						case "stderr":
+							if (event.data !== void 0) {
+								if (this._logEntries.length < MAX_LOG_ENTRIES) this._logEntries.push({
+									stream: event.type,
+									data: event.data
+								});
+								else this._logTruncated = true;
+								(event.type === "stdout" ? onStdout : onStderr)?.(event.data);
+							}
+							break;
+						case "exit":
+							this._exitCode = event.exitCode ?? 1;
+							break;
+						case "timeout":
+							this._timedOut = true;
+							this._exitCode = 124;
+							break;
+						case "error":
+							this._exitCode = 1;
+							break;
+					}
+				}
+				this._eventQueue.close();
+				resolveCompletion(new CommandFinished({
+					cmdId,
+					exitCode: this._exitCode ?? 1,
+					stdout: this._logEntries.filter((e) => e.stream === "stdout").map((e) => e.data).join("\n"),
+					stderr: this._logEntries.filter((e) => e.stream === "stderr").map((e) => e.data).join("\n"),
+					output: this._logEntries.map((e) => e.data).join("\n"),
+					timedOut: this._timedOut,
+					startedAt
+				}));
+				this._logEntries.length = 0;
+			} catch (err) {
+				this._eventQueue.close();
+				const error = err instanceof Error ? err : new Error(String(err));
+				rejectCompletion(error);
+			} finally {
+				if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+			}
+		})();
+	}
+	get startedAt() {
+		return this._startedAt;
+	}
+	get exitCode() {
+		return this._exitCode;
+	}
+	async *logs(opts) {
+		const signal = opts?.signal;
+		if (signal?.aborted) return;
+		for await (const event of this._eventQueue) {
+			if (signal?.aborted) return;
+			if (event.type === "stdout" || event.type === "stderr") yield {
+				stream: event.type,
+				data: event.data ?? ""
+			};
+		}
+	}
+	stdout(opts) {
+		if (!this._stdoutPromise) this._stdoutPromise = this._completion.then((r) => r.stdout);
+		return this._withSignal(this._stdoutPromise, opts?.signal);
+	}
+	stderr(opts) {
+		if (!this._stderrPromise) this._stderrPromise = this._completion.then((r) => r.stderr);
+		return this._withSignal(this._stderrPromise, opts?.signal);
+	}
+	output(stream, opts) {
+		if (stream === "stdout") return this.stdout(opts);
+		if (stream === "stderr") return this.stderr(opts);
+		if (!this._outputPromise) this._outputPromise = this._completion.then((r) => r.output);
+		return this._withSignal(this._outputPromise, opts?.signal);
+	}
+	wait(opts) {
+		return this._withSignal(this._completion, opts?.signal);
+	}
+	async kill(signal, opts) {
+		await this._agent.killCommand(this.cmdId, signal, opts?.abortSignal);
+	}
+	_withSignal(promise, signal) {
+		if (!signal) return promise;
+		if (signal.aborted) return Promise.reject(new DOMException("The operation was aborted.", "AbortError"));
+		return new Promise((resolve, reject) => {
+			const onAbort = () => reject(new DOMException("The operation was aborted.", "AbortError"));
+			signal.addEventListener("abort", onAbort, { once: true });
+			promise.then((value) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(value);
+			}, (err) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(err);
+			});
+		});
+	}
+};
 var AgentClient = class {
 	constructor(baseUrl, token) {
 		this.baseUrl = baseUrl;
@@ -11,14 +201,15 @@ var AgentClient = class {
 		if (!res.ok) throw new Error(`Agent health check failed: ${res.status}`);
 		return res.json();
 	}
-	async *run(params) {
+	async *run(params, signal) {
 		const res = await fetch(`${this.baseUrl}/exec`, {
 			method: "POST",
 			headers: {
 				"Content-Type": "application/json",
 				Authorization: `Bearer ${this.token}`
 			},
-			body: JSON.stringify(params)
+			body: JSON.stringify(params),
+			signal
 		});
 		if (!res.ok) {
 			const text = await res.text();
@@ -41,7 +232,7 @@ var AgentClient = class {
 		}
 		if (buffer.trim()) yield JSON.parse(buffer.trim());
 	}
-	async killCommand(cmdId, signal) {
+	async killCommand(cmdId, signal, abortSignal) {
 		const url = `${this.baseUrl}/exec/${cmdId}/kill`;
 		const res = await fetch(url, {
 			method: "POST",
@@ -49,7 +240,8 @@ var AgentClient = class {
 				"Content-Type": "application/json",
 				Authorization: `Bearer ${this.token}`
 			},
-			body: signal ? JSON.stringify({ signal }) : void 0
+			body: signal ? JSON.stringify({ signal }) : void 0,
+			signal: abortSignal
 		});
 		if (!res.ok) {
 			const text = await res.text();
@@ -94,6 +286,41 @@ var AgentClient = class {
 			throw new Error(`Agent killShellSession failed (${res.status}): ${text}`);
 		}
 	}
+	async exec(params, opts) {
+		const stream = this.run(params, opts?.signal);
+		const first = await stream.next();
+		if (first.done) throw new Error("Stream ended without 'started' event");
+		if (first.value.type !== "started") throw new Error(`Expected 'started' event, got '${first.value.type}'`);
+		const cmdId = first.value.id;
+		if (!cmdId) throw new Error("'started' event missing 'id' field");
+		const startedAt = first.value.ts ? new Date(first.value.ts) : /* @__PURE__ */ new Date();
+		return new Command({
+			agent: this,
+			cmdId,
+			startedAt,
+			stream,
+			signal: opts?.signal,
+			onStdout: opts?.onStdout,
+			onStderr: opts?.onStderr
+		});
+	}
+	async runCommand(cmdOrParams, args, opts) {
+		let params;
+		if (typeof cmdOrParams === "string") params = {
+			cmd: cmdOrParams,
+			args,
+			signal: opts?.signal
+		};
+		else params = cmdOrParams;
+		const { signal, onStdout, onStderr, ...runParams } = params;
+		const command = await this.exec(runParams, {
+			signal,
+			onStdout,
+			onStderr
+		});
+		if (params.detached) return command;
+		return command.wait({ signal });
+	}
 	async readFile(path) {
 		const res = await fetch(`${this.baseUrl}/files/read`, {
 			method: "POST",

package/dist/_chunks/context.mjs

@@ -2,9 +2,10 @@ import { n as vmsanPaths } from "./paths.mjs";
 import { B as mutuallyExclusiveFlagsError, C as vmNotStoppedError, S as vmNotRunningError, U as VmsanError, _ as chrootNotFoundError, a as noKernelDirError, d as socketTimeoutError, i as noExt4RootfsError, o as noKernelError, p as defaultInterfaceNotFoundError, r as missingBinaryError, s as noRootfsDirError, u as lockTimeoutError, x as vmNotFoundError, y as snapshotNotFoundError } from "./errors.mjs";
 import { c as safeKill, f as toError, i as generateVmId, t as FileVmStateStore } from "./vm-state.mjs";
 import { t as FirecrackerClient } from "./firecracker.mjs";
+import { t as spawnTimeoutKiller } from "./timeout-killer.mjs";
 import { createHooks } from "hookable";
 import { dirname, join } from "node:path";
-import { execFileSync, execSync, spawn } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { consola } from "consola";
 import { randomBytes } from "node:crypto";
@@ -1825,37 +1826,6 @@ function ensureSeccompFilter(paths) {
 		return null;
 	}
 }
-/**
-* Spawn a detached bash process that kills the VM after timeout.
-* The process sleeps for the timeout duration, then verifies the VM
-* is still running with the expected PID before sending SIGTERM.
-*/
-function spawnTimeoutKiller(opts) {
-	const { vmId, pid, timeoutMs, stateFile } = opts;
-	const timeoutSec = String(Math.ceil(timeoutMs / 1e3));
-	const killer = spawn("bash", [
-		"-c",
-		[
-			"sleep \"$1\"",
-			"STATE=$(cat -- \"$2\" 2>/dev/null) || exit 0",
-			"echo \"$STATE\" | grep -q '\"status\":\"running\"' || exit 0",
-			"echo \"$STATE\" | grep -q \"\"pid\":$3\" || exit 0",
-			"[ -d \"/proc/$3\" ] || exit 0",
-			"grep -aq -- \"$4\" \"/proc/$3/cmdline\" 2>/dev/null || exit 0",
-			"kill -- \"$3\" 2>/dev/null"
-		].join(" && "),
-		"bash",
-		timeoutSec,
-		stateFile,
-		String(pid),
-		vmId
-	], {
-		detached: true,
-		stdio: "ignore"
-	});
-	killer.unref();
-	return killer;
-}
 var VMService = class {
 	paths;
 	store;
@@ -2394,4 +2364,4 @@ async function createVmsan(options) {
 	if (options?.plugins) for (const plugin of options.plugins) await plugin.setup(ctx);
 	return vmsan;
 }
-export { createDefaultLogger as C, NetworkManager as S, validateEnvironment as _, ensureSeccompFilter as a, detectCgroupVersion as b, cleanupChroot as c, markVmAsError as d, assertSnapshotExists as f, getVmPid as g, getVmJailerPid as h, compileSeccompFilter as i, cleanupNetwork as l, findRootfs as m, VMService as n, resolveImageRootfs as o, findKernel as p, spawnTimeoutKiller as r, buildInitialVmState as s, createVmsan as t, killOrphanVmProcess as u, waitForSocket as v, createSilentLogger as w, FileLock as x, Jailer as y };
+export { createSilentLogger as C, createDefaultLogger as S, waitForSocket as _, resolveImageRootfs as a, FileLock as b, cleanupNetwork as c, assertSnapshotExists as d, findKernel as f, validateEnvironment as g, getVmPid as h, ensureSeccompFilter as i, killOrphanVmProcess as l, getVmJailerPid as m, VMService as n, buildInitialVmState as o, findRootfs as p, compileSeccompFilter as r, cleanupChroot as s, createVmsan as t, markVmAsError as u, Jailer as v, NetworkManager as x, detectCgroupVersion as y };

package/dist/_chunks/create.mjs

@@ -4,6 +4,7 @@ import { i as initVmsanLogger, n as createScopedLogger, t as createCommandLogger
 import "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { n as waitForAgent } from "./vm-context.mjs";
 import { t as ShellSession } from "./shell.mjs";
 import { a as parseImageReference, t as parseBandwidth } from "./validation.mjs";

package/dist/_chunks/exec.mjs

@@ -0,0 +1,193 @@
+import { n as vmsanPaths } from "./paths.mjs";
+import { t as handleCommandError } from "./errors.mjs";
+import { t as createCommandLogger } from "./logger.mjs";
+import "./vm-state.mjs";
+import "./timeout-killer.mjs";
+import { t as AgentClient } from "./agent.mjs";
+import { t as TimeoutExtender } from "./timeout-extender.mjs";
+import { n as waitForAgent, t as resolveVmState } from "./vm-context.mjs";
+import { t as ShellSession } from "./shell.mjs";
+import { consola } from "consola";
+import { defineCommand } from "citty";
+import { isatty } from "node:tty";
+function shellEscape(s) {
+	if (/^[a-zA-Z0-9._\-/=:@]+$/.test(s)) return s;
+	return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function parseEnvFlags(targetCommand) {
+	const env = {};
+	const argv = process.argv;
+	let positionalCount = 0;
+	for (let i = 2; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--") break;
+		if (!arg.startsWith("-")) {
+			positionalCount++;
+			if (positionalCount >= 3) break;
+			continue;
+		}
+		let value;
+		if (arg === "--env" || arg === "-e") {
+			value = argv[i + 1];
+			if (value !== void 0) i++;
+		} else if (arg.startsWith("--env=")) value = arg.slice(6);
+		else if (arg.startsWith("-e=")) value = arg.slice(3);
+		if (value !== void 0) {
+			const eqIdx = value.indexOf("=");
+			if (eqIdx > 0) env[value.slice(0, eqIdx)] = value.slice(eqIdx + 1);
+		}
+	}
+	return env;
+}
+function buildVmsanPrompt(vmId) {
+	return `\\[\\033[1;32m\\]vmsan:${vmId.slice(0, 8)}\\[\\033[0m\\]:\\[\\033[1;34m\\]\\w\\[\\033[0m\\]\\$ `;
+}
+const execCommand = defineCommand({
+	meta: {
+		name: "exec",
+		description: "Execute a command inside a running VM"
+	},
+	args: {
+		vmId: {
+			type: "positional",
+			description: "VM ID, followed by command and arguments",
+			required: true
+		},
+		sudo: {
+			type: "boolean",
+			default: false,
+			description: "Run with extended privileges (sudo)"
+		},
+		interactive: {
+			type: "boolean",
+			alias: "i",
+			default: false,
+			description: "Interactive shell mode (PTY)"
+		},
+		"no-extend-timeout": {
+			type: "boolean",
+			default: false,
+			description: "Skip timeout extension (interactive only)"
+		},
+		tty: {
+			type: "boolean",
+			alias: "t",
+			default: false,
+			description: "Allocate a pseudo-TTY (accepted for compatibility)"
+		},
+		workdir: {
+			type: "string",
+			alias: "w",
+			description: "Working directory inside the VM"
+		},
+		env: {
+			type: "string",
+			alias: "e",
+			description: "Environment variable (KEY=VAL), repeatable"
+		}
+	},
+	async run({ args }) {
+		const cmdLog = createCommandLogger("exec");
+		const paths = vmsanPaths();
+		try {
+			const command = args._[1];
+			const commandArgs = args._.slice(2);
+			if (!command) {
+				consola.error("No command provided. Usage: vmsan exec <vm_id> <command> [...args]");
+				cmdLog.emit();
+				process.exitCode = 1;
+				return;
+			}
+			if (args.interactive && !isatty(1)) {
+				consola.error("--interactive requires a terminal (TTY).");
+				process.exitCode = 1;
+				return;
+			}
+			const envVars = parseEnvFlags(command);
+			const { state, guestIp, port, store } = resolveVmState(args.vmId, paths);
+			consola.debug(`Agent endpoint: ${guestIp}:${port}`);
+			const log = consola.withTag(args.vmId);
+			log.start("Waiting for agent...");
+			await waitForAgent(guestIp, port);
+			if (args.interactive) {
+				const parts = [];
+				parts.push(`export PS1=${shellEscape(buildVmsanPrompt(args.vmId))} TERM=xterm-256color &&`);
+				if (args.workdir) parts.push(`cd ${shellEscape(args.workdir)} &&`);
+				for (const [key, val] of Object.entries(envVars)) parts.push(`${key}=${shellEscape(val)}`);
+				if (args.sudo) parts.push("sudo");
+				parts.push(shellEscape(command));
+				for (const a of commandArgs) parts.push(shellEscape(a));
+				const injectedCmd = parts.join(" ") + "; exit $?\n";
+				log.success("Agent is ready. Connecting interactive shell...");
+				let extender = null;
+				if (!args["no-extend-timeout"] && state.timeoutMs) {
+					extender = new TimeoutExtender({
+						vmId: args.vmId,
+						store,
+						paths
+					});
+					extender.start();
+				}
+				try {
+					await new ShellSession({
+						host: guestIp,
+						port,
+						token: state.agentToken,
+						initialCommand: injectedCmd
+					}).connect();
+				} finally {
+					extender?.stop();
+				}
+				cmdLog.set({
+					vmId: args.vmId,
+					mode: "interactive",
+					command,
+					args: commandArgs,
+					...args["no-extend-timeout"] && { noExtendTimeout: true }
+				});
+				cmdLog.emit();
+			} else {
+				consola.debug(`exec: ${command} ${commandArgs.join(" ")}`);
+				const agent = new AgentClient(`http://${guestIp}:${port}`, state.agentToken);
+				const cmd = args.sudo ? "sudo" : command;
+				const runArgs = args.sudo ? [command, ...commandArgs] : commandArgs;
+				const params = {
+					cmd,
+					args: runArgs.length > 0 ? runArgs : void 0,
+					cwd: args.workdir || void 0,
+					env: Object.keys(envVars).length > 0 ? envVars : void 0
+				};
+				const ac = new AbortController();
+				const onSignal = () => ac.abort();
+				process.on("SIGINT", onSignal);
+				process.on("SIGTERM", onSignal);
+				try {
+					const result = await (await agent.exec(params, {
+						signal: ac.signal,
+						onStdout: (line) => process.stdout.write(line + "\n"),
+						onStderr: (line) => process.stderr.write(line + "\n")
+					})).wait();
+					process.exitCode = result.exitCode;
+					if (result.timedOut) consola.error("Command timed out.");
+				} catch (err) {
+					if (!ac.signal.aborted) throw err;
+					process.exitCode = 130;
+				} finally {
+					process.removeListener("SIGINT", onSignal);
+					process.removeListener("SIGTERM", onSignal);
+				}
+				cmdLog.set({
+					vmId: args.vmId,
+					mode: "non-interactive",
+					command,
+					args: commandArgs
+				});
+				cmdLog.emit();
+			}
+		} catch (error) {
+			handleCommandError(error, cmdLog);
+			process.exitCode = 1;
+		}
+	}
+});
+export { execCommand as default };

package/dist/_chunks/list.mjs

@@ -4,6 +4,7 @@ import { r as getOutputMode, t as createCommandLogger } from "./logger.mjs";
 import { d as timeRemaining, l as table, u as timeAgo } from "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { consola } from "consola";
 import { defineCommand } from "citty";
 const STATUS_COLORS = {

package/dist/_chunks/network.mjs

@@ -4,6 +4,7 @@ import { r as getOutputMode, t as createCommandLogger } from "./logger.mjs";
 import "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { d as validateCidr, i as parseDomains, n as parseCidrList, s as parseNetworkPolicy } from "./validation.mjs";
 import { consola } from "consola";
 import { defineCommand } from "citty";

package/dist/_chunks/remove.mjs

@@ -4,6 +4,7 @@ import { t as createCommandLogger } from "./logger.mjs";
 import "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { consola } from "consola";
 import { defineCommand } from "citty";
 const removeCommand = defineCommand({

package/dist/_chunks/shell.mjs

@@ -100,6 +100,7 @@ var ShellSession = class {
 				process.stdin.resume();
 				this.ws.send(serializeReady());
 				if (process.stdout.columns && process.stdout.rows) this.ws.send(serializeResize(process.stdout.columns, process.stdout.rows));
+				if (this.opts.initialCommand) this.ws.send(serializeData(Buffer.from(this.opts.initialCommand)));
 				process.stdin.on("data", onStdinData);
 				process.stdout.on("resize", onResize);
 			});

package/dist/_chunks/start.mjs

@@ -4,6 +4,7 @@ import { t as createCommandLogger } from "./logger.mjs";
 import "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { defineCommand } from "citty";
 const startCommand = defineCommand({
 	meta: {

package/dist/_chunks/stop.mjs

@@ -4,6 +4,7 @@ import { t as createCommandLogger } from "./logger.mjs";
 import "./vm-state.mjs";
 import { t as createVmsan } from "./context.mjs";
 import "./firecracker.mjs";
+import "./timeout-killer.mjs";
 import { consola } from "consola";
 import { defineCommand } from "citty";
 const stopCommand = defineCommand({

package/dist/_chunks/summary.mjs

@@ -1,6 +1,6 @@
 import { V as policyConflictError } from "./errors.mjs";
 import { s as parseDuration } from "./vm-state.mjs";
-import { f as assertSnapshotExists } from "./context.mjs";
+import { d as assertSnapshotExists } from "./context.mjs";
 import { c as parsePublishedPorts, d as validateCidr, f as validatePublishedPortsAvailable, i as parseDomains, l as parseRuntime, n as parseCidrList, o as parseMemoryMib, r as parseDiskSizeGb, s as parseNetworkPolicy, u as parseVcpuCount } from "./validation.mjs";
 function parseCreateInput(args, paths) {
 	const vcpus = parseVcpuCount(args.vcpus);

package/dist/_chunks/timeout-extender.mjs

@@ -0,0 +1,66 @@
+import { c as safeKill } from "./vm-state.mjs";
+import { t as spawnTimeoutKiller } from "./timeout-killer.mjs";
+import { join } from "node:path";
+const DEFAULT_INTERVAL_MS = 300 * 1e3;
+var TimeoutExtender = class {
+	_timer = null;
+	_previousKillerPid = null;
+	_vmId;
+	_store;
+	_paths;
+	_intervalMs;
+	_signal;
+	constructor(opts) {
+		this._vmId = opts.vmId;
+		this._store = opts.store;
+		this._paths = opts.paths;
+		this._intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+		this._signal = opts.signal;
+	}
+	start() {
+		if (this._timer) return;
+		if (this._signal) {
+			this._signal.addEventListener("abort", () => this.stop(), { once: true });
+			if (this._signal.aborted) {
+				this.stop();
+				return;
+			}
+		}
+		this._extendSafe();
+		this._timer = setInterval(() => this._extendSafe(), this._intervalMs);
+	}
+	stop() {
+		if (this._timer) {
+			clearInterval(this._timer);
+			this._timer = null;
+		}
+		if (this._previousKillerPid !== null) {
+			safeKill(this._previousKillerPid);
+			this._previousKillerPid = null;
+		}
+	}
+	_extendSafe() {
+		try {
+			this._extend();
+		} catch {
+			this.stop();
+		}
+	}
+	_extend() {
+		const state = this._store.load(this._vmId);
+		if (!state || state.status !== "running" || !state.timeoutMs) return;
+		const timeoutAt = new Date(Date.now() + state.timeoutMs).toISOString();
+		this._store.update(this._vmId, { timeoutAt });
+		if (this._previousKillerPid !== null) {
+			safeKill(this._previousKillerPid);
+			this._previousKillerPid = null;
+		}
+		if (state.pid) this._previousKillerPid = spawnTimeoutKiller({
+			vmId: this._vmId,
+			pid: state.pid,
+			timeoutMs: state.timeoutMs,
+			stateFile: join(this._paths.vmsDir, `${this._vmId}.json`)
+		}).pid ?? null;
+	}
+};
+export { TimeoutExtender as t };

package/dist/_chunks/timeout-killer.mjs

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+/**
+* Spawn a detached bash process that kills the VM after timeout.
+* The process sleeps for the timeout duration, then verifies the VM
+* is still running with the expected PID before sending SIGTERM.
+*/
+function spawnTimeoutKiller(opts) {
+	const { vmId, pid, timeoutMs, stateFile } = opts;
+	const timeoutSec = String(Math.ceil(timeoutMs / 1e3));
+	const killer = spawn("bash", [
+		"-c",
+		[
+			"sleep \"$1\"",
+			"STATE=$(cat -- \"$2\" 2>/dev/null) || exit 0",
+			"echo \"$STATE\" | grep -q '\"status\":\"running\"' || exit 0",
+			"echo \"$STATE\" | grep -q '\"pid\":'\"$3\" || exit 0",
+			"[ -d \"/proc/$3\" ] || exit 0",
+			"grep -aq -- \"$4\" \"/proc/$3/cmdline\" 2>/dev/null || exit 0",
+			"kill -- \"$3\" 2>/dev/null"
+		].join(" && "),
+		"bash",
+		timeoutSec,
+		stateFile,
+		String(pid),
+		vmId
+	], {
+		detached: true,
+		stdio: "ignore"
+	});
+	killer.unref();
+	return killer;
+}
+export { spawnTimeoutKiller as t };

package/dist/bin/cli.mjs

@@ -59,6 +59,7 @@ runMain(defineCommand({
 		connect: () => import("../_chunks/connect.mjs").then((m) => m.default),
 		upload: () => import("../_chunks/upload.mjs").then((m) => m.default),
 		download: () => import("../_chunks/download.mjs").then((m) => m.default),
+		exec: () => import("../_chunks/exec.mjs").then((m) => m.default),
 		network: () => import("../_chunks/network.mjs").then((m) => m.default)
 	}
 }));

package/dist/index.d.mts

@@ -2779,6 +2779,76 @@ declare class FirecrackerClient {
   static getVersion(baseDir: string): Promise<string | undefined>;
 }
 //#endregion
+//#region src/lib/command.d.ts
+interface LogEntry {
+  stream: "stdout" | "stderr";
+  data: string;
+}
+interface CommandInit {
+  agent: AgentClient;
+  cmdId: string;
+  startedAt: Date;
+  stream: AsyncIterable<RunEvent>;
+  signal?: AbortSignal;
+  onStdout?: (line: string) => void;
+  onStderr?: (line: string) => void;
+}
+declare class CommandFinished {
+  readonly cmdId: string;
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly output: string;
+  readonly timedOut: boolean;
+  readonly startedAt: Date;
+  constructor(opts: {
+    cmdId: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    output: string;
+    timedOut: boolean;
+    startedAt: Date;
+  });
+  get ok(): boolean;
+}
+declare class Command {
+  readonly cmdId: string;
+  private _startedAt;
+  private _exitCode;
+  private _timedOut;
+  private _logEntries;
+  private _logTruncated;
+  private _eventQueue;
+  private _completion;
+  private _stdoutPromise;
+  private _stderrPromise;
+  private _outputPromise;
+  private _agent;
+  constructor(init: CommandInit);
+  get startedAt(): Date;
+  get exitCode(): number | null;
+  logs(opts?: {
+    signal?: AbortSignal;
+  }): AsyncGenerator<LogEntry>;
+  stdout(opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  stderr(opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  output(stream?: "stdout" | "stderr" | "both", opts?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  wait(opts?: {
+    signal?: AbortSignal;
+  }): Promise<CommandFinished>;
+  kill(signal?: string, opts?: {
+    abortSignal?: AbortSignal;
+  }): Promise<void>;
+  private _withSignal;
+}
+//#endregion
 //#region src/services/agent.d.ts
 interface RunParams {
   cmd: string;
@@ -2808,6 +2878,11 @@ interface SessionInfo {
   createdAt: string;
   subscriberCount: number;
 }
+interface RunCommandParams extends RunParams {
+  signal?: AbortSignal;
+  onStdout?: (line: string) => void;
+  onStderr?: (line: string) => void;
+}
 declare class AgentClient {
   private baseUrl;
   private token;
@@ -2816,11 +2891,23 @@ declare class AgentClient {
     status: string;
     version: string;
   }>;
-  run(params: RunParams): AsyncGenerator<RunEvent>;
-  killCommand(cmdId: string, signal?: string): Promise<void>;
+  run(params: RunParams, signal?: AbortSignal): AsyncGenerator<RunEvent>;
+  killCommand(cmdId: string, signal?: string, abortSignal?: AbortSignal): Promise<void>;
   writeFiles(files: WriteFileEntry[], extractDir?: string): Promise<void>;
   listShellSessions(): Promise<SessionInfo[]>;
   killShellSession(sessionId: string): Promise<void>;
+  exec(params: RunParams, opts?: {
+    signal?: AbortSignal;
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+  }): Promise<Command>;
+  runCommand(cmd: string, args?: string[], opts?: {
+    signal?: AbortSignal;
+  }): Promise<CommandFinished>;
+  runCommand(params: RunCommandParams & {
+    detached: true;
+  }): Promise<Command>;
+  runCommand(params: RunCommandParams): Promise<CommandFinished>;
   readFile(path: string): Promise<Buffer | null>;
 }
 //#endregion
@@ -2843,6 +2930,7 @@ declare class TimeoutExtender {
   constructor(opts: TimeoutExtenderOptions);
   start(): void;
   stop(): void;
+  private _extendSafe;
   private _extend;
 }
 //#endregion
@@ -2954,6 +3042,7 @@ interface ShellSessionOptions {
   token: string;
   shell?: string;
   sessionId?: string;
+  initialCommand?: string;
 }
 interface ShellCloseInfo {
   /** true when the shell process exited (e.g. user typed `exit`) */

package/dist/index.mjs

@@ -2,73 +2,19 @@ import { n as vmsanPaths } from "./_chunks/paths.mjs";
 import { A as invalidDiskSizeRangeError, B as mutuallyExclusiveFlagsError, C as vmNotStoppedError, D as invalidCidrOctetError, E as invalidCidrFormatError, F as invalidImageRefTagError, H as portConflictError, I as invalidIntegerFlagError, L as invalidNetworkPolicyError, M as invalidDomainPatternError, N as invalidDurationError, O as invalidCidrPrefixError, P as invalidImageRefEmptyError, R as invalidPortError, S as vmNotRunningError, T as ValidationError, U as VmsanError, V as policyConflictError, _ as chrootNotFoundError, a as noKernelDirError, b as vmNoAgentTokenError, c as TimeoutError, d as socketTimeoutError, f as NetworkError, g as VmError, h as firecrackerApiError, i as noExt4RootfsError, j as invalidDomainError, k as invalidDiskSizeFormatError, l as agentTimeoutError, m as FirecrackerApiError, n as SetupError, o as noKernelError, p as defaultInterfaceNotFoundError, r as missingBinaryError, s as noRootfsDirError, t as handleCommandError, u as lockTimeoutError, v as networkSlotsExhaustedError, w as vmStateNotFoundError, x as vmNotFoundError, y as snapshotNotFoundError, z as invalidRuntimeError } from "./_chunks/errors.mjs";
 import { i as initVmsanLogger, n as createScopedLogger, r as getOutputMode, t as createCommandLogger } from "./_chunks/logger.mjs";
 import { a as isProcessAlive, c as safeKill, d as timeRemaining, f as toError, i as generateVmId, l as table, n as findFreeNetworkSlot, o as mkdirSecure, p as writeSecure, r as getActiveTapSlots, s as parseDuration, t as FileVmStateStore, u as timeAgo } from "./_chunks/vm-state.mjs";
-import { C as createDefaultLogger, S as NetworkManager, _ as validateEnvironment, a as ensureSeccompFilter, b as detectCgroupVersion, c as cleanupChroot, d as markVmAsError, g as getVmPid, h as getVmJailerPid, i as compileSeccompFilter, l as cleanupNetwork, m as findRootfs, n as VMService, o as resolveImageRootfs, p as findKernel, r as spawnTimeoutKiller, s as buildInitialVmState, t as createVmsan, u as killOrphanVmProcess, v as waitForSocket, w as createSilentLogger, x as FileLock, y as Jailer } from "./_chunks/context.mjs";
+import { C as createSilentLogger, S as createDefaultLogger, _ as waitForSocket, a as resolveImageRootfs, b as FileLock, c as cleanupNetwork, f as findKernel, g as validateEnvironment, h as getVmPid, i as ensureSeccompFilter, l as killOrphanVmProcess, m as getVmJailerPid, n as VMService, o as buildInitialVmState, p as findRootfs, r as compileSeccompFilter, s as cleanupChroot, t as createVmsan, u as markVmAsError, v as Jailer, x as NetworkManager, y as detectCgroupVersion } from "./_chunks/context.mjs";
 import { n as firecrackerFetch, t as FirecrackerClient } from "./_chunks/firecracker.mjs";
+import { t as spawnTimeoutKiller } from "./_chunks/timeout-killer.mjs";
 import { t as AgentClient } from "./_chunks/agent.mjs";
+import { t as TimeoutExtender } from "./_chunks/timeout-extender.mjs";
 import { n as waitForAgent, t as resolveVmState } from "./_chunks/vm-context.mjs";
 import { n as connectShell, t as ShellSession } from "./_chunks/shell.mjs";
 import { a as parseImageReference, c as parsePublishedPorts, d as validateCidr, f as validatePublishedPortsAvailable, i as parseDomains, l as parseRuntime, n as parseCidrList, o as parseMemoryMib, r as parseDiskSizeGb, s as parseNetworkPolicy, t as parseBandwidth, u as parseVcpuCount } from "./_chunks/validation.mjs";
 import { n as parseCreateInput, t as buildCreateSummaryLines } from "./_chunks/summary.mjs";
-import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 function definePlugin(plugin) {
 	return plugin;
 }
-const DEFAULT_INTERVAL_MS = 300 * 1e3;
-var TimeoutExtender = class {
-	_timer = null;
-	_previousKillerPid = null;
-	_vmId;
-	_store;
-	_paths;
-	_intervalMs;
-	_signal;
-	constructor(opts) {
-		this._vmId = opts.vmId;
-		this._store = opts.store;
-		this._paths = opts.paths;
-		this._intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
-		this._signal = opts.signal;
-	}
-	start() {
-		if (this._timer) return;
-		if (this._signal) {
-			this._signal.addEventListener("abort", () => this.stop(), { once: true });
-			if (this._signal.aborted) {
-				this.stop();
-				return;
-			}
-		}
-		this._extend();
-		this._timer = setInterval(() => this._extend(), this._intervalMs);
-	}
-	stop() {
-		if (this._timer) {
-			clearInterval(this._timer);
-			this._timer = null;
-		}
-		if (this._previousKillerPid !== null) {
-			safeKill(this._previousKillerPid);
-			this._previousKillerPid = null;
-		}
-	}
-	_extend() {
-		const state = this._store.load(this._vmId);
-		if (!state || state.status !== "running" || !state.timeoutMs) return;
-		const timeoutAt = new Date(Date.now() + state.timeoutMs).toISOString();
-		this._store.update(this._vmId, { timeoutAt });
-		if (this._previousKillerPid !== null) {
-			safeKill(this._previousKillerPid);
-			this._previousKillerPid = null;
-		}
-		if (state.pid) this._previousKillerPid = spawnTimeoutKiller({
-			vmId: this._vmId,
-			pid: state.pid,
-			timeoutMs: state.timeoutMs,
-			stateFile: join(this._paths.vmsDir, `${this._vmId}.json`)
-		}).pid ?? null;
-	}
-};
 var MemoryVmStateStore = class {
 	states = /* @__PURE__ */ new Map();
 	save(state) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vmsan",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "description": "Firecracker microVM sandbox toolkit",
   "homepage": "https://github.com/angelorc/vmsan",
   "bugs": "https://github.com/angelorc/vmsan/issues",