@namzu/sandbox 13.0.0 → 14.0.0

package/src/backends/kubernetes/sandbox.ts

@@ -0,0 +1,395 @@
+/**
+ * The {@link Sandbox} a kubernetes acquire hands back: the SDK contract,
+ * served over the guest agent's TCP transport, with the lease that keeps the
+ * cluster from deleting the pod out from under a long run.
+ *
+ * Split out of `index.ts` because that file is about the CONTROL plane —
+ * claim, poll, address, release — and this one is about the DATA plane, and
+ * the two are read for different reasons.
+ *
+ * ## What it implements, and what it deliberately does not
+ *
+ * Implemented: `exec` (through the shared {@link RemoteExecutionController},
+ * so an `AbortSignal` terminates the guest process rather than abandoning
+ * the wait), `writeFile`, `readFile`, `listFiles`, `openTerminal`,
+ * `openTcpConnection`, `destroy`.
+ *
+ * Absent on purpose, because the SDK's contract says a backend that cannot
+ * honour an optional method must omit it rather than accept and ignore:
+ *
+ *  - `setNetworkPolicy` — egress here is a `NetworkPolicy` attached to the
+ *    pool's `SandboxTemplate`. There is no per-running-pod knob to turn, and
+ *    a policy accepted and not applied is worse than one never offered: the
+ *    caller stops looking.
+ *  - `spawnDetached` — the guest agent has no op that starts a process and
+ *    returns it running. A host asking for background jobs must be told no.
+ *  - `walkFiles` — not in this batch. A host that requires bounded search
+ *    refuses an absent method, which is the honest answer today.
+ *
+ * ## Terminals are owned
+ *
+ * `openTerminal` is only a compliant implementation if `destroy()` kills and
+ * awaits every terminal it returned, so open terminals are tracked and
+ * reaped before the object is released — the same thing the Firecracker
+ * backend does, for the same contract.
+ *
+ * ## Two terminal states, one `SandboxStatus`
+ *
+ * `SandboxStatus` has exactly four members and this change does not widen
+ * the SDK's union, so both ways a sandbox ends report `'destroyed'`. They
+ * are told apart by the error a later call throws:
+ * {@link KubernetesSandboxDestroyedError} (this host released it) and
+ * {@link KubernetesSandboxGoneError} (the cluster deleted it — the lease
+ * renewal found the object already gone).
+ */
+
+import type {
+	OpenTerminalOptions,
+	Sandbox,
+	SandboxDestroyOptions,
+	SandboxEnvironment,
+	SandboxExecOptions,
+	SandboxExecResult,
+	SandboxFileEntry,
+	SandboxId,
+	SandboxStatus,
+	SandboxTcpConnectOptions,
+	SandboxTcpConnection,
+	TerminalSession,
+} from '@namzu/sdk'
+
+import { OperationDeadline } from '../readiness.js'
+import {
+	RemoteCancellationUnknownError,
+	type SandboxRetirementObservation,
+} from '../remote-execution-controller.js'
+import { KubernetesLeaseRenewal } from './lease.js'
+import type { KubernetesAgentTransport } from './transport.js'
+
+/**
+ * How long a retirement triggered by an unconfirmed cancellation may spend
+ * deleting the object. Separate from every other clock on the path: the
+ * caller's own deadline has usually already expired by the time this runs,
+ * and reusing it would mean skipping teardown exactly when a command of
+ * unknown state is still out there.
+ */
+const RETIREMENT_TIMEOUT_MS = 15_000
+
+/** Thrown by any operation on a sandbox this host already destroyed. */
+export class KubernetesSandboxDestroyedError extends Error {
+	override readonly name = 'KubernetesSandboxDestroyedError'
+
+	constructor(
+		readonly operation: string,
+		readonly sandboxName: string,
+	) {
+		super(
+			`kubernetes sandbox ${sandboxName} has been destroyed; ${operation}() cannot be admitted. Acquire a new sandbox — a destroyed one's pod, Service and claim are deleted and its agent address no longer resolves.`,
+		)
+	}
+}
+
+/**
+ * Thrown by any operation on a sandbox the CLUSTER removed while this
+ * handle still held it — the lease renewal PATCH came back 404/410. Distinct
+ * from {@link KubernetesSandboxDestroyedError} because nothing this host did
+ * caused it: the object expired, an operator deleted it, or the controller
+ * reaped it, and the actionable advice is different.
+ */
+export class KubernetesSandboxGoneError extends Error {
+	override readonly name = 'KubernetesSandboxGoneError'
+
+	constructor(
+		readonly operation: string,
+		readonly sandboxName: string,
+	) {
+		super(
+			`kubernetes sandbox ${sandboxName} no longer exists on the cluster; ${operation}() cannot be admitted. Its lease renewal found the object already deleted — it expired (spec.lifecycle.shutdownTime), an operator deleted it, or the controller reaped it. Nothing this handle can do brings it back; acquire a new sandbox.`,
+		)
+	}
+}
+
+interface KubernetesSandboxBaseOptions {
+	/** The cluster's own name for the bound sandbox — also the sandbox id. */
+	readonly name: string
+	readonly rootDir: string
+	readonly transport: KubernetesAgentTransport
+	/** DELETE the object this backend created. Already-gone counts as done. */
+	readonly release: (signal?: AbortSignal) => Promise<void>
+}
+
+/**
+ * The lease half of the options: a way to move the expiry, and the expiry it
+ * is moving. Required TOGETHER, because `renew` without `ttlSeconds` is a
+ * renewal loop with nothing to stamp — it would re-stamp `now + 0`, an
+ * expiry already in the past, and hand the object straight to the
+ * controller's reaper while reporting every tick a success. A pair is the
+ * only shape that cannot be half-configured.
+ */
+interface KubernetesSandboxLeaseOptions {
+	/** PATCH the object's `shutdownTime` forward. See `lease.ts`. */
+	readonly renew: (shutdownTime: string, signal?: AbortSignal) => Promise<void>
+	/** The TTL acquire stamped; each renewal re-stamps exactly this much. */
+	readonly ttlSeconds: number
+	readonly onRenewalError?: (error: unknown) => void
+	/** Test seam: the renewal loop's base interval. Default: half the TTL. */
+	readonly leaseIntervalMs?: number
+}
+
+/**
+ * The other arm: an object that carries no expiry, so this handle runs no
+ * renewal loop at all — the persistent workspace (`workspace.ts`), which is
+ * explicitly managed and must outlive a host that stopped renewing. A no-op
+ * `renew` would be the wrong way to say that: it would leave a timer ticking
+ * forever to do nothing. The lease fields are typed `undefined` rather than
+ * omitted so that passing one of them here is a type error and not an
+ * excess-property check a spread would slip past.
+ */
+interface KubernetesSandboxUnleasedOptions {
+	readonly renew?: undefined
+	readonly ttlSeconds?: undefined
+	readonly onRenewalError?: undefined
+	readonly leaseIntervalMs?: undefined
+}
+
+export type KubernetesSandboxOptions = KubernetesSandboxBaseOptions &
+	(KubernetesSandboxLeaseOptions | KubernetesSandboxUnleasedOptions)
+
+function detectEnvironment(): SandboxEnvironment {
+	// The guest runs Linux; the enum describes the host-facing shape of the
+	// worker, not the isolation technology under it. Firecracker's guest
+	// reports the same for the same reason.
+	return 'linux-namespace'
+}
+
+/**
+ * What this backend hands back: the SDK contract, with the two optional
+ * members it DOES implement narrowed to present, so a caller that composes
+ * one — `workspace.ts` wraps this handle — does not have to re-check for a
+ * method this file always defines.
+ */
+export type KubernetesSandboxHandle = Sandbox &
+	Required<Pick<Sandbox, 'openTerminal' | 'openTcpConnection'>>
+
+/**
+ * Build the handle. It does NOT run the acquire-time privilege probe — that
+ * is `create()`'s job in `index.ts`, so that a refusal can destroy this
+ * object before any caller has a reference to it, and so this function stays
+ * usable by the workspace path that runs its own probe.
+ */
+export function buildKubernetesSandbox(options: KubernetesSandboxOptions): KubernetesSandboxHandle {
+	// The cluster owns this name. Preserving it verbatim as the sandbox id —
+	// as the Firecracker backend preserves its orchestrator's — means a log
+	// line carrying an id is also a `kubectl get sandbox` argument.
+	const id = options.name as SandboxId
+	const transport = options.transport
+
+	type Lifecycle = 'active' | 'retiring' | 'destroyed' | 'gone'
+	let lifecycle: Lifecycle = 'active'
+	let activeExecutions = 0
+	let teardownPromise: Promise<void> | undefined
+	let teardownComplete = false
+	let retirementPromise: Promise<SandboxRetirementObservation> | undefined
+	const terminals = new Set<TerminalSession>()
+
+	// No `renew` ⇒ no expiry to move ⇒ no loop. `stop()` on the undefined
+	// case is the caller's problem to not have, which is why every use below
+	// goes through `lease?.stop()`.
+	const renew = options.renew
+	const ttlSeconds = options.ttlSeconds
+	// The type above already pairs the two. This is the runtime half of the
+	// same rule, for a caller that reached here through a cast or from
+	// JavaScript: a lease stamping `now + 0` expires the moment it is written,
+	// and every tick would report success while the controller deleted the
+	// object underneath it.
+	if (renew !== undefined && (typeof ttlSeconds !== 'number' || ttlSeconds <= 0)) {
+		throw new Error(
+			`kubernetes: sandbox ${options.name} was given a lease renewal with ttlSeconds ${String(ttlSeconds)}. A renewal re-stamps shutdownTime as now + ttlSeconds, so a zero or absent TTL stamps an expiry that has already passed and the object is reaped while the loop reports every tick a success. Pass renew and a positive ttlSeconds together, or neither — an object with no expiry (a persistent workspace) runs no renewal loop.`,
+		)
+	}
+	// `ttlSeconds === undefined` is unreachable once `renew` is defined — the
+	// throw above saw to that — and is written out anyway because it is what
+	// narrows the field to a number for the constructor below.
+	const lease =
+		renew === undefined || ttlSeconds === undefined
+			? undefined
+			: new KubernetesLeaseRenewal({
+					ttlSeconds,
+					renew,
+					onGone: () => {
+						// The object is gone; the pod behind the address went with it.
+						// Refuse every later call by name rather than let it dial into a
+						// connect timeout with nothing to explain it.
+						if (lifecycle === 'active') lifecycle = 'gone'
+					},
+					...(options.onRenewalError !== undefined
+						? { onRenewalError: options.onRenewalError }
+						: {}),
+					...(options.leaseIntervalMs !== undefined ? { intervalMs: options.leaseIntervalMs } : {}),
+				})
+	lease?.start()
+
+	const assertAdmissible = (operation: string): void => {
+		if (lifecycle === 'active') return
+		if (lifecycle === 'gone') throw new KubernetesSandboxGoneError(operation, options.name)
+		throw new KubernetesSandboxDestroyedError(operation, options.name)
+	}
+
+	const teardown = (signal?: AbortSignal): Promise<void> => {
+		if (lifecycle === 'active') lifecycle = 'retiring'
+		lease?.stop()
+		if (teardownComplete) return Promise.resolve()
+		if (teardownPromise) return teardownPromise
+		const shared = options.release(signal).then(
+			() => {
+				teardownComplete = true
+				lifecycle = 'destroyed'
+			},
+			(error: unknown) => {
+				// A failed teardown must stay retryable; keeping the rejected
+				// promise would answer every later destroy() with the same
+				// stale failure.
+				if (teardownPromise === shared) teardownPromise = undefined
+				throw error
+			},
+		)
+		teardownPromise = shared
+		return shared
+	}
+
+	/**
+	 * A command whose cancellation the guest could not confirm may still be
+	 * running in that pod, so the pod stops being reusable. Retire it and
+	 * report whether the retirement landed, on the error the caller is about
+	 * to receive.
+	 */
+	const retire = (): Promise<SandboxRetirementObservation> => {
+		if (lifecycle === 'active') lifecycle = 'retiring'
+		retirementPromise ??= new OperationDeadline(
+			RETIREMENT_TIMEOUT_MS,
+			`kubernetes sandbox ${options.name} retirement`,
+		)
+			.run(async (signal) => await teardown(signal))
+			.then(() => ({ accepted: true as const }))
+			.catch((error: unknown) => ({
+				accepted: false as const,
+				error: error instanceof Error ? error : new Error(String(error)),
+			}))
+		return retirementPromise
+	}
+
+	const runExecution = async <T>(operation: string, run: () => Promise<T>): Promise<T> => {
+		assertAdmissible(operation)
+		activeExecutions += 1
+		try {
+			return await run()
+		} catch (error) {
+			if (error instanceof RemoteCancellationUnknownError) {
+				error.retirement = await retire()
+			}
+			throw error
+		} finally {
+			activeExecutions = Math.max(0, activeExecutions - 1)
+		}
+	}
+
+	return {
+		id,
+		get status(): SandboxStatus {
+			// Four members, and no new one: a cluster-side disappearance and a
+			// host-side destroy both read as 'destroyed' here and are told
+			// apart by the error a later call throws.
+			if (lifecycle !== 'active') return 'destroyed'
+			return activeExecutions > 0 ? 'busy' : 'ready'
+		},
+		rootDir: options.rootDir,
+		environment: detectEnvironment(),
+
+		async exec(
+			command: string,
+			argv?: string[],
+			opts?: SandboxExecOptions,
+		): Promise<SandboxExecResult> {
+			return await runExecution('exec', async () => await transport.exec(command, argv, opts))
+		},
+
+		/**
+		 * Every `tcp` request dials a fresh connection, so its envelope is
+		 * also that connection's first, not-yet-authenticated frame and is
+		 * bounded by the guest's pre-auth frame ceiling (8 MiB by default).
+		 * The transport checks that BEFORE dialing and throws
+		 * `AgentPreauthFrameTooLargeError` naming the limit; it is passed
+		 * through unwrapped so a caller can catch that class and chunk,
+		 * rather than having to pattern-match a message.
+		 */
+		async writeFile(path: string, content: string | Buffer): Promise<void> {
+			assertAdmissible('writeFile')
+			const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8')
+			await transport.writeFile(path, buf)
+		},
+
+		async readFile(path: string): Promise<Buffer> {
+			assertAdmissible('readFile')
+			return await transport.readFile(path)
+		},
+
+		async openTerminal(terminalOptions: OpenTerminalOptions): Promise<TerminalSession> {
+			assertAdmissible('openTerminal')
+			const terminal = await transport.openTerminal(terminalOptions)
+			terminals.add(terminal)
+			void terminal.exited.finally(() => terminals.delete(terminal))
+			return terminal
+		},
+
+		async openTcpConnection(
+			connectOptions: SandboxTcpConnectOptions,
+		): Promise<SandboxTcpConnection> {
+			assertAdmissible('openTcpConnection')
+			return await transport.openTcpConnection(connectOptions)
+		},
+
+		async listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]> {
+			return await runExecution('listFiles', async () => {
+				// Same wire as docker/aci/firecracker: `find -printf '%p\t%s\n'`,
+				// parsed line by line, with a non-zero exit (a root that does
+				// not exist yet) mapped to "empty" as the SDK contract asks.
+				const result = await transport.exec('find', [rootPath, '-type', 'f', '-printf', '%p\t%s\n'])
+				if (result.exitCode !== 0) return []
+				const entries: SandboxFileEntry[] = []
+				for (const rawLine of result.stdout.split('\n')) {
+					if (!rawLine) continue
+					const tab = rawLine.indexOf('\t')
+					if (tab < 0) continue
+					const filePath = rawLine.slice(0, tab)
+					const size = Number.parseInt(rawLine.slice(tab + 1), 10)
+					if (!filePath || !Number.isFinite(size)) continue
+					entries.push({ path: filePath, size })
+				}
+				return entries
+			})
+		},
+
+		async destroy(destroyOptions?: SandboxDestroyOptions): Promise<void> {
+			if (retirementPromise) {
+				const observation = await retirementPromise
+				if (observation.accepted) return
+				retirementPromise = undefined
+			}
+			// A terminal owns an interactive process tree in this pod. Stop and
+			// await every one before releasing the object, so the SDK's
+			// ownership contract is real rather than best-effort bookkeeping.
+			lifecycle = lifecycle === 'active' ? 'retiring' : lifecycle
+			lease?.stop()
+			const activeTerminals = [...terminals]
+			for (const terminal of activeTerminals) terminal.kill('SIGKILL')
+			await Promise.allSettled(activeTerminals.map((terminal) => terminal.exited))
+			terminals.clear()
+			// Deleting the claim cascades to the sandbox it adopted through the
+			// ownerReferences the controller re-parents on bind, so one DELETE
+			// retires the pod, the Service and the object. An object that is
+			// already gone counts as released — that is the state DELETE was
+			// asking for.
+			await teardown(destroyOptions?.signal)
+		},
+	}
+}

package/src/backends/kubernetes/transport.ts

@@ -0,0 +1,286 @@
+/**
+ * Host-side transport for the kubernetes backend's guest agent: the same
+ * `agent/agent.cjs` the Firecracker tier bakes into its golden image,
+ * reached over the pod network instead of a host-local vsock/unix socket.
+ *
+ * Every byte on the wire goes through {@link VsockAgentTransport}
+ * constructed with a `{ kind: 'tcp' }` handle (`../firecracker/transport.js`):
+ * the SAME per-call dial (fresh connection, no cached socket, no cached
+ * IP — a Service-FQDN host re-resolves on every call, so a resumed pod's
+ * new address costs nothing extra), the SAME 8-hex-length framing, and
+ * the SAME token-in-envelope credential. Nothing about the wire is
+ * reimplemented here.
+ *
+ * This module supplies its OWN {@link RemoteExecutionAdapter} to the
+ * shared {@link RemoteExecutionController} — a third adapter against the
+ * same controller, alongside `http-worker-client.ts` and
+ * `firecracker/transport.ts`, each of which does this independently — so
+ * it can report where an `exec()` call's wall time actually goes: the
+ * dial(s), the reserve round trip, the execute round trip, and the small
+ * amount of local bookkeeping after the peer's own work is done
+ * ("drain"). That attribution is the whole point of `onTiming`: the
+ * Firecracker relay path has a known, unexplained fixed cost, and the
+ * sub-second warm-acquire target this backend is judged against must be
+ * measured, not guessed at.
+ */
+
+import type {
+	OpenTerminalOptions,
+	SandboxExecOptions,
+	SandboxExecResult,
+	SandboxTcpConnectOptions,
+	SandboxTcpConnection,
+	TerminalSession,
+} from '@namzu/sdk'
+
+import type { ExecRequest } from '../firecracker/protocol.js'
+import {
+	type AgentRequest,
+	type SandboxAgentHandle,
+	VsockAgentTransport,
+	type VsockTransportOptions,
+} from '../firecracker/transport.js'
+import {
+	type RemoteExecutionAdapter,
+	RemoteExecutionController,
+} from '../remote-execution-controller.js'
+
+/** The one {@link SandboxAgentHandle} arm this backend ever constructs. */
+export type KubernetesAgentHandle = Extract<SandboxAgentHandle, { kind: 'tcp' }>
+
+/**
+ * Thrown when the guest agent refuses a request because the handle's
+ * token does not match what the pod is bound to. Named distinctly from
+ * {@link RemoteProtocolError} so a caller can tell "this credential is
+ * wrong" (never going to succeed by retrying) from "the wire shape was
+ * unexpected".
+ */
+export class KubernetesAgentUnauthorizedError extends Error {
+	constructor(
+		message = 'kubernetes tcp transport: the guest agent rejected this connection’s token (unauthorized)',
+	) {
+		super(message)
+		this.name = 'KubernetesAgentUnauthorizedError'
+	}
+}
+
+/** True for the wire shape `agent.cjs` sends when a token is rejected. */
+function isUnauthorized(response: unknown): boolean {
+	if (!response || typeof response !== 'object') return false
+	const value = response as { ok?: unknown; error?: unknown }
+	return value.ok === false && value.error === 'unauthorized'
+}
+
+/**
+ * One framed control request, with the guest's `unauthorized` refusal
+ * turned into {@link KubernetesAgentUnauthorizedError}.
+ *
+ * BOTH control requests go through here — `reserve-execution` and
+ * `cancel-execution` — because the two are read by the same caller for
+ * opposite reasons and neither may mistake a refusal for a blip. The
+ * cancel path is the sharper of the two: {@link RemoteExecutionController}
+ * RETRIES a failed cancellation for its whole confirm window and then
+ * reports the cancellation UNCONFIRMED, which retires the sandbox. A
+ * rejected token read as a transport failure would therefore spend that
+ * window re-sending a request that can never succeed, and end by
+ * describing a wrong credential as an ambiguous outcome.
+ */
+async function requestChecked(
+	wire: VsockAgentTransport,
+	request: AgentRequest,
+	signal?: AbortSignal,
+): Promise<unknown> {
+	const response = await wire.request(request, signal)
+	if (isUnauthorized(response)) throw new KubernetesAgentUnauthorizedError()
+	return response
+}
+
+/**
+ * One `exec()` call's wall-time breakdown. Durations are NOT a partition
+ * of a single total — `reserveMs` and `executeMs` each include their OWN
+ * dial, which is also folded into `dialMs` — this is a diagnostic
+ * breakdown for attribution, not an accounting identity. Never carries a
+ * token, a command, its arguments, or any output.
+ */
+export interface KubernetesTransportTiming {
+	/** Total time spent establishing TCP connections for this call. */
+	readonly dialMs: number
+	/** Time spent on the `reserve-execution` round trip (dial included). */
+	readonly reserveMs: number
+	/** Time spent on the `execute` round trip (dial included). */
+	readonly executeMs: number
+	/**
+	 * Time between the execute round trip settling and `exec()` itself
+	 * resolving — the shared controller's own post-execute bookkeeping
+	 * (clearing timers, tearing down the observation race). Always small
+	 * on the happy path; distinct from `executeMs` because it is spent
+	 * locally, after the peer has nothing left to do.
+	 */
+	readonly drainMs: number
+}
+
+export interface KubernetesTransportOptions extends VsockTransportOptions {
+	/**
+	 * Fires once per completed `exec()` call (success or failure) with
+	 * the four phase durations above. The payload is exactly those four
+	 * numbers — never the token, never a command, argv, or output.
+	 */
+	readonly onTiming?: (timing: KubernetesTransportTiming) => void
+}
+
+/**
+ * The kubernetes backend's dialable transport: a `tcp` handle plus a
+ * `RemoteExecutionAdapter` built from it, so `exec()` gets the same
+ * reserve-before-admission behaviour (cancellation, timeout ownership,
+ * "do not infer complete output on an ambiguous cancel") every other
+ * remote backend gets, while every network operation is delegated to
+ * {@link VsockAgentTransport} for the actual dial/frame/token work.
+ */
+export class KubernetesAgentTransport {
+	private readonly handle: KubernetesAgentHandle
+	private readonly transportOptions: VsockTransportOptions
+	private readonly onTiming?: (timing: KubernetesTransportTiming) => void
+	/** Simple pass-through operations share one transport instance. */
+	private readonly wire: VsockAgentTransport
+
+	constructor(handle: KubernetesAgentHandle, options: KubernetesTransportOptions = {}) {
+		const { onTiming, ...transportOptions } = options
+		this.handle = handle
+		this.transportOptions = transportOptions
+		this.onTiming = onTiming
+		this.wire = new VsockAgentTransport(handle, transportOptions)
+	}
+
+	/** Readiness probe — never requires a token; see `protocol.ts`. */
+	async healthz(signal?: AbortSignal): Promise<boolean> {
+		return await this.wire.healthz(signal)
+	}
+
+	/** Poll until `healthz` succeeds or the timeout elapses. */
+	async waitForReady(
+		timeoutMs: number,
+		pollIntervalMs: number,
+		signal?: AbortSignal,
+	): Promise<void> {
+		return await this.wire.waitForReady(timeoutMs, pollIntervalMs, signal)
+	}
+
+	/**
+	 * The raw `reserve-execution` primitive, exposed directly (rather than
+	 * only reachable as a side effect of `exec()`) so the reservation
+	 * round trip is independently observable and testable against the
+	 * real guest.
+	 */
+	async reserve(signal?: AbortSignal): Promise<unknown> {
+		return await requestChecked(this.wire, { op: 'reserve-execution' }, signal)
+	}
+
+	/**
+	 * The raw `cancel-execution` primitive, exposed for the same reason
+	 * {@link reserve} is: it is a control request with its own refusal
+	 * semantics, and proving those against the real guest should not require
+	 * driving a whole cancelled `exec()` to reach it.
+	 */
+	async cancel(executionId: string, signal?: AbortSignal): Promise<unknown> {
+		return await requestChecked(
+			this.wire,
+			{ op: 'cancel-execution', body: { executionId } },
+			signal,
+		)
+	}
+
+	async writeFile(path: string, content: Buffer): Promise<void> {
+		return await this.wire.writeFile(path, content)
+	}
+
+	async readFile(path: string): Promise<Buffer> {
+		return await this.wire.readFile(path)
+	}
+
+	async openTerminal(options: OpenTerminalOptions): Promise<TerminalSession> {
+		return await this.wire.openTerminal(options)
+	}
+
+	async openTcpConnection(options: SandboxTcpConnectOptions): Promise<SandboxTcpConnection> {
+		return await this.wire.openTcpConnection(options)
+	}
+
+	/**
+	 * Run one command through a fresh, call-scoped adapter + controller.
+	 * Fresh per call — not shared instance state — because
+	 * {@link VsockAgentTransport} itself carries no cross-call connection
+	 * state (it dials fresh every time), so building one per `exec()` is
+	 * free and makes concurrent `exec()` calls on the same
+	 * `KubernetesAgentTransport` correctly independent: each gets its own
+	 * `onDial` closure and its own timing accumulator, with no shared
+	 * mutable field for two in-flight calls to race on.
+	 */
+	async exec(
+		command: string,
+		argv?: string[],
+		opts?: SandboxExecOptions,
+	): Promise<SandboxExecResult> {
+		let dialMs = 0
+		let reserveMs = 0
+		let executeMs = 0
+		let executeSettledAt = 0
+
+		const timedWire = new VsockAgentTransport(this.handle, {
+			...this.transportOptions,
+			onDial: (ms) => {
+				dialMs += ms
+			},
+		})
+
+		const adapter: RemoteExecutionAdapter<Pick<ExecRequest, 'stdin' | 'maxOutputBytes'>> = {
+			label: 'kubernetes pod-network agent',
+			reserve: async (signal) => {
+				const startedAt = Date.now()
+				try {
+					return await requestChecked(timedWire, { op: 'reserve-execution' }, signal)
+				} finally {
+					reserveMs += Date.now() - startedAt
+				}
+			},
+			// Checked exactly like `reserve` — see `requestChecked`.
+			cancel: async (executionId, signal) =>
+				await requestChecked(timedWire, { op: 'cancel-execution', body: { executionId } }, signal),
+			execute: async (executionId, cmd, execArgv, execOpts, signal, context) => {
+				const startedAt = Date.now()
+				try {
+					return await timedWire.executeStreamed(
+						{
+							...(executionId ? { executionId } : {}),
+							command: cmd,
+							args: execArgv ?? [],
+							...(execOpts?.cwd !== undefined ? { cwd: execOpts.cwd } : {}),
+							...(execOpts?.env !== undefined ? { env: execOpts.env } : {}),
+							...(execOpts?.timeout !== undefined ? { timeoutMs: execOpts.timeout } : {}),
+							...(context?.stdin !== undefined ? { stdin: context.stdin } : {}),
+							...(context?.maxOutputBytes !== undefined
+								? { maxOutputBytes: context.maxOutputBytes }
+								: {}),
+						},
+						execOpts,
+						signal,
+					)
+				} finally {
+					executeMs += Date.now() - startedAt
+					executeSettledAt = Date.now()
+				}
+			},
+		}
+
+		const controller = new RemoteExecutionController(adapter)
+		try {
+			return await controller.exec(command, argv, opts)
+		} finally {
+			this.onTiming?.({
+				dialMs,
+				reserveMs,
+				executeMs,
+				drainMs: executeSettledAt > 0 ? Date.now() - executeSettledAt : 0,
+			})
+		}
+	}
+}