feat(extension): Add CapTP E() support for calling vat methods

- Import and initialize makeBackgroundKref to enable E() calls on vat objects
- Expose captp.resolveKref and captp.krefOf on globalThis for console access
- Refactor startDefaultSubcluster to return the bootstrap vat rootKref
- Add greetBootstrapVat function that automatically calls hello() on the
  bootstrap vat after subcluster launch on startup
- Update global.d.ts with captp type declaration for IDE support

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

Author: rekmarks

packages/extension/src/background.ts

@@ -1,6 +1,7 @@
 import { E } from '@endo/eventual-send';
 import {
   makeBackgroundCapTP,
+  makeBackgroundKref,
   makeCapTPNotification,
   isCapTPNotification,
   getCapTPMessage,
@@ -116,6 +117,10 @@ async function main(): Promise<void> {
     logger.info(result);
   };
 
+  // Create background kref system for E() calls on vat objects
+  const bgKref = makeBackgroundKref({ kernelFacade: kernelP });
+  Object.assign(globalThis.captp, bgKref);
+
   // Handle incoming CapTP messages from the kernel
   const drainPromise = offscreenStream.drain((message) => {
     if (isCapTPNotification(message)) {
@@ -128,7 +133,10 @@ async function main(): Promise<void> {
   drainPromise.catch(logger.error);
 
   await ping(); // Wait for the kernel to be ready
-  await startDefaultSubcluster(kernelP);
+  const rootKref = await startDefaultSubcluster(kernelP);
+  if (rootKref) {
+    await greetBootstrapVat(rootKref);
+  }
 
   try {
     await drainPromise;
@@ -145,18 +153,33 @@ async function main(): Promise<void> {
  * Idempotently starts the default subcluster.
  *
  * @param kernelPromise - Promise for the kernel facade.
+ * @returns The rootKref of the bootstrap vat if launched, undefined if subcluster already exists.
  */
 async function startDefaultSubcluster(
   kernelPromise: Promise<KernelFacade>,
-): Promise<void> {
+): Promise<string | undefined> {
   const status = await E(kernelPromise).getStatus();
 
   if (status.subclusters.length === 0) {
     const result = await E(kernelPromise).launchSubcluster(defaultSubcluster);
     logger.info(`Default subcluster launched: ${JSON.stringify(result)}`);
-  } else {
-    logger.info('Subclusters already exist. Not launching default subcluster.');
+    return result.rootKref;
   }
+  logger.info('Subclusters already exist. Not launching default subcluster.');
+  return undefined;
+}
+
+/**
+ * Greets the bootstrap vat by calling its hello() method.
+ *
+ * @param rootKref - The kref of the bootstrap vat's root object.
+ */
+async function greetBootstrapVat(rootKref: string): Promise<void> {
+  const rootPresence = captp.resolveKref(rootKref) as {
+    hello: (from: string) => string;
+  };
+  const greeting = await E(rootPresence).hello('background');
+  logger.info(`Got greeting from bootstrap vat: ${greeting}`);
 }
 
 /**
@@ -178,7 +201,13 @@ function defineGlobals(): void {
       value: async () => kernelP,
     },
   });
-  harden(globalThis.kernel);
+
+  Object.defineProperty(globalThis, 'captp', {
+    configurable: false,
+    enumerable: true,
+    writable: false,
+    value: {},
+  });
 
   Object.defineProperty(globalThis, 'E', {
     value: E,

packages/extension/src/global.d.ts

@@ -1,4 +1,7 @@
-import type { KernelFacade } from '@metamask/kernel-browser-runtime';
+import type {
+  BackgroundKref,
+  KernelFacade,
+} from '@metamask/kernel-browser-runtime';
 
 // Type declarations for kernel dev console API.
 declare global {
@@ -17,6 +20,18 @@ declare global {
 
   // eslint-disable-next-line no-var
   var kernel: KernelFacade | Promise<KernelFacade>;
+
+  /**
+   * CapTP utilities for resolving krefs to E()-callable presences.
+   *
+   * @example
+   * ```typescript
+   * const alice = captp.resolveKref('ko1');
+   * await E(alice).hello('console');
+   * ```
+   */
+  // eslint-disable-next-line no-var
+  var captp: BackgroundKref;
 }
 
 export {};