@secure-exec/browser 0.0.0-agentos-dylib-base.edaa4a4

package/README.md

@@ -0,0 +1,6 @@
+# Secure Exec Browser
+
+Browser driver primitives for secure-exec.
+
+- Package: `@secure-exec/browser`
+- Exports: `createBrowserDriver`, `createBrowserRuntimeDriverFactory`, `createOpfsFileSystem`, `BrowserWorkerAdapter`

package/dist/child-process-bridge.d.ts

@@ -0,0 +1,25 @@
+export type BrowserChildProcessBytes = {
+    __agentOsType: "bytes";
+    base64: string;
+};
+export type BrowserChildProcessSpawnOptions = {
+    cwd?: string;
+    env?: Record<string, string>;
+    input?: BrowserChildProcessBytes | string | Uint8Array;
+};
+export type BrowserChildProcessSpawnRequest = {
+    command: string;
+    args: string[];
+    options?: BrowserChildProcessSpawnOptions;
+};
+export type BrowserChildProcessPollEvent = {
+    type: "stdout" | "stderr";
+    data: BrowserChildProcessBytes;
+} | {
+    type: "exit";
+    exitCode: number;
+    signal: null;
+};
+export declare function encodeChildProcessBytes(data: Uint8Array): BrowserChildProcessBytes;
+export declare function decodeChildProcessInput(value: unknown): Uint8Array | undefined;
+export declare function parseChildProcessSpawnRequest(value: unknown, label: string): BrowserChildProcessSpawnRequest;

package/dist/child-process-bridge.js

@@ -0,0 +1,50 @@
+import { base64ToBytes, bytesToBase64, toUint8Array } from "./encoding.js";
+export function encodeChildProcessBytes(data) {
+    return {
+        __agentOsType: "bytes",
+        base64: bytesToBase64(data),
+    };
+}
+export function decodeChildProcessInput(value) {
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value === "object" &&
+        value.__agentOsType === "bytes" &&
+        typeof value.base64 === "string") {
+        return base64ToBytes(value.base64);
+    }
+    if (typeof value === "string") {
+        return new TextEncoder().encode(value);
+    }
+    return toUint8Array(value);
+}
+export function parseChildProcessSpawnRequest(value, label) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (!parsed || typeof parsed !== "object") {
+        throw new Error(`${label} must be an object`);
+    }
+    const record = parsed;
+    if (typeof record.command !== "string") {
+        throw new Error(`${label}.command must be a string`);
+    }
+    if (!Array.isArray(record.args)) {
+        throw new Error(`${label}.args must be an array`);
+    }
+    const rawOptions = record.options;
+    const optionsRecord = rawOptions && typeof rawOptions === "object"
+        ? rawOptions
+        : {};
+    const env = optionsRecord.env && typeof optionsRecord.env === "object"
+        ? Object.fromEntries(Object.entries(optionsRecord.env).map(([key, envValue]) => [key, String(envValue)]))
+        : undefined;
+    return {
+        command: record.command,
+        args: record.args.map((entry) => String(entry)),
+        options: {
+            cwd: typeof optionsRecord.cwd === "string" ? optionsRecord.cwd : undefined,
+            env,
+            input: optionsRecord.input,
+        },
+    };
+}

package/dist/converged-base64.d.ts

@@ -0,0 +1,2 @@
+export declare function encodeBase64(bytes: Uint8Array): string;
+export declare function decodeBase64(input: string): Uint8Array;

package/dist/converged-base64.js

@@ -0,0 +1,41 @@
+// Standard base64 codec over byte arrays, shared by the converged bridge
+// translation layers. Self-contained (no `atob`/`btoa`) so it behaves
+// identically in a Worker, the main thread, and Node/vitest, and is binary-safe
+// (atob/btoa are latin1-only).
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function encodeBase64(bytes) {
+    let output = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const byte0 = bytes[index];
+        const byte1 = bytes[index + 1];
+        const byte2 = bytes[index + 2];
+        const triple = (byte0 << 16) | ((byte1 ?? 0) << 8) | (byte2 ?? 0);
+        output += BASE64_ALPHABET[(triple >> 18) & 0x3f];
+        output += BASE64_ALPHABET[(triple >> 12) & 0x3f];
+        output +=
+            index + 1 < bytes.length ? BASE64_ALPHABET[(triple >> 6) & 0x3f] : "=";
+        output +=
+            index + 2 < bytes.length ? BASE64_ALPHABET[triple & 0x3f] : "=";
+    }
+    return output;
+}
+export function decodeBase64(input) {
+    const clean = input.replace(/[^A-Za-z0-9+/]/g, "");
+    const length = Math.floor((clean.length * 3) / 4);
+    const bytes = new Uint8Array(length);
+    let outIndex = 0;
+    for (let index = 0; index < clean.length; index += 4) {
+        const enc0 = BASE64_ALPHABET.indexOf(clean[index]);
+        const enc1 = BASE64_ALPHABET.indexOf(clean[index + 1]);
+        const enc2 = BASE64_ALPHABET.indexOf(clean[index + 2]);
+        const enc3 = BASE64_ALPHABET.indexOf(clean[index + 3]);
+        const triple = (enc0 << 18) | (enc1 << 12) | ((enc2 & 0x3f) << 6) | (enc3 & 0x3f);
+        if (outIndex < length)
+            bytes[outIndex++] = (triple >> 16) & 0xff;
+        if (enc2 !== -1 && outIndex < length)
+            bytes[outIndex++] = (triple >> 8) & 0xff;
+        if (enc3 !== -1 && outIndex < length)
+            bytes[outIndex++] = triple & 0xff;
+    }
+    return bytes;
+}

package/dist/converged-dgram-bridge.d.ts

@@ -0,0 +1,11 @@
+import type { ConvergedSyncResponse } from "./converged-fs-bridge.js";
+import type { GuestKernelCallRequestPayload } from "./converged-net-bridge.js";
+export declare function isConvergedDgramBridgeOperation(operation: string): boolean;
+/** True if `operation` needs a wasm kernel round-trip (vs an inline response). */
+export declare function dgramOperationUsesKernel(operation: string): boolean;
+/** Inline response for buffer-size ops (no kernel counterpart; advisory). */
+export declare function convergedDgramInlineResponse(operation: string): ConvergedSyncResponse;
+/** Translate a guest `dgram.*` sync op + positional args into a kernel call. */
+export declare function convergedDgramRequestPayload(operation: string, args: readonly unknown[], executionId: string): GuestKernelCallRequestPayload;
+/** Map a kernel `dgram.*` JSON result back into the guest's expected shape. */
+export declare function convergedDgramSyncResponse(operation: string, result: unknown): ConvergedSyncResponse;

package/dist/converged-dgram-bridge.js

@@ -0,0 +1,147 @@
+// Converged dgram (UDP) bridge translation layer.
+//
+// The guest worker already issues `dgram.*` sync-bridge ops (positional args).
+// This routes them to the wasm kernel UDP socket table via `guest_kernel_call`
+// (`dgram.*` ops in `sidecar-core::guest_net`) instead of the legacy in-process
+// TS dgram sessions, and maps the kernel responses back to the exact shapes the
+// guest dgram module consumes (mirroring the legacy servicer). Buffer-size ops
+// have no kernel counterpart and are handled inline (advisory).
+import { encodeBase64 } from "./converged-base64.js";
+import { SYNC_BRIDGE_KIND_JSON } from "./sync-bridge.js";
+const KERNEL_DGRAM_OPERATIONS = new Set([
+    "dgram.create",
+    "dgram.bind",
+    "dgram.recv",
+    "dgram.send",
+    "dgram.close",
+    "dgram.address",
+]);
+const BUFFER_SIZE_OPERATIONS = new Set([
+    "dgram.setBufferSize",
+    "dgram.getBufferSize",
+]);
+const DEFAULT_BUFFER_SIZE = 65536;
+export function isConvergedDgramBridgeOperation(operation) {
+    return (KERNEL_DGRAM_OPERATIONS.has(operation) ||
+        BUFFER_SIZE_OPERATIONS.has(operation));
+}
+/** True if `operation` needs a wasm kernel round-trip (vs an inline response). */
+export function dgramOperationUsesKernel(operation) {
+    return KERNEL_DGRAM_OPERATIONS.has(operation);
+}
+/** Inline response for buffer-size ops (no kernel counterpart; advisory). */
+export function convergedDgramInlineResponse(operation) {
+    if (operation === "dgram.getBufferSize") {
+        return { kind: SYNC_BRIDGE_KIND_JSON, value: { size: DEFAULT_BUFFER_SIZE } };
+    }
+    return { kind: SYNC_BRIDGE_KIND_JSON, value: { ok: true } };
+}
+/** Translate a guest `dgram.*` sync op + positional args into a kernel call. */
+export function convergedDgramRequestPayload(operation, args, executionId) {
+    const request = buildKernelRequest(operation, args);
+    return {
+        type: "guest_kernel_call",
+        execution_id: executionId,
+        operation,
+        payload: encodeJsonBytes(request),
+    };
+}
+/** Map a kernel `dgram.*` JSON result back into the guest's expected shape. */
+export function convergedDgramSyncResponse(operation, result) {
+    const value = (result ?? {});
+    switch (operation) {
+        case "dgram.create":
+            return { kind: SYNC_BRIDGE_KIND_JSON, value: { socketId: value.socketId } };
+        case "dgram.bind":
+            return { kind: SYNC_BRIDGE_KIND_JSON, value: { ok: true } };
+        case "dgram.close":
+            return { kind: SYNC_BRIDGE_KIND_JSON, value: { ok: true } };
+        case "dgram.send":
+            return { kind: SYNC_BRIDGE_KIND_JSON, value: { bytes: value.bytes ?? 0 } };
+        case "dgram.recv": {
+            if (value.data === null || value.data === undefined) {
+                return { kind: SYNC_BRIDGE_KIND_JSON, value: null };
+            }
+            const remoteAddress = String(value.remoteAddress ?? "");
+            return {
+                kind: SYNC_BRIDGE_KIND_JSON,
+                value: {
+                    type: "message",
+                    data: value.data,
+                    remoteAddress,
+                    remotePort: value.remotePort,
+                    remoteFamily: remoteAddress.includes(":") ? "IPv6" : "IPv4",
+                },
+            };
+        }
+        case "dgram.address": {
+            if (value.host === null || value.host === undefined) {
+                const error = new Error("getsockname EBADF");
+                error.code = "EBADF";
+                throw error;
+            }
+            const address = String(value.host);
+            return {
+                kind: SYNC_BRIDGE_KIND_JSON,
+                value: {
+                    address,
+                    port: value.port,
+                    family: address.includes(":") ? "IPv6" : "IPv4",
+                },
+            };
+        }
+        default:
+            throw new Error(`converged dgram bridge has no response for ${operation}`);
+    }
+}
+function buildKernelRequest(operation, args) {
+    switch (operation) {
+        case "dgram.create":
+            return {};
+        case "dgram.bind": {
+            const options = (args[1] ?? {});
+            return {
+                socketId: requireSocketId(args[0]),
+                host: typeof options.address === "string" ? options.address : "127.0.0.1",
+                port: typeof options.port === "number" ? options.port : 0,
+            };
+        }
+        case "dgram.recv":
+            return { socketId: requireSocketId(args[0]) };
+        case "dgram.send": {
+            const target = (args[2] ?? {});
+            return {
+                socketId: requireSocketId(args[0]),
+                host: typeof target.address === "string" ? target.address : "127.0.0.1",
+                port: typeof target.port === "number" ? target.port : 0,
+                data: encodeBase64(toUint8Array(args[1])),
+            };
+        }
+        case "dgram.close":
+        case "dgram.address":
+            return { socketId: requireSocketId(args[0]) };
+        default:
+            throw new Error(`converged dgram bridge has no mapping for ${operation}`);
+    }
+}
+function requireSocketId(value) {
+    const socketId = typeof value === "string" ? Number(value) : value;
+    if (typeof socketId !== "number" || Number.isNaN(socketId)) {
+        throw new Error("converged dgram bridge call requires a numeric socketId");
+    }
+    return socketId;
+}
+function toUint8Array(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    throw new Error("converged dgram send requires binary data");
+}
+function encodeJsonBytes(value) {
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}

package/dist/converged-driver-setup.d.ts

@@ -0,0 +1,22 @@
+import type { CreateVmConfig } from "@secure-exec/core/vm-config";
+import type { ProtocolFramePayloadCodec } from "@secure-exec/core/protocol-frames";
+import type { ConvergedSyncResponse } from "./converged-fs-bridge.js";
+import { ConvergedExecutorSession } from "./converged-executor-session.js";
+import { type LegacySyncBridgeServicer } from "./converged-sync-bridge-router.js";
+export interface ConvergedServicerOptions {
+    pushFrame: (frame: Uint8Array) => Uint8Array;
+    config: CreateVmConfig;
+    codec?: ProtocolFramePayloadCodec;
+    setNextExecutionId?: (executionId: string) => void;
+    onFsReadDenied?: () => void;
+}
+export interface ConvergedServicer {
+    /**
+     * Service one guest sync-bridge operation: fs/net/dns to the wasm handler,
+     * module.* to the kernel-backed resolver, everything else to `legacy`.
+     */
+    route(executionId: string, operation: string, args: readonly unknown[], legacy: LegacySyncBridgeServicer): Promise<ConvergedSyncResponse>;
+    /** Snapshot the VM root filesystem (for host persistence, e.g. OPFS). */
+    snapshotRootFilesystem(): ReturnType<ConvergedExecutorSession["snapshotRootFilesystem"]>;
+}
+export declare function createConvergedServicer(options: ConvergedServicerOptions): ConvergedServicer;

package/dist/converged-driver-setup.js

@@ -0,0 +1,72 @@
+// Converged driver servicer assembly.
+//
+// Bundles the converged executor pieces (session bootstrap, fs/net/dns handler,
+// kernel-backed module resolver, router) into a single servicer the runtime
+// driver uses to satisfy a guest's sync-bridge requests against the wasm kernel.
+//
+// The runtime driver loads this DYNAMICALLY (only when a converged sidecar is
+// configured) so the legacy, unbundled `/dist/` driver load never pulls in the
+// bare `@secure-exec/core/*` imports these modules need — those resolve only
+// when the converged runtime is esbuild-bundled.
+import { isConvergedDgramBridgeOperation } from "./converged-dgram-bridge.js";
+import { ConvergedExecutorSession } from "./converged-executor-session.js";
+import { ConvergedModuleServicer } from "./converged-module-servicer.js";
+import { isConvergedNetBridgeOperation } from "./converged-net-bridge.js";
+import { ConvergedSyncBridgeRouter, } from "./converged-sync-bridge-router.js";
+import { KernelBackedFilesystem } from "./kernel-backed-filesystem.js";
+const FS_READ_OPERATIONS = new Set([
+    "fs.readFile",
+    "fs.readFileBinary",
+    "fs.readDir",
+    "fs.stat",
+    "fs.lstat",
+    "fs.exists",
+    "fs.realpath",
+    "fs.readlink",
+]);
+export function createConvergedServicer(options) {
+    const session = new ConvergedExecutorSession({
+        pushFrame: options.pushFrame,
+        codec: options.codec,
+    });
+    session.bootstrap({ runtime: "java_script", config: options.config });
+    const moduleServicer = new ConvergedModuleServicer(new KernelBackedFilesystem(session.transportForVm()));
+    const registeredExecutions = new Set();
+    const ensureExecutionRegistered = (executionId) => {
+        if (registeredExecutions.has(executionId) || !options.setNextExecutionId) {
+            return;
+        }
+        options.setNextExecutionId(executionId);
+        session.registerExecution({ processId: executionId, args: ["node"] });
+        registeredExecutions.add(executionId);
+    };
+    return {
+        async route(executionId, operation, args, legacy) {
+            // Guest net/dgram need a kernel process (pid); register it lazily on
+            // first use so the guest_kernel_call resolves execution_id -> pid.
+            if (isConvergedNetBridgeOperation(operation) ||
+                isConvergedDgramBridgeOperation(operation)) {
+                ensureExecutionRegistered(executionId);
+            }
+            const router = new ConvergedSyncBridgeRouter({
+                handler: session.handlerForExecution(executionId),
+                asyncServicers: [moduleServicer],
+                legacy,
+            });
+            try {
+                return await router.route(operation, args);
+            }
+            catch (error) {
+                if (options.onFsReadDenied &&
+                    FS_READ_OPERATIONS.has(operation) &&
+                    error?.code === "EACCES") {
+                    options.onFsReadDenied();
+                }
+                throw error;
+            }
+        },
+        snapshotRootFilesystem() {
+            return session.snapshotRootFilesystem();
+        },
+    };
+}

package/dist/converged-execution-host-bridge.d.ts

@@ -0,0 +1,7 @@
+export interface ConvergedExecutionHostBridge {
+    /** Set the execution id `startExecution` will echo for the next `execute`. */
+    setNextExecutionId(executionId: string): void;
+    /** The host-bridge object passed to `new BrowserSidecarWasm(bridge)`. */
+    readonly bridge: Record<string, (requestJson: string) => unknown>;
+}
+export declare function createConvergedExecutionHostBridge(): ConvergedExecutionHostBridge;

package/dist/converged-execution-host-bridge.js

@@ -0,0 +1,85 @@
+// Execution host bridge for the converged wasm sidecar.
+//
+// In the converged browser runtime the guest runs in the browser worker, not in
+// the wasm sidecar. But guest `net.*`/`dgram.*` syscalls need a kernel process
+// (pid) and socket ownership inside the sidecar, which is created by an `execute`
+// wire request. That request drives these host-bridge callbacks. They are
+// no-ops that just satisfy the sidecar's execution lifecycle: the only one that
+// matters is `startExecution`, which echoes the driver-provided execution id so
+// the sidecar registers the kernel process under the SAME id the guest worker
+// uses in its sync-bridge `guest_kernel_call`s.
+//
+// The wasm `BrowserJsBridge` invokes each method with a JSON request string and
+// JSON-decodes the return value.
+export function createConvergedExecutionHostBridge() {
+    let nextExecutionId = "converged-exec";
+    let contextCounter = 0;
+    let workerCounter = 0;
+    const bridge = {
+        createJavascriptContext() {
+            contextCounter += 1;
+            return { contextId: `converged-ctx-${contextCounter}` };
+        },
+        createWasmContext() {
+            contextCounter += 1;
+            return { contextId: `converged-wasm-ctx-${contextCounter}` };
+        },
+        startExecution() {
+            return { executionId: nextExecutionId };
+        },
+        createWorker(requestJson) {
+            workerCounter += 1;
+            const request = parse(requestJson);
+            return {
+                workerId: `converged-worker-${workerCounter}`,
+                runtime: typeof request.runtime === "string" ? request.runtime : undefined,
+            };
+        },
+        writeExecutionStdin() {
+            return {};
+        },
+        closeExecutionStdin() {
+            return {};
+        },
+        killExecution() {
+            return {};
+        },
+        pollExecutionEvent() {
+            return null;
+        },
+        terminateWorker() {
+            return {};
+        },
+        // Diagnostics/observability callbacks the execute lifecycle emits; no-ops
+        // here (the converged driver surfaces events through its own channels).
+        emitStructuredEvent() {
+            return {};
+        },
+        emitDiagnostic() {
+            return {};
+        },
+        emitLog() {
+            return {};
+        },
+        emitLifecycle() {
+            return {};
+        },
+    };
+    return {
+        setNextExecutionId(executionId) {
+            nextExecutionId = executionId;
+        },
+        bridge,
+    };
+}
+function parse(requestJson) {
+    try {
+        const value = JSON.parse(requestJson);
+        return typeof value === "object" && value !== null
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/converged-executor-session.d.ts

@@ -0,0 +1,60 @@
+import type { CreateVmConfig } from "@secure-exec/core/vm-config";
+import type { LiveRootFilesystemEntry as RootFilesystemEntry } from "@secure-exec/core/filesystem";
+import type { ProtocolFramePayloadCodec } from "@secure-exec/core/protocol-frames";
+import type { LiveRequestPayload } from "@secure-exec/core/request-payloads";
+import { ConvergedSyncBridgeHandler, type ConvergedPushFrame, PushFrameSidecarTransport } from "./converged-sync-bridge-handler.js";
+type GuestRuntimeKind = Extract<LiveRequestPayload, {
+    type: "create_vm";
+}>["runtime"];
+export interface ConvergedExecutorSessionOptions {
+    pushFrame: ConvergedPushFrame;
+    codec?: ProtocolFramePayloadCodec;
+}
+export interface ConvergedVmBootstrap {
+    runtime: GuestRuntimeKind;
+    config: CreateVmConfig;
+    sessionMetadata?: Record<string, string>;
+}
+/** A bootstrapped VM inside the wasm sidecar. */
+export interface ConvergedVm {
+    connectionId: string;
+    sessionId: string;
+    vmId: string;
+}
+export declare class ConvergedExecutorSession {
+    private readonly pushFrame;
+    private readonly codec;
+    private vm;
+    constructor(options: ConvergedExecutorSessionOptions);
+    /** The bootstrapped VM, or throw if `bootstrap()` has not run. */
+    get currentVm(): ConvergedVm;
+    /** Run the authenticate -> open_session -> create_vm handshake. */
+    bootstrap(options: ConvergedVmBootstrap): ConvergedVm;
+    /** A synchronous syscall handler scoped to the bootstrapped VM + execution. */
+    handlerForExecution(executionId: string): ConvergedSyncBridgeHandler;
+    /**
+     * Register a guest execution (kernel process) in the sidecar via an `execute`
+     * wire request, so guest `net.*`/`dgram.*` syscalls can resolve their
+     * `execution_id` to a kernel pid. The guest itself runs in the browser worker;
+     * this only owns the kernel-side process/socket lifecycle. Requires the wasm
+     * sidecar to be constructed with an execution host bridge whose
+     * `startExecution` echoes `processId` back as the execution id.
+     */
+    registerExecution(options: {
+        processId: string;
+        entrypoint?: string;
+        args?: readonly string[];
+        cwd?: string;
+    }): {
+        processId: string;
+    };
+    /**
+     * Snapshot the VM's root filesystem (the writable changes) so callers can
+     * persist them to host storage (e.g. OPFS) across runtimes.
+     */
+    snapshotRootFilesystem(): RootFilesystemEntry[];
+    /** A request transport bound to the bootstrapped VM ownership. */
+    transportForVm(): PushFrameSidecarTransport;
+    private send;
+}
+export {};

package/dist/converged-executor-session.js

@@ -0,0 +1,127 @@
+// Converged executor session bootstrap.
+//
+// Brings up a VM inside the wasm sidecar over the synchronous `pushFrame`
+// dispatcher (authenticate -> open_session -> create_vm), then hands out a
+// per-execution `ConvergedSyncBridgeHandler` bound to that VM's ownership. This
+// is the glue between the wasm sidecar and the guest Worker's sync-bridge: the
+// handshake runs once at setup, and each guest execution gets a synchronous
+// handler that routes its syscalls to the kernel.
+//
+// The handshake uses the same client identity and versions as the core
+// `SidecarProcess` so the wasm sidecar accepts it. Unit-tested with a fake
+// synchronous `pushFrame`.
+import { SIDECAR_PROTOCOL_SCHEMA } from "@secure-exec/core/protocol-schema";
+import { ConvergedSyncBridgeHandler, PushFrameSidecarTransport, } from "./converged-sync-bridge-handler.js";
+// Mirror `SidecarProcess`'s client identity so the sidecar handshake succeeds.
+const CLIENT_NAME = "secure-exec-core-client";
+const AUTH_TOKEN = "secure-exec-core-client-token";
+const BRIDGE_CONTRACT_VERSION = 1;
+export class ConvergedExecutorSession {
+    pushFrame;
+    codec;
+    vm;
+    constructor(options) {
+        this.pushFrame = options.pushFrame;
+        this.codec = options.codec ?? "bare";
+    }
+    /** The bootstrapped VM, or throw if `bootstrap()` has not run. */
+    get currentVm() {
+        if (!this.vm) {
+            throw new Error("converged executor session has not bootstrapped a VM");
+        }
+        return this.vm;
+    }
+    /** Run the authenticate -> open_session -> create_vm handshake. */
+    bootstrap(options) {
+        const authenticated = this.send({ scope: "connection", connection_id: "client-hint" }, {
+            type: "authenticate",
+            client_name: CLIENT_NAME,
+            auth_token: AUTH_TOKEN,
+            protocol_version: SIDECAR_PROTOCOL_SCHEMA.version,
+            bridge_version: BRIDGE_CONTRACT_VERSION,
+        });
+        if (authenticated.type !== "authenticated") {
+            throw new Error(`unexpected authenticate response: ${authenticated.type}`);
+        }
+        const connectionId = authenticated.connection_id;
+        const opened = this.send({ scope: "connection", connection_id: connectionId }, {
+            type: "open_session",
+            placement: { kind: "shared", pool: null },
+            metadata: options.sessionMetadata ?? {},
+        });
+        if (opened.type !== "session_opened") {
+            throw new Error(`unexpected open_session response: ${opened.type}`);
+        }
+        const sessionId = opened.session_id;
+        const created = this.send({ scope: "session", connection_id: connectionId, session_id: sessionId }, { type: "create_vm", runtime: options.runtime, config: options.config });
+        if (created.type !== "vm_created") {
+            throw new Error(`unexpected create_vm response: ${created.type}`);
+        }
+        this.vm = { connectionId, sessionId, vmId: created.vm_id };
+        return this.vm;
+    }
+    /** A synchronous syscall handler scoped to the bootstrapped VM + execution. */
+    handlerForExecution(executionId) {
+        return new ConvergedSyncBridgeHandler({
+            transport: this.transportForVm(),
+            executionId,
+        });
+    }
+    /**
+     * Register a guest execution (kernel process) in the sidecar via an `execute`
+     * wire request, so guest `net.*`/`dgram.*` syscalls can resolve their
+     * `execution_id` to a kernel pid. The guest itself runs in the browser worker;
+     * this only owns the kernel-side process/socket lifecycle. Requires the wasm
+     * sidecar to be constructed with an execution host bridge whose
+     * `startExecution` echoes `processId` back as the execution id.
+     */
+    registerExecution(options) {
+        const response = this.transportForVm().sendRequest({
+            type: "execute",
+            process_id: options.processId,
+            runtime: "java_script",
+            entrypoint: options.entrypoint,
+            args: [...(options.args ?? [])],
+            cwd: options.cwd,
+        });
+        if (response.type !== "process_started") {
+            throw new Error(`unexpected execute response: ${response.type}`);
+        }
+        return { processId: response.process_id };
+    }
+    /**
+     * Snapshot the VM's root filesystem (the writable changes) so callers can
+     * persist them to host storage (e.g. OPFS) across runtimes.
+     */
+    snapshotRootFilesystem() {
+        const response = this.transportForVm().sendRequest({
+            type: "snapshot_root_filesystem",
+        });
+        if (response.type !== "root_filesystem_snapshot") {
+            throw new Error(`unexpected snapshot_root_filesystem response: ${response.type}`);
+        }
+        return response.entries;
+    }
+    /** A request transport bound to the bootstrapped VM ownership. */
+    transportForVm() {
+        const vm = this.currentVm;
+        return new PushFrameSidecarTransport({
+            pushFrame: this.pushFrame,
+            codec: this.codec,
+            ownership: {
+                scope: "vm",
+                connection_id: vm.connectionId,
+                session_id: vm.sessionId,
+                vm_id: vm.vmId,
+            },
+        });
+    }
+    send(ownership, payload) {
+        const transport = new PushFrameSidecarTransport({
+            pushFrame: this.pushFrame,
+            codec: this.codec,
+            ownership,
+        });
+        return transport.sendRequest(payload);
+    }
+}