feat(omnium): Add caplet vat implementation

eslint.config.mjs

@@ -270,6 +270,7 @@ const config = createConfig([
   {
     files: [
       'packages/*/src/**/vats/**/*',
+      'packages/*/src/**/caplets/**/*.js',
       'packages/*/test/**/vats/**/*',
       'packages/nodejs/test/workers/**/*',
       'packages/logger/test/workers/**/*',

packages/kernel-browser-runtime/src/kernel-worker/captp/captp.integration.test.ts

@@ -24,8 +24,12 @@ describe('CapTP Integration', () => {
     // Create mock kernel with method implementations
     mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue({
-        body: '#{"rootKref":"ko1"}',
-        slots: ['ko1'],
+        subclusterId: 'sc1',
+        bootstrapRootKref: 'ko1',
+        bootstrapResult: {
+          body: '#{"result":"ok"}',
+          slots: [],
+        },
       }),
       terminateSubcluster: vi.fn().mockResolvedValue(undefined),
       queueMessage: vi.fn().mockResolvedValue({
@@ -113,9 +117,11 @@ describe('CapTP Integration', () => {
 
       // Call launchSubcluster via E()
       const result = await E(kernel).launchSubcluster(config);
+
+      // The kernel facade now returns LaunchResult instead of CapData
       expect(result).toStrictEqual({
-        body: '#{"rootKref":"ko1"}',
-        slots: ['ko1'],
+        subclusterId: 'sc1',
+        rootKref: 'ko1',
       });
 
       expect(mockKernel.launchSubcluster).toHaveBeenCalledWith(config);

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-facade.test.ts

@@ -24,8 +24,8 @@ describe('makeKernelFacade', () => {
   beforeEach(() => {
     mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue({
-        body: '#{"status":"ok"}',
-        slots: [],
+        subclusterId: 'sc1',
+        bootstrapRootKref: 'ko1',
       }),
       terminateSubcluster: vi.fn().mockResolvedValue(undefined),
       queueMessage: vi.fn().mockResolvedValue({
@@ -60,16 +60,24 @@ describe('makeKernelFacade', () => {
       expect(mockKernel.launchSubcluster).toHaveBeenCalledTimes(1);
     });
 
-    it('returns result from kernel', async () => {
-      const expectedResult = { body: '#{"rootObject":"ko1"}', slots: ['ko1'] };
+    it('returns result with subclusterId and rootKref from kernel', async () => {
+      const kernelResult = {
+        subclusterId: 's1',
+        bootstrapRootKref: 'ko1',
+        bootstrapResult: { body: '#null', slots: [] },
+      };
       vi.mocked(mockKernel.launchSubcluster).mockResolvedValueOnce(
-        expectedResult,
+        kernelResult,
       );
 
       const config: ClusterConfig = makeClusterConfig();
 
       const result = await facade.launchSubcluster(config);
-      expect(result).toStrictEqual(expectedResult);
+
+      expect(result).toStrictEqual({
+        subclusterId: 's1',
+        rootKref: 'ko1',
+      });
     });
 
     it('propagates errors from kernel', async () => {

packages/kernel-browser-runtime/src/kernel-worker/captp/kernel-facade.ts

@@ -1,7 +1,7 @@
 import { makeDefaultExo } from '@metamask/kernel-utils/exo';
 import type { Kernel, ClusterConfig, KRef, VatId } from '@metamask/ocap-kernel';
 
-import type { KernelFacade } from '../../types.ts';
+import type { KernelFacade, LaunchResult } from '../../types.ts';
 
 export type { KernelFacade } from '../../types.ts';
 
@@ -15,8 +15,10 @@ export function makeKernelFacade(kernel: Kernel): KernelFacade {
   return makeDefaultExo('KernelFacade', {
     ping: async () => 'pong' as const,
 
-    launchSubcluster: async (config: ClusterConfig) => {
-      return kernel.launchSubcluster(config);
+    launchSubcluster: async (config: ClusterConfig): Promise<LaunchResult> => {
+      const { subclusterId, bootstrapRootKref } =
+        await kernel.launchSubcluster(config);
+      return { subclusterId, rootKref: bootstrapRootKref };
     },
 
     terminateSubcluster: async (subclusterId: string) => {
@@ -34,6 +36,12 @@ export function makeKernelFacade(kernel: Kernel): KernelFacade {
     pingVat: async (vatId: VatId) => {
       return kernel.pingVat(vatId);
     },
+
+    getVatRoot: async (krefString: string) => {
+      // Return wrapped kref for future CapTP marshalling to presence
+      // TODO: Enable custom CapTP marshalling tables to convert this to a presence
+      return { kref: krefString };
+    },
   });
 }
 harden(makeKernelFacade);

packages/kernel-browser-runtime/src/rpc-handlers/launch-subcluster.test.ts

@@ -3,9 +3,14 @@ import { describe, it, expect, vi } from 'vitest';
 import { launchSubclusterHandler } from './launch-subcluster.ts';
 
 describe('launchSubclusterHandler', () => {
-  it('should call kernel.launchSubcluster with the provided config', async () => {
+  it('calls kernel.launchSubcluster with the provided config', async () => {
+    const mockResult = {
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: { body: '#null', slots: [] },
+    };
     const mockKernel = {
-      launchSubcluster: vi.fn().mockResolvedValue(undefined),
+      launchSubcluster: vi.fn().mockResolvedValue(mockResult),
     };
     const params = {
       config: {
@@ -20,9 +25,14 @@ describe('launchSubclusterHandler', () => {
     expect(mockKernel.launchSubcluster).toHaveBeenCalledWith(params.config);
   });
 
-  it('should return null when kernel.launchSubcluster returns undefined', async () => {
+  it('returns the result from kernel.launchSubcluster', async () => {
+    const mockResult = {
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: { body: '#{"result":"ok"}', slots: [] },
+    };
     const mockKernel = {
-      launchSubcluster: vi.fn().mockResolvedValue(undefined),
+      launchSubcluster: vi.fn().mockResolvedValue(mockResult),
     };
     const params = {
       config: {
@@ -34,11 +44,15 @@ describe('launchSubclusterHandler', () => {
       { kernel: mockKernel },
       params,
     );
-    expect(result).toBeNull();
+    expect(result).toStrictEqual(mockResult);
   });
 
-  it('should return the result from kernel.launchSubcluster when not undefined', async () => {
-    const mockResult = { body: 'test', slots: [] };
+  it('converts undefined bootstrapResult to null for JSON compatibility', async () => {
+    const mockResult = {
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: undefined,
+    };
     const mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue(mockResult),
     };
@@ -52,6 +66,10 @@ describe('launchSubclusterHandler', () => {
       { kernel: mockKernel },
       params,
     );
-    expect(result).toBe(mockResult);
+    expect(result).toStrictEqual({
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: null,
+    });
   });
 });

packages/kernel-browser-runtime/src/rpc-handlers/launch-subcluster.ts

@@ -1,17 +1,38 @@
 import type { CapData } from '@endo/marshal';
 import type { MethodSpec, Handler } from '@metamask/kernel-rpc-methods';
 import type { Kernel, ClusterConfig, KRef } from '@metamask/ocap-kernel';
-import { CapDataStruct, ClusterConfigStruct } from '@metamask/ocap-kernel';
-import { object, nullable } from '@metamask/superstruct';
+import { ClusterConfigStruct, CapDataStruct } from '@metamask/ocap-kernel';
+import {
+  object,
+  string,
+  nullable,
+  type as structType,
+} from '@metamask/superstruct';
+
+/**
+ * JSON-compatible version of SubclusterLaunchResult for RPC.
+ * Uses null instead of undefined for JSON serialization.
+ */
+type LaunchSubclusterRpcResult = {
+  subclusterId: string;
+  bootstrapRootKref: string;
+  bootstrapResult: CapData<KRef> | null;
+};
+
+const LaunchSubclusterRpcResultStruct = structType({
+  subclusterId: string(),
+  bootstrapRootKref: string(),
+  bootstrapResult: nullable(CapDataStruct),
+});
 
 export const launchSubclusterSpec: MethodSpec<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<CapData<KRef> | null>
+  Promise<LaunchSubclusterRpcResult>
 > = {
   method: 'launchSubcluster',
   params: object({ config: ClusterConfigStruct }),
-  result: nullable(CapDataStruct),
+  result: LaunchSubclusterRpcResultStruct,
 };
 
 export type LaunchSubclusterHooks = {
@@ -21,16 +42,21 @@ export type LaunchSubclusterHooks = {
 export const launchSubclusterHandler: Handler<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<CapData<KRef> | null>,
+  Promise<LaunchSubclusterRpcResult>,
   LaunchSubclusterHooks
 > = {
   ...launchSubclusterSpec,
   hooks: { kernel: true },
   implementation: async (
     { kernel }: LaunchSubclusterHooks,
     params: { config: ClusterConfig },
-  ): Promise<CapData<KRef> | null> => {
+  ): Promise<LaunchSubclusterRpcResult> => {
     const result = await kernel.launchSubcluster(params.config);
-    return result ?? null;
+    // Convert undefined to null for JSON compatibility
+    return {
+      subclusterId: result.subclusterId,
+      bootstrapRootKref: result.bootstrapRootKref,
+      bootstrapResult: result.bootstrapResult ?? null,
+    };
   },
 };

packages/kernel-browser-runtime/src/types.ts

@@ -1,21 +1,32 @@
-import type { Kernel } from '@metamask/ocap-kernel';
+import type { Kernel, ClusterConfig } from '@metamask/ocap-kernel';
 import type { Json } from '@metamask/utils';
 
 /**
  * A CapTP message that can be sent over the wire.
  */
 export type CapTPMessage = Record<string, Json>;
 
+/**
+ * Result of launching a subcluster.
+ *
+ * The rootKref contains the kref string for the bootstrap vat's root object.
+ */
+export type LaunchResult = {
+  subclusterId: string;
+  rootKref: string;
+};
+
 /**
  * The kernel facade interface - methods exposed to userspace via CapTP.
  *
  * This is the remote presence type that the background receives from the kernel.
  */
 export type KernelFacade = {
   ping: () => Promise<'pong'>;
-  launchSubcluster: Kernel['launchSubcluster'];
+  launchSubcluster: (config: ClusterConfig) => Promise<LaunchResult>;
   terminateSubcluster: Kernel['terminateSubcluster'];
   queueMessage: Kernel['queueMessage'];
   getStatus: Kernel['getStatus'];
   pingVat: Kernel['pingVat'];
+  getVatRoot: (krefString: string) => Promise<unknown>;
 };

packages/kernel-test/src/liveslots.test.ts

@@ -67,14 +67,14 @@ describe('liveslots promise handling', () => {
     testName: string,
   ): Promise<unknown> {
     const bundleSpec = getBundleSpec(bundleName);
-    const bootstrapResultRaw = await kernel.launchSubcluster(
+    const { bootstrapResult } = await kernel.launchSubcluster(
       makeTestSubcluster(testName, bundleSpec),
     );
     await waitUntilQuiescent(1000);
-    if (bootstrapResultRaw === undefined) {
+    if (bootstrapResult === undefined) {
       throw Error(`this can't happen but eslint is stupid`);
     }
-    return kunser(bootstrapResultRaw);
+    return kunser(bootstrapResult);
   }
 
   it('promiseArg1: send promise parameter, resolve after send', async () => {

packages/kernel-test/src/persistence.test.ts

@@ -155,7 +155,7 @@ describe('persistent storage', { timeout: 20_000 }, () => {
       false,
       logger.logger.subLogger({ tags: ['test'] }),
     );
-    const bootstrapResult = await kernel1.launchSubcluster(testSubcluster);
+    const { bootstrapResult } = await kernel1.launchSubcluster(testSubcluster);
     expect(kunser(bootstrapResult as CapData<string>)).toBe(
       'Counter initialized with count: 1',
     );

packages/kernel-test/src/utils.ts

@@ -37,12 +37,12 @@ export async function runTestVats(
   kernel: Kernel,
   config: ClusterConfig,
 ): Promise<unknown> {
-  const bootstrapResultRaw = await kernel.launchSubcluster(config);
+  const { bootstrapResult } = await kernel.launchSubcluster(config);
   await waitUntilQuiescent();
-  if (bootstrapResultRaw === undefined) {
+  if (bootstrapResult === undefined) {
     throw Error(`this can't happen but eslint is stupid`);
   }
-  return kunser(bootstrapResultRaw);
+  return kunser(bootstrapResult);
 }
 
 /**

packages/nodejs/package.json

@@ -52,7 +52,6 @@
   },
   "dependencies": {
     "@endo/eventual-send": "^1.3.4",
-    "@endo/marshal": "^1.8.0",
     "@endo/promise-kit": "^1.1.13",
     "@libp2p/interface": "2.11.0",
     "@libp2p/webrtc": "5.2.24",

packages/nodejs/test/helpers/kernel.ts

@@ -42,10 +42,7 @@ export async function runTestVats(
   kernel: Kernel,
   config: ClusterConfig,
 ): Promise<unknown> {
-  const bootstrapResultRaw = await kernel.launchSubcluster(config);
+  const { bootstrapResult } = await kernel.launchSubcluster(config);
   await waitUntilQuiescent();
-  if (bootstrapResultRaw === undefined) {
-    throw Error(`this can't happen but eslint is stupid`);
-  }
-  return kunser(bootstrapResultRaw);
+  return bootstrapResult && kunser(bootstrapResult);
 }

packages/nodejs/test/helpers/remote-comms.ts

@@ -1,5 +1,5 @@
-import type { CapData } from '@endo/marshal';
 import type { KernelDatabase } from '@metamask/kernel-store';
+import { stringify } from '@metamask/kernel-utils';
 import { Kernel, kunser, makeKernelStore } from '@metamask/ocap-kernel';
 import type { ClusterConfig, KRef } from '@metamask/ocap-kernel';
 
@@ -58,8 +58,13 @@ export async function launchVatAndGetURL(
   kernel: Kernel,
   config: ClusterConfig,
 ): Promise<string> {
-  const result = await kernel.launchSubcluster(config);
-  return kunser(result as CapData<KRef>) as string;
+  const { bootstrapResult } = await kernel.launchSubcluster(config);
+  if (!bootstrapResult) {
+    throw new Error(
+      `No bootstrap result for vat "${config.bootstrap}" with config ${stringify(config)}`,
+    );
+  }
+  return kunser(bootstrapResult) as string;
 }
 
 /**

packages/ocap-kernel/src/Kernel.test.ts

@@ -286,7 +286,11 @@ describe('Kernel', () => {
       );
       const config = makeMockClusterConfig();
       const result = await kernel.launchSubcluster(config);
-      expect(result).toStrictEqual({ body: '{"result":"ok"}', slots: [] });
+      expect(result).toStrictEqual({
+        subclusterId: 's1',
+        bootstrapResult: { body: '{"result":"ok"}', slots: [] },
+        bootstrapRootKref: expect.stringMatching(/^ko\d+$/u),
+      });
     });
   });