@ebowwa/sandbox 0.1.1

package/src/runtimes/process.ts

@@ -0,0 +1,316 @@
+/**
+ * Process Runtime
+ *
+ * Spawns child processes for code execution with elevated permissions.
+ * Supports filesystem and network access with configurable limits.
+ *
+ * Isolation level: 'process'
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { setTimeout as setTimeoutPromise } from "node:timers/promises";
+import type {
+  ExecutionResult,
+  Permissions,
+  Limits,
+  DisplayOutput,
+} from "../core/types.js";
+import type {
+  IRuntime,
+  RuntimeOptions,
+  ExecutionRequest,
+  RuntimeCapabilities,
+} from "../core/runtime.js";
+
+/** Process runtime configuration */
+export interface ProcessRuntimeConfig {
+  /** Default shell to use */
+  shell?: string;
+  /** Timeout for availability check */
+  availabilityTimeout?: number;
+}
+
+/**
+ * Process Runtime
+ *
+ * Executes code in child processes with configurable permissions.
+ * Provides filesystem and network access based on permission level.
+ */
+export class ProcessRuntime implements IRuntime {
+  readonly name = "process";
+  readonly capabilities: RuntimeCapabilities = {
+    isolation: "process",
+    stateful: true,
+    async: true,
+    filesystem: true,
+    network: true,
+    maxMemory: 4 * 1024 * 1024 * 1024, // 4GB
+    wasi: false,
+  };
+
+  private executing = false;
+  private config: ProcessRuntimeConfig;
+
+  constructor(config: ProcessRuntimeConfig = {}) {
+    this.config = {
+      shell: config.shell ?? "/bin/sh",
+      availabilityTimeout: config.availabilityTimeout ?? 5000,
+    };
+  }
+
+  async init(): Promise<void> {
+    // No special initialization needed for process runtime
+  }
+
+  async isAvailable(): Promise<boolean> {
+    // Process spawning is always available in Node.js
+    return typeof process !== "undefined" && typeof spawn === "function";
+  }
+
+  async execute(
+    request: ExecutionRequest,
+    options: RuntimeOptions
+  ): Promise<ExecutionResult> {
+    const startTime = Date.now();
+    this.executing = true;
+
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const displays: DisplayOutput[] = [];
+
+    try {
+      // Parse limits
+      const timeout = this.parseTimeout(options.limits?.timeout);
+      const maxMemory = this.parseMemory(options.limits?.memory);
+
+      // Build execution command based on code type
+      const { command, args } = this.buildCommand(request, options);
+
+      // Create abort controller for timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+      // Combine with external signal if provided
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => {
+          controller.abort();
+          clearTimeout(timeoutId);
+        });
+      }
+
+      // Spawn child process
+      const childProcess = spawn(command, args, {
+        cwd: options.cwd ?? process.cwd(),
+        env: {
+          ...process.env,
+          ...options.env,
+          NODE_OPTIONS: `--max-old-space-size=${Math.floor(maxMemory / (1024 * 1024))}`,
+        },
+        signal: controller.signal,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      // Collect stdout
+      childProcess.stdout?.on("data", (data: Buffer) => {
+        stdout.push(data.toString("utf8"));
+      });
+
+      // Collect stderr
+      childProcess.stderr?.on("data", (data: Buffer) => {
+        stderr.push(data.toString("utf8"));
+      });
+
+      // Handle process events
+      const result = await new Promise<ExecutionResult>((resolve) => {
+        let returnValue: unknown = undefined;
+
+        childProcess.on("error", (error: Error) => {
+          clearTimeout(timeoutId);
+          resolve(
+            this.createErrorResult(
+              `Process error: ${error.message}`,
+              "runtime",
+              startTime,
+              stdout,
+              stderr
+            )
+          );
+        });
+
+        childProcess.on("close", (code: number, signal: NodeJS.Signals | null) => {
+          clearTimeout(timeoutId);
+
+          if (signal) {
+            resolve(
+              this.createErrorResult(
+                `Process killed by signal: ${signal}`,
+                signal === "SIGTERM" ? "timeout" : "cancel",
+                startTime,
+                stdout,
+                stderr
+              )
+            );
+            return;
+          }
+
+          // Try to parse stdout as JSON for return value
+          const output = stdout.join("");
+          try {
+            const parsed = JSON.parse(output);
+            if (parsed.__return_value !== undefined) {
+              returnValue = parsed.__return_value;
+            }
+          } catch {
+            // Not JSON, use raw output as value
+            returnValue = output.trim() || undefined;
+          }
+
+          resolve({
+            success: code === 0,
+            value: returnValue,
+            metrics: {
+              duration: Date.now() - startTime,
+              memoryUsed: 0, // Not tracked at process level
+            },
+            output: { stdout, stderr, displays },
+          });
+        });
+
+        // Write input if provided
+        if (request.input !== undefined) {
+          const inputStr =
+            typeof request.input === "string"
+              ? request.input
+              : JSON.stringify(request.input);
+          childProcess.stdin?.write(inputStr);
+          childProcess.stdin?.end();
+        }
+      });
+
+      return result;
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        return this.createErrorResult(
+          "Execution timed out",
+          "timeout",
+          startTime,
+          stdout,
+          stderr
+        );
+      }
+
+      return this.createErrorResult(
+        error instanceof Error ? error.message : String(error),
+        "runtime",
+        startTime,
+        stdout,
+        stderr
+      );
+    } finally {
+      this.executing = false;
+    }
+  }
+
+  async terminate(): Promise<void> {
+    this.executing = false;
+  }
+
+  isExecuting(): boolean {
+    return this.executing;
+  }
+
+  /**
+   * Build command and arguments for execution
+   */
+  private buildCommand(
+    request: ExecutionRequest,
+    options: RuntimeOptions
+  ): { command: string; args: string[] } {
+    // Execute WASM using node with WASI support
+    return {
+      command: "node",
+      args: [
+        "--experimental-wasi-unstable-preview1",
+        "-e",
+        this.generateWasmRunner(request.wasm.wasmBytes, options.permissions),
+      ],
+    };
+  }
+
+  /**
+   * Generate WASM runner script
+   */
+  private generateWasmRunner(
+    wasmBytes: Uint8Array,
+    permissions: Permissions
+  ): string {
+    const hasFs = permissions.fs?.read || permissions.fs?.write;
+    const hasNetwork = permissions.network?.outbound || permissions.network?.inbound;
+
+    return `
+const { WASI } = require('wasi');
+const { readFile } = require('fs/promises');
+
+async function run() {
+  const wasmBuffer = Buffer.from([${Array.from(wasmBytes).join(",")}]);
+
+  const wasi = new WASI({
+    version: 'preview1',
+    preopens: ${hasFs ? "{ '/': process.cwd() }" : "{}"},
+    env: process.env,
+  });
+
+  const { instance } = await WebAssembly.instantiate(wasmBuffer, {
+    wasi_snapshot_preview1: wasi.wasiImport,
+  });
+
+  wasi.start(instance);
+}
+
+run().catch(console.error);
+`;
+  }
+
+  private createErrorResult(
+    message: string,
+    type: "compile" | "runtime" | "permission" | "limit" | "timeout" | "cancel",
+    startTime: number,
+    stdout: string[] = [],
+    stderr: string[] = []
+  ): ExecutionResult {
+    return {
+      success: false,
+      error: { message, type },
+      metrics: {
+        duration: Date.now() - startTime,
+        memoryUsed: 0,
+      },
+      output: { stdout, stderr, displays: [] },
+    };
+  }
+
+  private parseMemory(memory: string | number | undefined): number {
+    if (!memory) return 256 * 1024 * 1024; // 256MB default
+    if (typeof memory === "number") return memory;
+    const match = memory.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)?$/i);
+    if (!match) return 256 * 1024 * 1024;
+    const [, num, unit] = match;
+    const multipliers: Record<string, number> = {
+      b: 1, kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3,
+    };
+    return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "b"] ?? 1));
+  }
+
+  private parseTimeout(timeout: string | number | undefined): number {
+    if (!timeout) return 60000; // 60s default for process
+    if (typeof timeout === "number") return timeout;
+    const match = timeout.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m)?$/i);
+    if (!match) return 60000;
+    const [, num, unit] = match;
+    const multipliers: Record<string, number> = {
+      ms: 1, s: 1000, m: 60000,
+    };
+    return Math.floor(parseFloat(num) * (multipliers[unit?.toLowerCase() ?? "ms"] ?? 1));
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Session Primitives
+ *
+ * Stateful execution contexts for interactive use.
+ */
+
+// Kernel - Language-specific execution session
+export type {
+  KernelState,
+  KernelOptions,
+  KernelStats,
+} from "./kernel.js";
+
+export {
+  BaseKernel,
+  KernelManager,
+} from "./kernel.js";
+
+// Notebook - Multi-cell document execution
+export type {
+  NotebookOptions,
+  NotebookState,
+  NotebookEvents,
+} from "./notebook.js";
+
+export {
+  BaseNotebook,
+  createNotebook,
+} from "./notebook.js";
+
+// REPL - Interactive Read-Eval-Print-Loop
+export type {
+  REPLOptions,
+  REPLHistoryEntry,
+  REPLState,
+} from "./repl.js";
+
+export {
+  BaseREPL,
+  createREPL,
+} from "./repl.js";