@ebowwa/sandbox 0.1.1

package/src/session/kernel.ts

@@ -0,0 +1,553 @@
+/**
+ * Kernel Primitive
+ *
+ * Language-specific execution session with state persistence.
+ * Provides REPL-like interactive execution for a single language.
+ */
+
+import type {
+  Language,
+  Kernel,
+  ExecutionResult,
+  ExecutionOptions,
+  CompletionResult,
+  InspectResult,
+  Permissions,
+  Limits,
+  Cell,
+} from "../core/types.js";
+import type { ICompiler, CompileResult } from "../core/compiler.js";
+import type { IRuntime, ExecutionRequest } from "../core/runtime.js";
+import { PermissionChecker, createPermissions } from "../core/permissions.js";
+import { LimitsParser, LimitsEnforcer, DEFAULT_LIMITS } from "../core/limits.js";
+import { v4 as uuid } from "uuid";
+
+/**
+ * Kernel state
+ */
+export type KernelState =
+  | "starting"
+  | "ready"
+  | "busy"
+  | "error"
+  | "shutting_down"
+  | "dead";
+
+/**
+ * Kernel options
+ */
+export interface KernelOptions {
+  /** Kernel ID */
+  id?: string;
+  /** Display name */
+  displayName?: string;
+  /** Language */
+  language: Language;
+  /** Compiler for this language */
+  compiler: ICompiler;
+  /** Runtime for execution */
+  runtime: IRuntime;
+  /** Permissions */
+  permissions?: Permissions;
+  /** Resource limits */
+  limits?: Limits;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Working directory */
+  cwd?: string;
+}
+
+/**
+ * Kernel statistics
+ */
+export interface KernelStats {
+  /** Total executions */
+  executions: number;
+  /** Successful executions */
+  successes: number;
+  /** Failed executions */
+  failures: number;
+  /** Total execution time (ms) */
+  totalTime: number;
+  /** Average execution time (ms) */
+  avgTime: number;
+  /** Memory high water mark */
+  memoryHighWater: number;
+  /** Last execution time */
+  lastExecution?: Date;
+}
+
+/**
+ * Base Kernel Implementation
+ *
+ * Provides core kernel functionality with state management.
+ */
+export class BaseKernel implements Kernel {
+  readonly language: Language;
+  readonly displayName: string;
+
+  private id: string;
+  private state: KernelState = "starting";
+  private kernelState = new Map<string, unknown>();
+  private exports = new Map<string, unknown>();
+  private compiler: ICompiler;
+  private runtime: IRuntime;
+  private permissions: Permissions;
+  private limits: Limits;
+  private env: Record<string, string>;
+  private cwd?: string;
+  private stats: KernelStats = {
+    executions: 0,
+    successes: 0,
+    failures: 0,
+    totalTime: 0,
+    avgTime: 0,
+    memoryHighWater: 0,
+  };
+  private permissionChecker: PermissionChecker;
+
+  constructor(options: KernelOptions) {
+    this.id = options.id ?? uuid();
+    this.language = options.language;
+    this.displayName = options.displayName ?? `${options.language} kernel`;
+    this.compiler = options.compiler;
+    this.runtime = options.runtime;
+    this.permissions = options.permissions ?? {};
+    this.limits = options.limits ?? {};
+    this.env = options.env ?? {};
+    this.cwd = options.cwd;
+    this.permissionChecker = new PermissionChecker(this.permissions);
+  }
+
+  /**
+   * Get kernel ID
+   */
+  getId(): string {
+    return this.id;
+  }
+
+  /**
+   * Get current execution state
+   */
+  getExecutionState(): KernelState {
+    return this.state;
+  }
+
+  /**
+   * Get kernel state (variables)
+   */
+  getState(): Map<string, unknown> {
+    return new Map(this.kernelState);
+  }
+
+  /**
+   * Get exports
+   */
+  getExports(): Map<string, unknown> {
+    return new Map(this.exports);
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): KernelStats {
+    return { ...this.stats };
+  }
+
+  /**
+   * Start the kernel
+   */
+  async start(): Promise<void> {
+    this.state = "starting";
+
+    try {
+      // Check if compiler is available
+      if (!(await this.compiler.isAvailable())) {
+        throw new Error(`Compiler for ${this.language} is not available`);
+      }
+
+      // Initialize runtime
+      await this.runtime.init();
+
+      // Check if runtime is available
+      if (!(await this.runtime.isAvailable())) {
+        throw new Error(`Runtime ${this.runtime.name} is not available`);
+      }
+
+      this.state = "ready";
+    } catch (error) {
+      this.state = "error";
+      throw error;
+    }
+  }
+
+  /**
+   * Check if kernel is running
+   */
+  isRunning(): boolean {
+    return this.state === "ready" || this.state === "busy";
+  }
+
+  /**
+   * Get display name
+   */
+  getDisplayName(): string {
+    return this.displayName;
+  }
+
+  /**
+   * Get language
+   */
+  getLanguage(): Language {
+    return this.language;
+  }
+
+  /**
+   * Execute code
+   */
+  async execute(
+    code: string,
+    options?: ExecutionOptions
+  ): Promise<ExecutionResult> {
+    if (this.state !== "ready" && this.state !== "busy") {
+      return this.createErrorResult(
+        `Kernel is not ready (state: ${this.state})`,
+        "runtime"
+      );
+    }
+
+    this.state = "busy";
+    const startTime = Date.now();
+
+    try {
+      // Parse limits
+      const parsedLimits = LimitsParser.parse(this.limits);
+      const enforcer = new LimitsEnforcer(parsedLimits);
+      enforcer.start();
+
+      // Check for abort signal
+      if (options?.signal?.aborted) {
+        return this.createErrorResult("Execution cancelled", "cancel");
+      }
+
+      // Compile
+      const compiled = await this.compiler.compile(
+        code,
+        this.permissions,
+        this.limits,
+        { optimize: true }
+      );
+
+      // Create execution request
+      const request: ExecutionRequest = {
+        wasm: compiled,
+        entrypoint: options?.entrypoint,
+        args: options?.args,
+        input: options?.input,
+        state: this.kernelState,
+      };
+
+      // Execute
+      const result = await this.runtime.execute(request, {
+        permissions: this.permissions,
+        limits: this.limits,
+        env: this.env,
+        cwd: this.cwd,
+        signal: options?.signal,
+      });
+
+      // Update state if successful
+      if (result.success && result.state) {
+        for (const [key, value] of result.state) {
+          this.kernelState.set(key, value);
+        }
+      }
+
+      // Update exports
+      if (result.exports) {
+        for (const [key, value] of result.exports) {
+          this.exports.set(key, value);
+        }
+      }
+
+      // Update stats
+      this.updateStats(result, Date.now() - startTime);
+
+      this.state = "ready";
+      return result;
+    } catch (error) {
+      this.state = "ready";
+      const result = this.createErrorResult(
+        error instanceof Error ? error.message : String(error),
+        "runtime"
+      );
+      this.updateStats(result, Date.now() - startTime);
+      return result;
+    }
+  }
+
+  /**
+   * Complete code at position (autocomplete)
+   */
+  async complete(
+    code: string,
+    position: number
+  ): Promise<CompletionResult> {
+    // Basic implementation - override in language-specific kernels
+    const beforeCursor = code.slice(0, position);
+    const match = beforeCursor.match(/(\w+)$/);
+    const prefix = match ? match[1] : "";
+
+    // Get completions from state
+    const matches: string[] = [];
+
+    for (const key of this.kernelState.keys()) {
+      if (key.startsWith(prefix)) {
+        matches.push(key);
+      }
+    }
+
+    for (const key of this.exports.keys()) {
+      if (key.startsWith(prefix)) {
+        matches.push(key);
+      }
+    }
+
+    return {
+      matches,
+      cursorStart: position - prefix.length,
+      cursorEnd: position,
+    };
+  }
+
+  /**
+   * Inspect object at position
+   */
+  async inspect(
+    code: string,
+    position: number
+  ): Promise<InspectResult> {
+    // Basic implementation - override in language-specific kernels
+    const beforeCursor = code.slice(0, position);
+    const match = beforeCursor.match(/(\w+)$/);
+    const name = match ? match[1] : "";
+
+    if (!name) {
+      return { found: false };
+    }
+
+    const value = this.kernelState.get(name) ?? this.exports.get(name);
+
+    if (value === undefined) {
+      return { found: false };
+    }
+
+    return {
+      found: true,
+      details: {
+        type: typeof value,
+        documentation: undefined,
+        signature: undefined,
+      },
+    };
+  }
+
+  /**
+   * Restart kernel (clear state)
+   */
+  async restart(): Promise<void> {
+    this.kernelState.clear();
+    this.exports.clear();
+    this.state = "ready";
+
+    // Reset stats
+    this.stats = {
+      executions: 0,
+      successes: 0,
+      failures: 0,
+      totalTime: 0,
+      avgTime: 0,
+      memoryHighWater: 0,
+    };
+  }
+
+  /**
+   * Shutdown kernel
+   */
+  async shutdown(): Promise<void> {
+    this.state = "shutting_down";
+
+    try {
+      await this.runtime.terminate();
+    } catch {
+      // Ignore errors during shutdown
+    }
+
+    this.kernelState.clear();
+    this.exports.clear();
+    this.state = "dead";
+  }
+
+  /**
+   * Interrupt current execution
+   */
+  interrupt(): void {
+    // Override in implementations that support interruption
+  }
+
+  /**
+   * Set environment variable
+   */
+  setEnv(key: string, value: string): void {
+    this.env[key] = value;
+  }
+
+  /**
+   * Get environment variable
+   */
+  getEnv(key: string): string | undefined {
+    return this.env[key];
+  }
+
+  /**
+   * Update permissions
+   */
+  setPermissions(permissions: Permissions): void {
+    this.permissions = permissions;
+    this.permissionChecker = new PermissionChecker(permissions);
+  }
+
+  /**
+   * Update limits
+   */
+  setLimits(limits: Limits): void {
+    this.limits = limits;
+  }
+
+  /**
+   * Create error result
+   */
+  private createErrorResult(
+    message: string,
+    type: "compile" | "runtime" | "permission" | "limit" | "timeout" | "cancel"
+  ): ExecutionResult {
+    return {
+      success: false,
+      error: { message, type },
+      metrics: {
+        duration: 0,
+        memoryUsed: 0,
+      },
+      output: { stdout: [], stderr: [], displays: [] },
+    };
+  }
+
+  /**
+   * Update statistics
+   */
+  private updateStats(result: ExecutionResult, duration: number): void {
+    this.stats.executions++;
+    this.stats.totalTime += duration;
+    this.stats.avgTime = this.stats.totalTime / this.stats.executions;
+    this.stats.lastExecution = new Date();
+
+    if (result.success) {
+      this.stats.successes++;
+    } else {
+      this.stats.failures++;
+    }
+
+    const memoryUsed = result.metrics.memoryUsed;
+    if (memoryUsed > this.stats.memoryHighWater) {
+      this.stats.memoryHighWater = memoryUsed;
+    }
+  }
+}
+
+/**
+ * Kernel Manager
+ *
+ * Manages multiple kernels across languages.
+ */
+export class KernelManager {
+  private kernels = new Map<string, BaseKernel>();
+  private languageKernels = new Map<Language, Set<string>>();
+
+  /**
+   * Create and register a kernel
+   */
+  async createKernel(options: KernelOptions): Promise<BaseKernel> {
+    const kernel = new BaseKernel(options);
+    await kernel.start();
+
+    this.kernels.set(kernel.getId(), kernel);
+
+    if (!this.languageKernels.has(options.language)) {
+      this.languageKernels.set(options.language, new Set());
+    }
+    this.languageKernels.get(options.language)!.add(kernel.getId());
+
+    return kernel;
+  }
+
+  /**
+   * Get kernel by ID
+   */
+  getKernel(id: string): BaseKernel | undefined {
+    return this.kernels.get(id);
+  }
+
+  /**
+   * Get kernels by language
+   */
+  getKernelsByLanguage(language: Language): BaseKernel[] {
+    const ids = this.languageKernels.get(language);
+    if (!ids) return [];
+
+    return Array.from(ids)
+      .map(id => this.kernels.get(id))
+      .filter((k): k is BaseKernel => k !== undefined);
+  }
+
+  /**
+   * Get all kernels
+   */
+  getAllKernels(): BaseKernel[] {
+    return Array.from(this.kernels.values());
+  }
+
+  /**
+   * Shutdown a kernel
+   */
+  async shutdownKernel(id: string): Promise<void> {
+    const kernel = this.kernels.get(id);
+    if (!kernel) return;
+
+    await kernel.shutdown();
+
+    // Remove from language index
+    const langSet = this.languageKernels.get(kernel.language);
+    if (langSet) {
+      langSet.delete(id);
+    }
+
+    this.kernels.delete(id);
+  }
+
+  /**
+   * Shutdown all kernels
+   */
+  async shutdownAll(): Promise<void> {
+    const shutdowns = Array.from(this.kernels.keys()).map(id =>
+      this.shutdownKernel(id)
+    );
+    await Promise.all(shutdowns);
+  }
+
+  /**
+   * Get kernel count
+   */
+  get count(): number {
+    return this.kernels.size;
+  }
+}