feat(omnium): Add loadCaplet method and fix vat bootstrap kref

- Add omnium.loadCaplet(id) to dynamically fetch caplet manifest and bundle
- Fix vatPowers.logger missing in browser vats (iframe.ts)
- Fix SubclusterLaunchResult to return bootstrapRootKref directly
  instead of trying to extract it from bootstrap() return slots

The bootstrapRootKref is the kref of the vat root object, which is
already known when the vat launches. Previously we incorrectly tried
to get it from the slots of the bootstrap() method return value.

Next step: Wire up CapTP marshalling so E(root).echo() works with
the caplet root presence.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: rekmarks

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

@@ -25,8 +25,12 @@ describe('CapTP Integration', () => {
     // Create mock kernel with method implementations
     mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue({
-        body: '#{"subclusterId":"sc1"}',
-        slots: ['ko1'],
+        subclusterId: 'sc1',
+        bootstrapRootKref: 'ko1',
+        bootstrapResult: {
+          body: '#{"result":"ok"}',
+          slots: [],
+        },
       }),
       terminateSubcluster: vi.fn().mockResolvedValue(undefined),
       queueMessage: vi.fn().mockResolvedValue({

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

@@ -16,32 +16,9 @@ export function makeKernelFacade(kernel: Kernel): KernelFacade {
     ping: async () => 'pong' as const,
 
     launchSubcluster: async (config: ClusterConfig): Promise<LaunchResult> => {
-      const capData = await kernel.launchSubcluster(config);
-
-      // A subcluster always has a bootstrap vat with a root object
-      if (!capData) {
-        throw new Error('launchSubcluster: expected capData with root kref');
-      }
-
-      // Parse the CapData body (format: "#..." where # prefix indicates JSON)
-      const bodyJson = capData.body.startsWith('#')
-        ? capData.body.slice(1)
-        : capData.body;
-      const body = JSON.parse(bodyJson) as { subclusterId?: string };
-      if (!body.subclusterId) {
-        throw new Error('launchSubcluster: expected subclusterId in body');
-      }
-
-      // Extract root kref from slots (first slot is bootstrap vat's root object)
-      const rootKref = capData.slots[0];
-      if (!rootKref) {
-        throw new Error('launchSubcluster: expected root kref in slots');
-      }
-
-      return {
-        subclusterId: body.subclusterId,
-        rootKref,
-      };
+      const { subclusterId, bootstrapRootKref } =
+        await kernel.launchSubcluster(config);
+      return { subclusterId, rootKref: bootstrapRootKref };
     },
 
     terminateSubcluster: async (subclusterId: string) => {

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,25 +25,12 @@ describe('launchSubclusterHandler', () => {
     expect(mockKernel.launchSubcluster).toHaveBeenCalledWith(params.config);
   });
 
-  it('should return null when kernel.launchSubcluster returns undefined', async () => {
-    const mockKernel = {
-      launchSubcluster: vi.fn().mockResolvedValue(undefined),
+  it('returns the result from kernel.launchSubcluster', async () => {
+    const mockResult = {
+      subclusterId: 's1',
+      bootstrapRootKref: 'ko1',
+      bootstrapResult: { body: '#{"result":"ok"}', slots: [] },
     };
-    const params = {
-      config: {
-        bootstrap: 'test-bootstrap',
-        vats: {},
-      },
-    };
-    const result = await launchSubclusterHandler.implementation(
-      { kernel: mockKernel },
-      params,
-    );
-    expect(result).toBeNull();
-  });
-
-  it('should return the result from kernel.launchSubcluster when not undefined', async () => {
-    const mockResult = { body: 'test', slots: [] };
     const mockKernel = {
       launchSubcluster: vi.fn().mockResolvedValue(mockResult),
     };

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

@@ -1,17 +1,31 @@
-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 type {
+  Kernel,
+  ClusterConfig,
+  SubclusterLaunchResult,
+} from '@metamask/ocap-kernel';
+import { ClusterConfigStruct, CapDataStruct } from '@metamask/ocap-kernel';
+import {
+  object,
+  string,
+  optional,
+  type as structType,
+} from '@metamask/superstruct';
+
+const SubclusterLaunchResultStruct = structType({
+  subclusterId: string(),
+  bootstrapRootKref: string(),
+  bootstrapResult: optional(CapDataStruct),
+});
 
 export const launchSubclusterSpec: MethodSpec<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<CapData<KRef> | null>
+  Promise<SubclusterLaunchResult>
 > = {
   method: 'launchSubcluster',
   params: object({ config: ClusterConfigStruct }),
-  result: nullable(CapDataStruct),
+  result: SubclusterLaunchResultStruct,
 };
 
 export type LaunchSubclusterHooks = {
@@ -21,16 +35,15 @@ export type LaunchSubclusterHooks = {
 export const launchSubclusterHandler: Handler<
   'launchSubcluster',
   { config: ClusterConfig },
-  Promise<CapData<KRef> | null>,
+  Promise<SubclusterLaunchResult>,
   LaunchSubclusterHooks
 > = {
   ...launchSubclusterSpec,
   hooks: { kernel: true },
   implementation: async (
     { kernel }: LaunchSubclusterHooks,
     params: { config: ClusterConfig },
-  ): Promise<CapData<KRef> | null> => {
-    const result = await kernel.launchSubcluster(params.config);
-    return result ?? null;
+  ): Promise<SubclusterLaunchResult> => {
+    return kernel.launchSubcluster(params.config);
   },
 };

packages/kernel-browser-runtime/src/vat/iframe.ts

@@ -28,13 +28,15 @@ async function main(): Promise<void> {
 
   const urlParams = new URLSearchParams(window.location.search);
   const vatId = urlParams.get('vatId') ?? 'unknown';
+  const vatLogger = logger.subLogger(vatId);
 
   // eslint-disable-next-line no-new
   new VatSupervisor({
     id: vatId,
     kernelStream,
-    logger: logger.subLogger(vatId),
+    logger: vatLogger,
     makePlatform,
+    vatPowers: { logger: vatLogger },
   });
 
   logger.info('VatSupervisor initialized with vatId:', vatId);

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/ocap-kernel/src/Kernel.test.ts

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

packages/ocap-kernel/src/Kernel.ts

@@ -21,6 +21,7 @@ import type {
   VatConfig,
   KernelStatus,
   Subcluster,
+  SubclusterLaunchResult,
   EndpointHandle,
 } from './types.ts';
 import { isVatId, isRemoteId } from './types.ts';
@@ -293,11 +294,12 @@ export class Kernel {
    * Launches a sub-cluster of vats.
    *
    * @param config - Configuration object for sub-cluster.
-   * @returns a promise for the (CapData encoded) result of the bootstrap message.
+   * @returns A promise for the subcluster ID and the (CapData encoded) result
+   * of the bootstrap message.
    */
   async launchSubcluster(
     config: ClusterConfig,
-  ): Promise<CapData<KRef> | undefined> {
+  ): Promise<SubclusterLaunchResult> {
     return this.#subclusterManager.launchSubcluster(config);
   }