@sandboxxjs/core 0.5.0 → 2.0.0

package/dist/protocol.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Sandbox protocol — WebSocket message types between sandbox-client and service.
+ *
+ * This protocol covers lifecycle steps 3-5:
+ *   Register: client sends RegisterMessage, service responds RegisteredMessage
+ *   Ready:    heartbeat keeps connection alive
+ *   Command:  service sends commands, client returns results
+ *
+ * All sandbox-clients (cloud, web, future types) speak this same protocol.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ */
+export interface RegisterMessage {
+    type: "register";
+    sandboxId: string;
+    token: string;
+}
+export interface ResultMessage {
+    type: "result";
+    id: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface FsResultMessage {
+    type: "fs.result";
+    id: string;
+    data: unknown;
+}
+export interface ErrorMessage {
+    type: "error";
+    id: string;
+    message: string;
+}
+export interface HeartbeatMessage {
+    type: "heartbeat";
+}
+export interface ExecMessage {
+    type: "exec";
+    id: string;
+    command: string;
+    cwd?: string;
+    timeout?: number;
+}
+export interface FsReadMessage {
+    type: "fs.read";
+    id: string;
+    path: string;
+}
+export interface FsWriteMessage {
+    type: "fs.write";
+    id: string;
+    path: string;
+    content: string;
+}
+export interface FsListMessage {
+    type: "fs.list";
+    id: string;
+    path: string;
+}
+export interface FsMkdirMessage {
+    type: "fs.mkdir";
+    id: string;
+    path: string;
+    recursive?: boolean;
+}
+export interface FsDeleteMessage {
+    type: "fs.delete";
+    id: string;
+    path: string;
+}
+export interface ProcessStartMessage {
+    type: "process.start";
+    id: string;
+    command: string;
+    cwd?: string;
+}
+export interface ProcessKillMessage {
+    type: "process.kill";
+    id: string;
+    processId: string;
+}
+export interface ProcessListMessage {
+    type: "process.list";
+    id: string;
+}
+export interface RegisteredMessage {
+    type: "registered";
+    sandboxId: string;
+}
+/** Messages sent from sandbox-client to service */
+export type ClientMessage = RegisterMessage | ResultMessage | FsResultMessage | ErrorMessage | HeartbeatMessage;
+/** Messages sent from service to sandbox-client */
+export type ServiceMessage = ExecMessage | FsReadMessage | FsWriteMessage | FsListMessage | FsMkdirMessage | FsDeleteMessage | ProcessStartMessage | ProcessKillMessage | ProcessListMessage | RegisteredMessage;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;CACnB;AAID,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,mDAAmD;AACnD,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,aAAa,GACb,eAAe,GACf,YAAY,GACZ,gBAAgB,CAAC;AAErB,mDAAmD;AACnD,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,aAAa,GACb,cAAc,GACd,aAAa,GACb,cAAc,GACd,eAAe,GACf,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,15 @@
+/**
+ * Sandbox protocol — WebSocket message types between sandbox-client and service.
+ *
+ * This protocol covers lifecycle steps 3-5:
+ *   Register: client sends RegisterMessage, service responds RegisteredMessage
+ *   Ready:    heartbeat keeps connection alive
+ *   Command:  service sends commands, client returns results
+ *
+ * All sandbox-clients (cloud, web, future types) speak this same protocol.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/provider.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SandboxProvider — platform capability injection.
+ *
+ * Provider is a component factory that supplies platform-specific
+ * implementations of Executor, FileSystem, and ProcessManager.
+ *
+ * The core layer (createSandboxClient) only depends on this interface.
+ * Platform differences are isolated in provider implementations:
+ *   - node-provider: child_process + node:fs
+ *   - web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, etc.
+ */
+import type { ExecOptions, ExecResult, FileInfo, ProcessInfo } from "./sandbox";
+/**
+ * Command execution component.
+ */
+export interface SandboxExecutor {
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+}
+/**
+ * File system component.
+ */
+export interface SandboxFileSystem {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    listFiles(path: string): Promise<FileInfo[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+}
+/**
+ * Process management component.
+ */
+export interface SandboxProcessManager {
+    start(command: string, options?: {
+        cwd?: string;
+    }): Promise<ProcessInfo>;
+    kill(processId: string): Promise<void>;
+    list(): Promise<ProcessInfo[]>;
+}
+/**
+ * SandboxProvider — the component factory.
+ *
+ * Each platform implements this interface to provide its components.
+ * createSandboxClient(provider) obtains components and dispatches
+ * incoming messages to the appropriate component.
+ */
+export interface SandboxProvider {
+    createExecutor(): SandboxExecutor;
+    createFileSystem(): SandboxFileSystem;
+    createProcessManager(): SandboxProcessManager;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEhF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACnE;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACzE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,cAAc,IAAI,eAAe,CAAC;IAClC,gBAAgB,IAAI,iBAAiB,CAAC;IACtC,oBAAoB,IAAI,qBAAqB,CAAC;CAC/C"}

package/dist/provider.js

@@ -0,0 +1,14 @@
+/**
+ * SandboxProvider — platform capability injection.
+ *
+ * Provider is a component factory that supplies platform-specific
+ * implementations of Executor, FileSystem, and ProcessManager.
+ *
+ * The core layer (createSandboxClient) only depends on this interface.
+ * Platform differences are isolated in provider implementations:
+ *   - node-provider: child_process + node:fs
+ *   - web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, etc.
+ */
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SandboxRegistry — accepts sandbox-client connections and manages lifecycle.
+ *
+ * Step 3-4 of the lifecycle: Register → Ready.
+ *
+ * When a sandbox-client connects via WebSocket and sends a register message,
+ * the registry:
+ *   1. Validates the token
+ *   2. Binds the WebSocket connection to the sandboxId
+ *   3. Updates the sandbox status from "pending" to "ready"
+ *   4. Provides the command routing channel
+ *
+ * The registry also handles disconnection, heartbeat, and reconnection.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^
+ */
+export interface SandboxConnection {
+    sandboxId: string;
+    connectedAt: number;
+}
+export interface SandboxRegistry {
+    /** Check if a sandbox-client is connected and ready */
+    has(sandboxId: string): boolean;
+    /** List all active connections */
+    connections(): SandboxConnection[];
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,kCAAkC;IAClC,WAAW,IAAI,iBAAiB,EAAE,CAAC;CACpC"}

package/dist/registry.js

@@ -0,0 +1,19 @@
+/**
+ * SandboxRegistry — accepts sandbox-client connections and manages lifecycle.
+ *
+ * Step 3-4 of the lifecycle: Register → Ready.
+ *
+ * When a sandbox-client connects via WebSocket and sends a register message,
+ * the registry:
+ *   1. Validates the token
+ *   2. Binds the WebSocket connection to the sandboxId
+ *   3. Updates the sandbox status from "pending" to "ready"
+ *   4. Provides the command routing channel
+ *
+ * The registry also handles disconnection, heartbeat, and reconnection.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                 ^^^^^^^^^^^^^^^^^
+ */
+export {};
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/router.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SandboxRouter — routes RPC methods to sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * The router is the external-facing RPC interface.
+ * It combines the allocator (lifecycle) and registry (connections)
+ * to provide a unified dispatch: method + params → result.
+ *
+ * Internally, it resolves the sandboxId from params, finds the
+ * connected sandbox-client through the registry, and forwards
+ * the command over WebSocket.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+import type { Sandbox } from "./sandbox";
+export interface SandboxRouter {
+    /** Get a Sandbox handle by id — routes through registry to connected client */
+    getSandbox(sandboxId: string): Sandbox;
+    /** Dispatch an RPC method with params */
+    dispatch(method: string, params: Record<string, unknown>): Promise<unknown>;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E"}

package/dist/router.js

@@ -0,0 +1,18 @@
+/**
+ * SandboxRouter — routes RPC methods to sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * The router is the external-facing RPC interface.
+ * It combines the allocator (lifecycle) and registry (connections)
+ * to provide a unified dispatch: method + params → result.
+ *
+ * Internally, it resolves the sandboxId from params, finds the
+ * connected sandbox-client through the registry, and forwards
+ * the command over WebSocket.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+export {};
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/sandbox.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Sandbox — the unified interface for sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * Consumers get a Sandbox instance and operate on it.
+ * They never need to know if it's a cloud container, a browser WebContainer,
+ * or any other sandbox type. All commands are routed through the registry
+ * to the connected sandbox-client.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+export interface ExecOptions {
+    cwd?: string;
+    timeout?: number;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    success: boolean;
+}
+export interface ProcessInfo {
+    id: string;
+    pid?: number;
+    command: string;
+    status: string;
+}
+export interface FileInfo {
+    name: string;
+    type: "file" | "directory" | "symlink";
+    size?: number;
+}
+export interface Sandbox {
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    startProcess(command: string, options?: {
+        cwd?: string;
+    }): Promise<ProcessInfo>;
+    killProcess(processId: string): Promise<void>;
+    listProcesses(): Promise<ProcessInfo[]>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    listFiles(path: string): Promise<FileInfo[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    deleteFile(path: string): Promise<void>;
+    exposePort(port: number, hostname: string): Promise<{
+        url: string;
+    }>;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAClE,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAChF,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,aAAa,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B"}

package/dist/sandbox.js

@@ -0,0 +1,15 @@
+/**
+ * Sandbox — the unified interface for sandbox operations.
+ *
+ * Step 5 of the lifecycle: Command.
+ *
+ * Consumers get a Sandbox instance and operate on it.
+ * They never need to know if it's a cloud container, a browser WebContainer,
+ * or any other sandbox type. All commands are routed through the registry
+ * to the connected sandbox-client.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                                                     ^^^^^^^
+ */
+export {};
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/package.json

@@ -1,51 +1,26 @@
 {
   "name": "@sandboxxjs/core",
-  "version": "0.5.0",
-  "description": "SandboX Core - Secure code execution engine",
-  "keywords": [
-    "sandbox",
-    "execution",
-    "security",
-    "isolation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Deepractice/SandboX.git",
-    "directory": "packages/core"
-  },
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.0.0"
-  },
+  "version": "2.0.0",
+  "description": "Core interfaces and runtime for sandboxxjs — unified sandbox lifecycle",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
   "scripts": {
-    "build": "bun run build.ts",
-    "lint": "eslint .",
+    "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "bun test",
     "clean": "rm -rf dist"
   },
-  "devDependencies": {},
   "publishConfig": {
     "access": "public"
-  },
-  "dependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.32",
-    "@sandboxxjs/cloudflare-isolator": "^0.5.0",
-    "@sandboxxjs/state": "^0.5.0",
-    "execa": "^9.6.1",
-    "nanoid": "^5.1.6"
   }
 }

package/src/allocator.ts

@@ -0,0 +1,48 @@
+/**
+ * SandboxAllocator — provisions sandbox resources.
+ *
+ * Step 1 of the lifecycle: Allocate.
+ *
+ * The allocator creates a sandbox environment and returns a SandboxContainer
+ * with status "pending". The sandbox is NOT ready for commands yet —
+ * it becomes ready only after a sandbox-client connects and registers.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *            ^^^^^^^^
+ */
+
+export type SandboxContainerType = "cloud" | "web";
+
+export type SandboxStatus = "pending" | "ready" | "destroyed";
+
+export interface SandboxContainer {
+  id: string;
+  type: SandboxContainerType;
+  status: SandboxStatus;
+  createdAt: number;
+  source?: string;
+  /** Connection info for sandbox-client to register */
+  connection: {
+    wsUrl: string;
+    token: string;
+  };
+}
+
+export interface AllocateRequest {
+  type?: SandboxContainerType;
+  sandboxId?: string;
+  source?: string;
+}
+
+export interface SandboxAllocator {
+  /** Allocate a sandbox — returns container with status "pending" */
+  allocate(request: AllocateRequest): Promise<SandboxContainer>;
+  /** Release sandbox resources */
+  deallocate(sandboxId: string): Promise<void>;
+  /** List all sandboxes */
+  list(): Promise<SandboxContainer[]>;
+  /** Get a single sandbox by id */
+  get(sandboxId: string): Promise<SandboxContainer | null>;
+  /** Update sandbox status (called by registry on registration) */
+  updateStatus(sandboxId: string, status: SandboxStatus): Promise<void>;
+}

package/src/client.ts

@@ -0,0 +1,51 @@
+/**
+ * SandboxClient — the agent that runs inside every sandbox environment.
+ *
+ * Step 2-3 of the lifecycle: Prepare → Register.
+ *
+ * After allocation, the sandbox environment starts a SandboxClient.
+ * The client connects to the service via WebSocket, registers itself,
+ * and then listens for commands (exec, fs, process operations).
+ *
+ * The client is platform-agnostic. Platform differences are injected
+ * via SandboxProvider, which supplies Executor, FileSystem, and
+ * ProcessManager components:
+ *   - node-provider: child_process + node:fs
+ *   - web-provider: @webcontainer/api
+ *   - Future: Docker, SSH, etc.
+ *
+ * Lifecycle: Allocate → Prepare → Register → Ready → Command
+ *                       ^^^^^^^^^^^^^^^^^
+ */
+
+/**
+ * Connection options for a sandbox-client.
+ */
+export interface SandboxClientOptions {
+  /** WebSocket URL of the sandbox service registry */
+  wsUrl: string;
+  /** Sandbox identifier */
+  sandboxId: string;
+  /** Authentication token */
+  token: string;
+  /** Heartbeat interval in milliseconds (default: 30000) */
+  heartbeatInterval?: number;
+}
+
+/**
+ * SandboxClient — connects to service, receives commands, executes via provider components.
+ *
+ * Usage:
+ *   const provider = new NodeProvider();            // or WebContainerProvider
+ *   const client = createSandboxClient(provider);
+ *   await client.connect({ wsUrl, sandboxId, token });
+ *   // Client is now registered and listening for commands
+ */
+export interface SandboxClient {
+  /** Connect to the sandbox service and register */
+  connect(options: SandboxClientOptions): Promise<void>;
+  /** Disconnect from the service */
+  disconnect(): Promise<void>;
+  /** Whether the client is connected and registered */
+  readonly connected: boolean;
+}