feat(ocap-kernel): add evaluate RPC method for vat REPL

Add an `evaluate` RPC method to VatSupervisor that evaluates code in a vat's isolated compartment, enabling REPL functionality while maintaining security isolation from the supervisor.

Key changes:
- New evaluate.ts RPC spec and handler
- VatSupervisor creates a separate eval compartment with vat exports in scope
- VatHandle.evaluate() method for kernel-side API
- Result serialization for JSON-RPC transport (handles functions, symbols, bigints)
- Errors return as { success: false, error } without crashing the vat

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: rekmarks

packages/ocap-kernel/src/rpc/vat/evaluate.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { evaluateHandler } from './evaluate.ts';
+import type { HandleEvaluate } from './evaluate.ts';
+
+describe('evaluateHandler', () => {
+  it('calls handleEvaluate with the code parameter', () => {
+    const handleEvaluate = vi.fn(() => ({
+      success: true as const,
+      value: 42,
+    }));
+    const result = evaluateHandler.implementation(
+      { handleEvaluate },
+      { code: '1 + 1' },
+    );
+    expect(result).toStrictEqual({ success: true, value: 42 });
+    expect(handleEvaluate).toHaveBeenCalledWith('1 + 1');
+  });
+
+  it('returns success result with value', () => {
+    const handleEvaluate: HandleEvaluate = () => ({
+      success: true,
+      value: { foo: 'bar' },
+    });
+    const result = evaluateHandler.implementation(
+      { handleEvaluate },
+      { code: 'test' },
+    );
+    expect(result).toStrictEqual({ success: true, value: { foo: 'bar' } });
+  });
+
+  it('returns success result without value for undefined', () => {
+    const handleEvaluate: HandleEvaluate = () => ({
+      success: true,
+    });
+    const result = evaluateHandler.implementation(
+      { handleEvaluate },
+      { code: 'undefined' },
+    );
+    expect(result).toStrictEqual({ success: true });
+  });
+
+  it('returns error result for failures', () => {
+    const handleEvaluate: HandleEvaluate = () => ({
+      success: false,
+      error: 'SyntaxError: Unexpected token',
+    });
+    const result = evaluateHandler.implementation(
+      { handleEvaluate },
+      { code: 'invalid{code' },
+    );
+    expect(result).toStrictEqual({
+      success: false,
+      error: 'SyntaxError: Unexpected token',
+    });
+  });
+});

packages/ocap-kernel/src/rpc/vat/evaluate.ts

@@ -0,0 +1,67 @@
+import type { Handler, MethodSpec } from '@metamask/kernel-rpc-methods';
+import {
+  object,
+  string,
+  literal,
+  union,
+  exactOptional,
+} from '@metamask/superstruct';
+import type { Infer } from '@metamask/superstruct';
+import { UnsafeJsonStruct } from '@metamask/utils';
+import type { Json } from '@metamask/utils';
+
+const EvaluateParamsStruct = object({
+  code: string(),
+});
+
+type EvaluateParams = Infer<typeof EvaluateParamsStruct>;
+
+const EvaluateSuccessResultStruct = object({
+  success: literal(true),
+  value: exactOptional(UnsafeJsonStruct),
+});
+
+const EvaluateErrorResultStruct = object({
+  success: literal(false),
+  error: string(),
+});
+
+const EvaluateResultStruct = union([
+  EvaluateSuccessResultStruct,
+  EvaluateErrorResultStruct,
+]);
+
+export type EvaluateResult =
+  | { success: true; value?: Json }
+  | { success: false; error: string };
+
+export type EvaluateSpec = MethodSpec<
+  'evaluate',
+  EvaluateParams,
+  EvaluateResult
+>;
+
+export const evaluateSpec = {
+  method: 'evaluate',
+  params: EvaluateParamsStruct,
+  result: EvaluateResultStruct,
+} as const as EvaluateSpec;
+
+export type HandleEvaluate = (code: string) => EvaluateResult;
+
+type EvaluateHooks = {
+  handleEvaluate: HandleEvaluate;
+};
+
+export type EvaluateHandler = Handler<
+  'evaluate',
+  EvaluateParams,
+  EvaluateResult,
+  EvaluateHooks
+>;
+
+export const evaluateHandler: EvaluateHandler = {
+  ...evaluateSpec,
+  hooks: { handleEvaluate: true },
+  implementation: ({ handleEvaluate }, params) => handleEvaluate(params.code),
+} as const;

packages/ocap-kernel/src/rpc/vat/index.ts

@@ -2,6 +2,12 @@ import type { Infer } from '@metamask/superstruct';
 
 import { deliverSpec, deliverHandler } from './deliver.ts';
 import type { DeliverSpec, DeliverHandler } from './deliver.ts';
+import { evaluateSpec, evaluateHandler } from './evaluate.ts';
+import type {
+  EvaluateSpec,
+  EvaluateHandler,
+  EvaluateResult,
+} from './evaluate.ts';
 import { initVatSpec, initVatHandler } from './initVat.ts';
 import type { InitVatSpec, InitVatHandler } from './initVat.ts';
 import { pingSpec, pingHandler } from './ping.ts';
@@ -12,20 +18,24 @@ import type { PingSpec, PingHandler } from './ping.ts';
 
 export const vatHandlers = {
   deliver: deliverHandler,
+  evaluate: evaluateHandler,
   initVat: initVatHandler,
   ping: pingHandler,
 } as {
   deliver: DeliverHandler;
+  evaluate: EvaluateHandler;
   initVat: InitVatHandler;
   ping: PingHandler;
 };
 
 export const vatMethodSpecs = {
   deliver: deliverSpec,
+  evaluate: evaluateSpec,
   initVat: initVatSpec,
   ping: pingSpec,
 } as {
   deliver: DeliverSpec;
+  evaluate: EvaluateSpec;
   initVat: InitVatSpec;
   ping: PingSpec;
 };
@@ -35,3 +45,5 @@ type Handlers = (typeof vatHandlers)[keyof typeof vatHandlers];
 export type VatMethod = Handlers['method'];
 
 export type PingVatResult = Infer<PingSpec['result']>;
+
+export type { EvaluateResult };

packages/ocap-kernel/src/vats/VatHandle.ts

@@ -18,7 +18,7 @@ import type { JsonRpcNotification, JsonRpcResponse } from '@metamask/utils';
 import type { KernelQueue } from '../KernelQueue.ts';
 import { kser, makeError } from '../liveslots/kernel-marshal.ts';
 import { vatMethodSpecs, vatSyscallHandlers } from '../rpc/index.ts';
-import type { PingVatResult, VatMethod } from '../rpc/index.ts';
+import type { EvaluateResult, PingVatResult, VatMethod } from '../rpc/index.ts';
 import type { KernelStore } from '../store/index.ts';
 import type {
   Message,
@@ -184,6 +184,19 @@ export class VatHandle implements EndpointHandle {
     });
   }
 
+  /**
+   * Evaluate code in the vat's REPL compartment.
+   *
+   * @param code - The code to evaluate.
+   * @returns A promise that resolves to the evaluation result.
+   */
+  async evaluate(code: string): Promise<EvaluateResult> {
+    return await this.sendVatCommand({
+      method: 'evaluate',
+      params: { code },
+    });
+  }
+
   /**
    * Handle a message from the vat.
    *

packages/ocap-kernel/src/vats/VatSupervisor.test.ts

@@ -124,6 +124,26 @@ describe('VatSupervisor', () => {
         }),
       );
     });
+
+    it('handles "evaluate" requests before vat initialization', async () => {
+      const dispatch = vi.fn();
+      const { stream } = await makeVatSupervisor({ dispatch });
+
+      await stream.receiveInput({
+        id: 'v0:1',
+        method: 'evaluate',
+        params: { code: '1 + 1' },
+        jsonrpc: '2.0',
+      });
+      await delay(10);
+
+      expect(dispatch).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: 'v0:1',
+          result: { success: false, error: 'Vat not initialized' },
+        }),
+      );
+    });
   });
 
   describe('terminate', () => {

packages/ocap-kernel/src/vats/VatSupervisor.ts

@@ -25,6 +25,7 @@ import {
   isJsonRpcRequest,
   isJsonRpcResponse,
 } from '@metamask/utils';
+import type { Json } from '@metamask/utils';
 import type { PlatformFactory } from '@ocap/kernel-platforms';
 
 import { loadBundle } from './bundle-loader.ts';
@@ -37,6 +38,7 @@ import type {
   GCTools,
 } from '../liveslots/types.ts';
 import { vatSyscallMethodSpecs, vatHandlers } from '../rpc/index.ts';
+import type { EvaluateResult } from '../rpc/index.ts';
 import { makeVatKVStore } from '../store/vat-kv-store.ts';
 import type { VatConfig, VatDeliveryResult, VatId } from '../types.ts';
 import { isVatConfig, coerceVatSyscallObject } from '../types.ts';
@@ -105,6 +107,9 @@ export class VatSupervisor {
   /** Options to pass to the makePlatform function. */
   readonly #platformOptions: Record<string, unknown>;
 
+  /** Compartment for REPL evaluation with vat exports in scope. */
+  #evalCompartment: { evaluate: (code: string) => unknown } | null = null;
+
   /**
    * Construct a new VatSupervisor instance.
    *
@@ -151,6 +156,7 @@ export class VatSupervisor {
     this.#rpcServer = new RpcService(vatHandlers, {
       initVat: this.#initVat.bind(this),
       handleDelivery: this.#deliver.bind(this),
+      handleEvaluate: this.#evaluate.bind(this),
     });
 
     Promise.all([
@@ -250,6 +256,81 @@ export class VatSupervisor {
     return [this.#vatKVStore!.checkpoint(), deliveryError];
   }
 
+  /**
+   * Evaluate code in the vat's REPL compartment.
+   *
+   * @param code - The code to evaluate.
+   * @returns The result of the evaluation.
+   */
+  #evaluate(code: string): EvaluateResult {
+    if (!this.#evalCompartment) {
+      return { success: false, error: 'Vat not initialized' };
+    }
+    try {
+      const result = this.#evalCompartment.evaluate(code);
+      const serialized = this.#serializeResult(result);
+      if (serialized === undefined) {
+        return { success: true };
+      }
+      return { success: true, value: serialized };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Serialize a value for JSON-RPC transport.
+   * Non-serializable values (functions, symbols, etc.) are converted to string representation.
+   *
+   * @param value - The value to serialize.
+   * @returns A JSON-serializable value.
+   */
+  #serializeResult(value: unknown): Json | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    if (value === null) {
+      return null;
+    }
+    const type = typeof value;
+    if (type === 'string') {
+      return value as string;
+    }
+    if (type === 'number') {
+      return value as number;
+    }
+    if (type === 'boolean') {
+      return value as boolean;
+    }
+    if (type === 'bigint') {
+      return `${String(value as bigint)}n`;
+    }
+    if (type === 'symbol') {
+      return (value as symbol).toString();
+    }
+    if (type === 'function') {
+      return `[Function: ${(value as { name?: string }).name ?? 'anonymous'}]`;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => this.#serializeResult(item) ?? null) as Json[];
+    }
+    if (type === 'object') {
+      // Handle objects - try to serialize their properties
+      const result: Record<string, Json> = {};
+      for (const key of Object.keys(value as object)) {
+        result[key] =
+          this.#serializeResult((value as Record<string, unknown>)[key]) ??
+          null;
+      }
+      return result;
+    }
+    // Fallback for any other types - unlikely to reach here
+    return `[${type}]`;
+  }
+
   /**
    * Initialize the vat by loading its user code bundle and creating a liveslots
    * instance to manage it.
@@ -357,6 +438,14 @@ export class VatSupervisor {
         endowments,
         inescapableGlobalProperties,
       });
+
+      // Create a separate compartment for REPL evaluation.
+      // Vat exports become endowments, so they're directly in scope.
+      this.#evalCompartment = new Compartment({
+        harden: globalThis.harden,
+        ...vatNS,
+      });
+
       return vatNS;
     };