@namzu/sandbox 11.0.0 → 12.0.0

package/src/backends/firecracker/transport.ts

@@ -56,11 +56,18 @@
 import net from 'node:net'
 import tls from 'node:tls'
 
-import type { SandboxExecOptions, SandboxExecResult } from '@namzu/sdk'
+import type {
+	OpenTerminalOptions,
+	SandboxExecOptions,
+	SandboxExecResult,
+	SandboxTcpConnectOptions,
+	SandboxTcpConnection,
+	TerminalSession,
+} from '@namzu/sdk'
 import { OperationDeadline, OperationDeadlineExpired } from '../readiness.js'
 import {
+	REMOTE_EXECUTION_PROTOCOL_VERSION,
 	RemoteCancellationUnknownError,
-	RemoteCancellationUnsupportedError,
 	type RemoteExecutionAdapter,
 	RemoteExecutionController,
 	RemoteProtocolError,
@@ -70,6 +77,12 @@ import {
 	ExecResultAccumulator,
 	type ReadFileRequest,
 	type ReadFileResponse,
+	type TcpConnectRequest,
+	type TcpInputEvent,
+	type TcpOutputEvent,
+	type TerminalInputEvent,
+	type TerminalOpenRequest,
+	type TerminalOutputEvent,
 	type WriteFileRequest,
 	type WriteFileResponse,
 	parseExecLine,
@@ -170,6 +183,8 @@ export type AgentRequest =
 	  }
 	| { readonly op: 'read-file'; readonly body: ReadFileRequest }
 	| { readonly op: 'write-file'; readonly body: WriteFileRequest }
+	| { readonly op: 'terminal'; readonly body: TerminalOpenRequest }
+	| { readonly op: 'tcp-connect'; readonly body: TcpConnectRequest }
 	| { readonly op: 'healthz' }
 
 export interface VsockTransportOptions {
@@ -202,6 +217,9 @@ const EXECUTION_TRANSPORT_GRACE_MS = 10_000
 const POST_RESPONSE_CLOSE_TIMEOUT_MS = 1_000
 const MAX_TIMER_DELAY_MS = 2_147_483_647
 
+/** Exact guest wire version accepted by this Firecracker transport. */
+export const FIRECRACKER_AGENT_PROTOCOL_VERSION = REMOTE_EXECUTION_PROTOCOL_VERSION
+
 /** Framing: 8 hex digits of payload byte length, then `\n`, then payload. */
 const LENGTH_PREFIX_HEX = 8
 
@@ -724,8 +742,8 @@ export class VsockAgentTransport {
 			typeof response.error === 'string' &&
 			response.error.startsWith('unknown_op:')
 		) {
-			throw new RemoteCancellationUnsupportedError(
-				'This microVM agent does not support the execution-cancellation lease protocol. Rebuild the guest image before passing SandboxExecOptions.signal; refusing rather than pretending cancellation is active.',
+			throw new RemoteProtocolError(
+				`The microVM guest does not implement Firecracker agent protocol ${FIRECRACKER_AGENT_PROTOCOL_VERSION}. Rebuild the golden image from the same Namzu release before admitting commands.`,
 			)
 		}
 		if (response.ok === false && response.error === 'agent_retiring') {
@@ -740,13 +758,25 @@ export class VsockAgentTransport {
 		return await this.request<unknown>({ op: 'cancel-execution', body: { executionId } }, signal)
 	}
 
-	/** Liveness probe. Returns true on an `{ ok: true }` healthz reply. */
+	/** Readiness probe. A healthy guest must also speak the exact host protocol. */
 	async healthz(signal?: AbortSignal): Promise<boolean> {
 		try {
-			const res = await this.request<{ ok?: boolean }>({ op: 'healthz' }, signal)
-			return res.ok === true
-		} catch {
+			const res = await this.request<{ ok?: boolean; protocolVersion?: unknown }>(
+				{ op: 'healthz' },
+				signal,
+			)
+			if (res.ok !== true) return false
+			if (res.protocolVersion !== FIRECRACKER_AGENT_PROTOCOL_VERSION) {
+				const actual =
+					res.protocolVersion === undefined ? 'missing' : JSON.stringify(res.protocolVersion)
+				throw new RemoteProtocolError(
+					`Firecracker guest protocol version mismatch: expected ${FIRECRACKER_AGENT_PROTOCOL_VERSION}, received ${actual}. Rebuild the golden image from the same Namzu release.`,
+				)
+			}
+			return true
+		} catch (error) {
 			if (signal?.aborted) throw signal.reason
+			if (error instanceof RemoteProtocolError) throw error
 			return false
 		}
 	}
@@ -770,6 +800,7 @@ export class VsockAgentTransport {
 				lastErr = new Error('healthz returned not-ok')
 			} catch (err) {
 				lastErr = err
+				if (err instanceof RemoteProtocolError) throw err
 				if (err instanceof OperationDeadlineExpired) break
 			}
 			try {
@@ -806,6 +837,306 @@ export class VsockAgentTransport {
 		}
 		return Buffer.from(res.content, 'base64')
 	}
+
+	/**
+	 * Open a real PTY owned by the in-VM agent.
+	 *
+	 * Unlike `execute`, this keeps one framed connection open for the complete
+	 * interactive lifetime: guest output and exit events flow toward the host,
+	 * while input/resize/kill events flow back on the same ordered stream. The
+	 * browser never reaches this transport directly; the runtime gateway owns
+	 * the session and its authenticated WebSocket attachment.
+	 */
+	async openTerminal(options: OpenTerminalOptions): Promise<TerminalSession> {
+		const socket = await this.dial()
+		const request: TerminalOpenRequest = {
+			...(options.command !== undefined ? { command: options.command } : {}),
+			...(options.args !== undefined ? { args: options.args } : {}),
+			...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+			...(options.env !== undefined ? { env: { ...options.env } } : {}),
+			cols: options.size.cols,
+			rows: options.size.rows,
+		}
+
+		return await new Promise<TerminalSession>((resolve, reject) => {
+			const KILL_GRACE_MS = 5_000
+			const reader = new FrameReader()
+			const listeners = new Set<(chunk: string) => void>()
+			const buffered: string[] = []
+			let bufferedBytes = 0
+			let ready = false
+			let settled = false
+			let killTimer: ReturnType<typeof setTimeout> | undefined
+			let resolveExit!: (event: { exitCode: number; signal?: number }) => void
+			const exited = new Promise<{ exitCode: number; signal?: number }>((done) => {
+				resolveExit = done
+			})
+			const idle = new IdleTimer(this.readIdleTimeoutMs, () => {
+				finish(
+					new Error(
+						`vsock transport: terminal read idle timeout after ${this.readIdleTimeoutMs}ms`,
+					),
+				)
+			})
+
+			const finish = (
+				error: Error | null,
+				exit: { exitCode: number; signal?: number } = { exitCode: -1 },
+			) => {
+				if (settled) return
+				settled = true
+				idle.clear()
+				if (killTimer) clearTimeout(killTimer)
+				socket.destroy()
+				listeners.clear()
+				resolveExit(exit)
+				if (!ready) reject(error ?? new Error('terminal exited before readiness'))
+			}
+
+			const send = (event: TerminalInputEvent) => {
+				if (settled) return
+				socket.write(frame(JSON.stringify(event)))
+			}
+
+			const session: TerminalSession = {
+				write(data) {
+					send({ type: 'input', data })
+				},
+				resize(size) {
+					send({ type: 'resize', cols: size.cols, rows: size.rows })
+				},
+				onData(listener) {
+					listeners.add(listener)
+					if (buffered.length > 0) {
+						const pending = buffered.splice(0)
+						bufferedBytes = 0
+						queueMicrotask(() => {
+							if (!listeners.has(listener)) return
+							for (const chunk of pending) listener(chunk)
+						})
+					}
+					return () => listeners.delete(listener)
+				},
+				exited,
+				kill(signal) {
+					send({ type: 'kill', ...(signal !== undefined ? { signal } : {}) })
+					// A wedged guest must not pin sandbox.destroy() forever. The normal
+					// path reports the real exit; the deadline only severs an
+					// unresponsive transport so the owning microVM can be reclaimed.
+					if (!settled && !killTimer) {
+						killTimer = setTimeout(() => finish(null), KILL_GRACE_MS)
+						killTimer.unref?.()
+					}
+				},
+			}
+
+			socket.on('data', (chunk: Buffer) => {
+				if (!ready) idle.bump()
+				let payloads: string[]
+				try {
+					payloads = reader.push(chunk)
+				} catch (err) {
+					finish(err instanceof Error ? err : new Error(String(err)))
+					return
+				}
+				for (const payload of payloads) {
+					let event: TerminalOutputEvent
+					try {
+						event = JSON.parse(payload) as TerminalOutputEvent
+					} catch (err) {
+						finish(err instanceof Error ? err : new Error(String(err)))
+						return
+					}
+					if (event.type === 'ready') {
+						if (!ready) {
+							ready = true
+							// Once ready, an interactive shell may legitimately sit silent
+							// for hours. Runtime/session TTL owns idle cleanup; a transport
+							// read timer would incorrectly kill a healthy quiet terminal.
+							idle.clear()
+							resolve(session)
+						}
+						continue
+					}
+					if (event.type === 'data') {
+						if (listeners.size === 0) {
+							buffered.push(event.data)
+							bufferedBytes += Buffer.byteLength(event.data)
+							while (bufferedBytes > 1024 * 1024 && buffered.length > 1) {
+								bufferedBytes -= Buffer.byteLength(buffered.shift() ?? '')
+							}
+						} else {
+							for (const listener of listeners) listener(event.data)
+						}
+						continue
+					}
+					if (event.type === 'exit') {
+						finish(null, {
+							exitCode: event.exitCode,
+							...(event.signal !== undefined ? { signal: event.signal } : {}),
+						})
+						return
+					}
+					finish(new Error(event.error))
+					return
+				}
+			})
+			socket.once('error', (err) => finish(err))
+			socket.once('close', () =>
+				finish(new Error('vsock transport: terminal socket closed before exit')),
+			)
+			idle.bump()
+			socket.write(
+				frame(
+					JSON.stringify({
+						op: 'terminal',
+						body: request,
+					} satisfies AgentRequest),
+				),
+			)
+		})
+	}
+
+	/** Open one TCP stream to a service listening on guest loopback. */
+	async openTcpConnection(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection> {
+		if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65_535) {
+			throw new Error('tcp connection port must be an integer in [1, 65535]')
+		}
+		const host = options.host ?? '127.0.0.1'
+		if (host !== '127.0.0.1' && host !== '::1') {
+			throw new Error('firecracker TCP connections are restricted to guest loopback')
+		}
+		const socket = await this.dial()
+		const request: TcpConnectRequest = { host, port: options.port }
+
+		return await new Promise<SandboxTcpConnection>((resolve, reject) => {
+			const reader = new FrameReader()
+			const listeners = new Set<(chunk: Uint8Array) => void>()
+			const buffered: Buffer[] = []
+			let bufferedBytes = 0
+			let ready = false
+			let settled = false
+			let resolveClosed!: () => void
+			const closed = new Promise<void>((done) => {
+				resolveClosed = done
+			})
+			const idle = new IdleTimer(this.readIdleTimeoutMs, () => {
+				finish(
+					new Error(`vsock transport: TCP connect idle timeout after ${this.readIdleTimeoutMs}ms`),
+				)
+			})
+
+			const finish = (error: Error | null) => {
+				if (settled) return
+				settled = true
+				idle.clear()
+				socket.destroy()
+				listeners.clear()
+				resolveClosed()
+				if (!ready) reject(error ?? new Error('TCP stream closed before readiness'))
+			}
+
+			const send = (event: TcpInputEvent): boolean => {
+				return !settled && socket.write(frame(JSON.stringify(event)))
+			}
+
+			const connection: SandboxTcpConnection = {
+				write(data) {
+					const bytes = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data)
+					return send({ type: 'data', data: bytes.toString('base64') })
+				},
+				end() {
+					send({ type: 'end' })
+				},
+				destroy() {
+					send({ type: 'destroy' })
+					finish(null)
+				},
+				pause() {
+					socket.pause()
+				},
+				resume() {
+					if (!settled) socket.resume()
+				},
+				onData(listener) {
+					listeners.add(listener)
+					if (buffered.length > 0) {
+						const pending = buffered.splice(0)
+						bufferedBytes = 0
+						queueMicrotask(() => {
+							if (!listeners.has(listener)) return
+							for (const chunk of pending) listener(chunk)
+						})
+					}
+					return () => listeners.delete(listener)
+				},
+				onDrain(listener) {
+					socket.on('drain', listener)
+					return () => socket.off('drain', listener)
+				},
+				closed,
+			}
+
+			socket.on('data', (chunk: Buffer) => {
+				if (!ready) idle.bump()
+				let payloads: string[]
+				try {
+					payloads = reader.push(chunk)
+				} catch (error) {
+					finish(error instanceof Error ? error : new Error(String(error)))
+					return
+				}
+				for (const payload of payloads) {
+					let event: TcpOutputEvent
+					try {
+						event = JSON.parse(payload) as TcpOutputEvent
+					} catch (error) {
+						finish(error instanceof Error ? error : new Error(String(error)))
+						return
+					}
+					if (event.type === 'ready') {
+						if (!ready) {
+							ready = true
+							idle.clear()
+							resolve(connection)
+						}
+						continue
+					}
+					if (event.type === 'data') {
+						const bytes = Buffer.from(event.data, 'base64')
+						if (listeners.size === 0) {
+							buffered.push(bytes)
+							bufferedBytes += bytes.byteLength
+							while (bufferedBytes > 1024 * 1024 && buffered.length > 1) {
+								bufferedBytes -= buffered.shift()?.byteLength ?? 0
+							}
+						} else {
+							for (const listener of listeners) listener(bytes)
+						}
+						continue
+					}
+					if (event.type === 'end') {
+						finish(null)
+						continue
+					}
+					finish(new Error(event.error))
+				}
+			})
+			socket.once('error', (error) => finish(error))
+			socket.once('close', () =>
+				finish(ready ? null : new Error('vsock TCP socket closed before readiness')),
+			)
+			idle.bump()
+			socket.write(
+				frame(
+					JSON.stringify({
+						op: 'tcp-connect',
+						body: request,
+					} satisfies AgentRequest),
+				),
+			)
+		})
+	}
 }
 
 // ---------------------------------------------------------------------------

package/src/backends/http-worker-client.ts

@@ -1,7 +1,6 @@
 import { type SandboxExecOptions, type SandboxExecResult, withHint } from '@namzu/sdk'
 
 import {
-	RemoteCancellationUnsupportedError,
 	RemoteCommandError,
 	type RemoteExecutionAdapter,
 	RemoteExecutionController,
@@ -162,8 +161,8 @@ async function readExecution(
 }
 
 /**
- * A per-sandbox HTTP worker client. The controller caches protocol support for
- * that worker and gives every v2 command an identity before it can be admitted.
+ * A per-sandbox HTTP worker client. Every command must reserve an identity
+ * through the exact worker protocol before it can be admitted.
  */
 export class HttpWorkerClient {
 	private readonly controller: RemoteExecutionController
@@ -177,8 +176,8 @@ export class HttpWorkerClient {
 					signal,
 				})
 				if (response.status === 404) {
-					throw new RemoteCancellationUnsupportedError(
-						'This sandbox worker does not support the execution-cancellation lease protocol. Rebuild the worker image or standby-pool profile before passing SandboxExecOptions.signal; refusing rather than pretending cancellation is active.',
+					throw new RemoteProtocolError(
+						'The sandbox worker does not implement the required execution protocol. Rebuild the worker image or standby-pool profile from the same Namzu release before admitting commands.',
 					)
 				}
 				if (!response.ok) {
@@ -215,11 +214,7 @@ export class HttpWorkerClient {
 	}
 }
 
-/**
- * Compatibility entry point for focused consumers. Sandbox backends keep one
- * {@link HttpWorkerClient} per remote sandbox so capability state is not shared
- * across peers and is not re-probed for every command.
- */
+/** Convenience entry point for focused consumers. */
 export async function execViaHttpWorker(
 	baseUrl: string,
 	command: string,

package/src/backends/readiness.ts

@@ -7,6 +7,11 @@
  * transports can release their sockets too.
  */
 
+import {
+	REMOTE_EXECUTION_PROTOCOL_VERSION,
+	RemoteProtocolError,
+} from './remote-execution-controller.js'
+
 const MAX_NODE_TIMER_MS = 2_147_483_647
 
 /**
@@ -142,15 +147,42 @@ export async function probeHttpHealth(
 ): Promise<{ readonly ok: boolean; readonly status: number }> {
 	signal.throwIfAborted()
 	const response = await fetch(url, { signal })
-	const result = { ok: response.ok, status: response.status }
+	if (!response.ok) {
+		try {
+			await response.body?.cancel()
+		} catch {
+			// The status is already known. A body cancellation failure must not
+			// hide it; the owning deadline still aborts the transport if needed.
+		}
+		signal.throwIfAborted()
+		return { ok: false, status: response.status }
+	}
+
+	let payload: unknown
 	try {
-		await response.body?.cancel()
-	} catch {
-		// The status is already known. A body cancellation failure must not
-		// hide it; the owning deadline still aborts the transport if needed.
+		payload = await response.json()
+	} catch (error) {
+		throw new RemoteProtocolError(
+			`Sandbox worker health response is not valid JSON for protocol ${REMOTE_EXECUTION_PROTOCOL_VERSION}: ${error instanceof Error ? error.message : String(error)}`,
+		)
 	}
 	signal.throwIfAborted()
-	return result
+	const health = payload as { ok?: unknown; protocolVersion?: unknown }
+	if (
+		!health ||
+		typeof health !== 'object' ||
+		health.ok !== true ||
+		health.protocolVersion !== REMOTE_EXECUTION_PROTOCOL_VERSION
+	) {
+		const actual =
+			health && typeof health === 'object' && health.protocolVersion !== undefined
+				? JSON.stringify(health.protocolVersion)
+				: 'missing'
+		throw new RemoteProtocolError(
+			`Sandbox worker protocol version mismatch: expected ${REMOTE_EXECUTION_PROTOCOL_VERSION}, received ${actual}. Rebuild the worker image from the same Namzu release.`,
+		)
+	}
+	return { ok: true, status: response.status }
 }
 
 /**

package/src/backends/remote-execution-controller.ts

@@ -9,9 +9,12 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647
 const EXECUTION_ID_PATTERN =
 	/^exec_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 
+/** Exact wire version implemented by the shipped worker and microVM guest. */
+export const REMOTE_EXECUTION_PROTOCOL_VERSION = 2 as const
+
 export interface RemoteReservation {
 	readonly ok: true
-	readonly protocolVersion: 2
+	readonly protocolVersion: typeof REMOTE_EXECUTION_PROTOCOL_VERSION
 	readonly executionId: string
 	readonly leaseExpiresAt: number
 }
@@ -37,8 +40,6 @@ export class RemoteCommandError extends Error {}
 
 export class RemoteProtocolError extends Error {}
 
-export class RemoteCancellationUnsupportedError extends Error {}
-
 export interface SandboxRetirementObservation {
 	readonly accepted: boolean
 	readonly error?: Error
@@ -106,7 +107,7 @@ function parseReservation(value: unknown): RemoteReservation {
 	const reservation = value as Record<string, unknown>
 	if (
 		reservation.ok !== true ||
-		reservation.protocolVersion !== 2 ||
+		reservation.protocolVersion !== REMOTE_EXECUTION_PROTOCOL_VERSION ||
 		!EXECUTION_ID_PATTERN.test(String(reservation.executionId ?? '')) ||
 		!Number.isFinite(reservation.leaseExpiresAt)
 	) {
@@ -223,17 +224,13 @@ async function bounded<T>(
 	}
 }
 
-type Capability = 'unknown' | 'supported' | 'unsupported'
-
 /**
- * One state machine for remote command ownership. A v2 peer reserves every
- * command, even when the caller supplied no signal, so transport loss can be
- * reconciled by identity. Legacy execution is entered only after an explicit
- * unsupported response from the peer and is fenced as unknown on any failure.
+ * One state machine for remote command ownership. Every supported peer reserves
+ * every command before admission, even when the caller supplied no signal, so
+ * transport loss can be reconciled by identity. An old peer is refused; an
+ * identity-less remote command is never started.
  */
 export class RemoteExecutionController<Context = undefined> {
-	private capability: Capability = 'unknown'
-	private unsupportedError: RemoteCancellationUnsupportedError | undefined
 	private readonly controlRequestTimeoutMs: number
 	private readonly cancelConfirmTimeoutMs: number
 	private readonly resultDrainTimeoutMs: number
@@ -261,17 +258,6 @@ export class RemoteExecutionController<Context = undefined> {
 	): Promise<SandboxExecResult> {
 		const startedAt = Date.now()
 		if (opts?.signal?.aborted) return cancelledBeforeStart(startedAt)
-		if (this.capability === 'unsupported') {
-			if (opts?.signal) {
-				throw (
-					this.unsupportedError ??
-					new RemoteCancellationUnsupportedError(
-						`${this.adapter.label} was classified as cancellation-unsupported`,
-					)
-				)
-			}
-			return await this.executeLegacy(command, argv, opts, context)
-		}
 
 		let reservation: RemoteReservation
 		try {
@@ -283,46 +269,14 @@ export class RemoteExecutionController<Context = undefined> {
 					opts?.signal,
 				),
 			)
-			this.capability = 'supported'
 		} catch (error) {
 			if (opts?.signal?.aborted) return cancelledBeforeStart(startedAt)
-			if (error instanceof RemoteCancellationUnsupportedError) {
-				this.capability = 'unsupported'
-				this.unsupportedError = error
-				if (opts?.signal) throw error
-				return await this.executeLegacy(command, argv, opts, context)
-			}
 			throw error
 		}
 
 		return await this.executeReserved(reservation, command, argv, opts, startedAt, context)
 	}
 
-	private async executeLegacy(
-		command: string,
-		argv: string[] | undefined,
-		opts: SandboxExecOptions | undefined,
-		context: Context | undefined,
-	): Promise<SandboxExecResult> {
-		const timeoutMs = observationDeadlineMs(
-			opts?.timeout,
-			this.defaultExecutionTimeoutMs,
-			this.executionObservationGraceMs,
-		)
-		try {
-			return await bounded(
-				`${this.adapter.label} legacy execution observation`,
-				timeoutMs,
-				(signal) => this.adapter.execute(undefined, command, argv, opts, signal, context),
-			)
-		} catch (error) {
-			throw new RemoteCancellationUnknownError(
-				`The legacy ${this.adapter.label} execution failed after admission without an execution id: ${error instanceof Error ? error.message : String(error)}. The remote outcome is unknown and the sandbox must not be reused.`,
-				{ cause: error },
-			)
-		}
-	}
-
 	private async requestCancellation(
 		executionId: string,
 	): Promise<RemoteCancellationAcknowledgement> {

package/src/index.ts

@@ -78,6 +78,7 @@ export type {
 	OrchestratorTokenProvider,
 } from './backends/firecracker/index.js'
 export {
+	FIRECRACKER_AGENT_PROTOCOL_VERSION,
 	type SandboxAgentHandle,
 	type VsockTransportOptions,
 	VsockAgentTransport,